Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add X25519 key and verification method support #735

Merged
merged 20 commits into from
Mar 22, 2022
Merged

Add X25519 key and verification method support #735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
b6b30ff
Add X25519 key type
cycraig Mar 20, 2022
59543e5
Add X25519KeyAgreementKey2019
cycraig Mar 21, 2022
38069e8
changelog and versions (#737)
github-actions[bot] Mar 21, 2022
dcaf8ac
Update Wasm bindings, add key exchange example
cycraig Mar 21, 2022
ad1ab21
Merge branch 'dev' of https://github.com/iotaledger/identity.rs into …
cycraig Mar 21, 2022
6ca5b90
Fix Wasm keyExchange example
cycraig Mar 21, 2022
849133c
Fix formatting
cycraig Mar 21, 2022
498e20d
Fix compilation after rename
cycraig Mar 21, 2022
49d7405
Rename MethodData key_type -> type_, key_data -> data
cycraig Mar 21, 2022
309aea5
Fix Wasm test command
cycraig Mar 21, 2022
8247770
Add key exchange web example
cycraig Mar 21, 2022
4cf6f3f
Remove KeyPair::new_ed25519, redundant
cycraig Mar 21, 2022
a939561
Replace KeyPair::try_from_ed25519_bytes with
cycraig Mar 21, 2022
8797c7b
Fix clippy, fmt
cycraig Mar 21, 2022
ce58b21
Add WasmKeyPair.tryFromPrivateKeyBytes
cycraig Mar 22, 2022
a0162ea
Apply suggestions from code review
cycraig Mar 22, 2022
de59656
Merge branch 'dev' of https://github.com/iotaledger/identity.rs into …
cycraig Mar 22, 2022
f2c6f15
Remove MethodType u32 representation to avoid breaking changes from
cycraig Mar 22, 2022
a5d7427
Remove KeyExchange trait, add Ed25519 to X25519 conversion
cycraig Mar 22, 2022
52c3122
Fix toml formatting
cycraig Mar 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions bindings/wasm/cypress/integration/keyExchange.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import {
keyExchange,
defaultClientConfig,
initIdentity,
} from '../../examples/dist/web'

describe(
"keyExchange",
{
defaultCommandTimeout: 1000*60*3, // 3 minutes to account for spurious network delays
},
() => {
before(async () => {
// The working directory is under __cypress at test runtime, so we need to go up one more level than usual
await initIdentity('../../../examples/dist/identity_wasm_bg.wasm');

// NOTE: `cy.wrap(defaultClientConfig()).as('config')` does not always work to make the config available
// from the shared context as `this.config` because it has a race condition with initializing the wasm.
// So call `defaultClientConfig()` manually for now.
});
it("Key Exchange", async () => {
await keyExchange(defaultClientConfig());
});
}
);
217 changes: 169 additions & 48 deletions bindings/wasm/docs/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ the configuration of previously built accounts.</p>
<dd></dd>
<dt><a href="#KeyPair">KeyPair</a></dt>
<dd></dd>
<dt><a href="#MethodData">MethodData</a></dt>
<dd><p>Supported verification method data formats.</p>
</dd>
<dt><a href="#MethodScope">MethodScope</a></dt>
<dd><p>Supported verification method types.</p>
</dd>
Expand Down Expand Up @@ -116,13 +119,14 @@ See <code>ISignatureOptions</code>.</p>
<dd><p>Holds additional signature verification options.
See <code>IVerifierOptions</code>.</p>
</dd>
<dt><a href="#X25519">X25519</a></dt>
<dd><p>An implementation of <code>X25519</code> Elliptic-curve Diffie-Hellman (ECDH) cryptographic key exchange.</p>
</dd>
</dl>

## Members

<dl>
<dt><a href="#KeyType">KeyType</a></dt>
<dd></dd>
<dt><a href="#MethodRelationship">MethodRelationship</a></dt>
<dd></dd>
<dt><a href="#SubjectHolderRelationship">SubjectHolderRelationship</a></dt>
Expand Down Expand Up @@ -152,6 +156,8 @@ This variant is the default used if no other variant is specified when construct
</dd>
<dt><a href="#Digest">Digest</a></dt>
<dd></dd>
<dt><a href="#KeyType">KeyType</a></dt>
<dd></dd>
<dt><a href="#DIDMessageEncoding">DIDMessageEncoding</a></dt>
<dd></dd>
</dl>
Expand All @@ -175,9 +181,8 @@ publishing to the Tangle.
**Kind**: global class

* [Account](#Account)
* [.deleteService(options)](#Account+deleteService) ⇒ <code>Promise.&lt;void&gt;</code>
* [.setAlsoKnownAs(options)](#Account+setAlsoKnownAs) ⇒ <code>Promise.&lt;void&gt;</code>
* [.setController(options)](#Account+setController) ⇒ <code>Promise.&lt;void&gt;</code>
* [.attachMethodRelationships(options)](#Account+attachMethodRelationships) ⇒ <code>Promise.&lt;void&gt;</code>
* [.detachMethodRelationships(options)](#Account+detachMethodRelationships) ⇒ <code>Promise.&lt;void&gt;</code>
* [.did()](#Account+did) ⇒ [<code>DID</code>](#DID)
* [.autopublish()](#Account+autopublish) ⇒ <code>boolean</code>
* [.autosave()](#Account+autosave) ⇒ [<code>AutoSave</code>](#AutoSave)
Expand All @@ -192,43 +197,36 @@ publishing to the Tangle.
* [.updateDocumentUnchecked(document)](#Account+updateDocumentUnchecked) ⇒ <code>Promise.&lt;void&gt;</code>
* [.fetchState()](#Account+fetchState) ⇒ <code>Promise.&lt;void&gt;</code>
* [.deleteMethod(options)](#Account+deleteMethod) ⇒ <code>Promise.&lt;void&gt;</code>
* [.deleteService(options)](#Account+deleteService) ⇒ <code>Promise.&lt;void&gt;</code>
* [.setAlsoKnownAs(options)](#Account+setAlsoKnownAs) ⇒ <code>Promise.&lt;void&gt;</code>
* [.setController(options)](#Account+setController) ⇒ <code>Promise.&lt;void&gt;</code>
* [.createMethod(options)](#Account+createMethod) ⇒ <code>Promise.&lt;void&gt;</code>
* [.createService(options)](#Account+createService) ⇒ <code>Promise.&lt;void&gt;</code>
* [.attachMethodRelationships(options)](#Account+attachMethodRelationships) ⇒ <code>Promise.&lt;void&gt;</code>
* [.detachMethodRelationships(options)](#Account+detachMethodRelationships) ⇒ <code>Promise.&lt;void&gt;</code>

<a name="Account+deleteService"></a>

### account.deleteService(options) ⇒ <code>Promise.&lt;void&gt;</code>
Deletes a Service if it exists.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>DeleteServiceOptions</code> |
<a name="Account+attachMethodRelationships"></a>

<a name="Account+setAlsoKnownAs"></a>
### account.attachMethodRelationships(options) ⇒ <code>Promise.&lt;void&gt;</code>
Attach one or more verification relationships to a method.

### account.setAlsoKnownAs(options) ⇒ <code>Promise.&lt;void&gt;</code>
Sets the `alsoKnownAs` property in the DID document.
Note: the method must exist and be in the set of verification methods;
it cannot be an embedded method.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>SetAlsoKnownAsOptions</code> |
| options | <code>AttachMethodRelationshipOptions</code> |

<a name="Account+setController"></a>
<a name="Account+detachMethodRelationships"></a>

### account.setController(options) ⇒ <code>Promise.&lt;void&gt;</code>
Sets the controllers of the DID document.
### account.detachMethodRelationships(options) ⇒ <code>Promise.&lt;void&gt;</code>
Detaches the given relationship from the given method, if the method exists.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>SetControllerOptions</code> |
| options | <code>DetachMethodRelationshipOptions</code> |

<a name="Account+did"></a>

Expand Down Expand Up @@ -368,52 +366,60 @@ Deletes a verification method if the method exists.
| --- | --- |
| options | <code>DeleteMethodOptions</code> |

<a name="Account+createMethod"></a>
<a name="Account+deleteService"></a>

### account.createMethod(options) ⇒ <code>Promise.&lt;void&gt;</code>
Adds a new verification method to the DID document.
### account.deleteService(options) ⇒ <code>Promise.&lt;void&gt;</code>
Deletes a Service if it exists.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>CreateMethodOptions</code> |
| options | <code>DeleteServiceOptions</code> |

<a name="Account+createService"></a>
<a name="Account+setAlsoKnownAs"></a>

### account.createService(options) ⇒ <code>Promise.&lt;void&gt;</code>
Adds a new Service to the DID Document.
### account.setAlsoKnownAs(options) ⇒ <code>Promise.&lt;void&gt;</code>
Sets the `alsoKnownAs` property in the DID document.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>CreateServiceOptions</code> |
| options | <code>SetAlsoKnownAsOptions</code> |

<a name="Account+attachMethodRelationships"></a>
<a name="Account+setController"></a>

### account.attachMethodRelationships(options) ⇒ <code>Promise.&lt;void&gt;</code>
Attach one or more verification relationships to a method.
### account.setController(options) ⇒ <code>Promise.&lt;void&gt;</code>
Sets the controllers of the DID document.

Note: the method must exist and be in the set of verification methods;
it cannot be an embedded method.
**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>SetControllerOptions</code> |

<a name="Account+createMethod"></a>

### account.createMethod(options) ⇒ <code>Promise.&lt;void&gt;</code>
Adds a new verification method to the DID document.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>AttachMethodRelationshipOptions</code> |
| options | <code>CreateMethodOptions</code> |

<a name="Account+detachMethodRelationships"></a>
<a name="Account+createService"></a>

### account.detachMethodRelationships(options) ⇒ <code>Promise.&lt;void&gt;</code>
Detaches the given relationship from the given method, if the method exists.
### account.createService(options) ⇒ <code>Promise.&lt;void&gt;</code>
Adds a new Service to the DID Document.

**Kind**: instance method of [<code>Account</code>](#Account)

| Param | Type |
| --- | --- |
| options | <code>DetachMethodRelationshipOptions</code> |
| options | <code>CreateServiceOptions</code> |

<a name="AccountBuilder"></a>

Expand Down Expand Up @@ -2564,6 +2570,7 @@ Deserializes a JSON object as `KeyLocation`.
* [.clone()](#KeyPair+clone) ⇒ [<code>KeyPair</code>](#KeyPair)
* _static_
* [.fromBase58(type_, public_key, private_key)](#KeyPair.fromBase58) ⇒ [<code>KeyPair</code>](#KeyPair)
* [.tryFromPrivateKeyBytes(keyType, privateKeyBytes)](#KeyPair.tryFromPrivateKeyBytes) ⇒ [<code>KeyPair</code>](#KeyPair)
* [.fromJSON(json)](#KeyPair.fromJSON) ⇒ [<code>KeyPair</code>](#KeyPair)

<a name="new_KeyPair_new"></a>
Expand Down Expand Up @@ -2619,6 +2626,22 @@ Parses a `KeyPair` object from base58-encoded public/private keys.
| public_key | <code>string</code> |
| private_key | <code>string</code> |

<a name="KeyPair.tryFromPrivateKeyBytes"></a>

### KeyPair.tryFromPrivateKeyBytes(keyType, privateKeyBytes) ⇒ [<code>KeyPair</code>](#KeyPair)
Reconstructs a `KeyPair` from the bytes of a private key.

The private key for `Ed25519` must be a 32-byte seed in compliance
with [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2).
Other implementations often use another format. See [this blog post](https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/) for further explanation.

**Kind**: static method of [<code>KeyPair</code>](#KeyPair)

| Param | Type |
| --- | --- |
| keyType | <code>number</code> |
| privateKeyBytes | <code>Uint8Array</code> |

<a name="KeyPair.fromJSON"></a>

### KeyPair.fromJSON(json) ⇒ [<code>KeyPair</code>](#KeyPair)
Expand All @@ -2630,6 +2653,80 @@ Deserializes a `KeyPair` object from a JSON object.
| --- | --- |
| json | <code>any</code> |

<a name="MethodData"></a>

## MethodData
Supported verification method data formats.

**Kind**: global class

* [MethodData](#MethodData)
* _instance_
* [.tryDecode()](#MethodData+tryDecode) ⇒ <code>Uint8Array</code>
* [.toJSON()](#MethodData+toJSON) ⇒ <code>any</code>
* [.clone()](#MethodData+clone) ⇒ [<code>MethodData</code>](#MethodData)
* _static_
* [.newBase58(data)](#MethodData.newBase58) ⇒ [<code>MethodData</code>](#MethodData)
* [.newMultibase(data)](#MethodData.newMultibase) ⇒ [<code>MethodData</code>](#MethodData)
* [.fromJSON(json)](#MethodData.fromJSON) ⇒ [<code>MethodData</code>](#MethodData)

<a name="MethodData+tryDecode"></a>

### methodData.tryDecode() ⇒ <code>Uint8Array</code>
Returns a `UInt8Array` containing the decoded bytes of the `MethodData`.

This is generally a public key identified by a `MethodData` value.

### Errors
Decoding can fail if `MethodData` has invalid content or cannot be
represented as a vector of bytes.

**Kind**: instance method of [<code>MethodData</code>](#MethodData)
<a name="MethodData+toJSON"></a>

### methodData.toJSON() ⇒ <code>any</code>
Serializes a `MethodData` object as a JSON object.

**Kind**: instance method of [<code>MethodData</code>](#MethodData)
<a name="MethodData+clone"></a>

### methodData.clone() ⇒ [<code>MethodData</code>](#MethodData)
Deep clones the object.

**Kind**: instance method of [<code>MethodData</code>](#MethodData)
<a name="MethodData.newBase58"></a>

### MethodData.newBase58(data) ⇒ [<code>MethodData</code>](#MethodData)
Creates a new `MethodData` variant with Base58-BTC encoded content.

**Kind**: static method of [<code>MethodData</code>](#MethodData)

| Param | Type |
| --- | --- |
| data | <code>Uint8Array</code> |

<a name="MethodData.newMultibase"></a>

### MethodData.newMultibase(data) ⇒ [<code>MethodData</code>](#MethodData)
Creates a new `MethodData` variant with Multibase-encoded content.

**Kind**: static method of [<code>MethodData</code>](#MethodData)

| Param | Type |
| --- | --- |
| data | <code>Uint8Array</code> |

<a name="MethodData.fromJSON"></a>

### MethodData.fromJSON(json) ⇒ [<code>MethodData</code>](#MethodData)
Deserializes a `MethodData` object from a JSON object.

**Kind**: static method of [<code>MethodData</code>](#MethodData)

| Param | Type |
| --- | --- |
| json | <code>any</code> |

<a name="MethodScope"></a>

## MethodScope
Expand Down Expand Up @@ -2769,6 +2866,7 @@ Supported verification method types.
* [.clone()](#MethodType+clone) ⇒ [<code>MethodType</code>](#MethodType)
* _static_
* [.Ed25519VerificationKey2018()](#MethodType.Ed25519VerificationKey2018) ⇒ [<code>MethodType</code>](#MethodType)
* [.X25519KeyAgreementKey2019()](#MethodType.X25519KeyAgreementKey2019) ⇒ [<code>MethodType</code>](#MethodType)
* [.MerkleKeyCollection2021()](#MethodType.MerkleKeyCollection2021) ⇒ [<code>MethodType</code>](#MethodType)
* [.fromJSON(json)](#MethodType.fromJSON) ⇒ [<code>MethodType</code>](#MethodType)

Expand All @@ -2788,6 +2886,10 @@ Deep clones the object.

### MethodType.Ed25519VerificationKey2018() ⇒ [<code>MethodType</code>](#MethodType)
**Kind**: static method of [<code>MethodType</code>](#MethodType)
<a name="MethodType.X25519KeyAgreementKey2019"></a>

### MethodType.X25519KeyAgreementKey2019() ⇒ [<code>MethodType</code>](#MethodType)
**Kind**: static method of [<code>MethodType</code>](#MethodType)
<a name="MethodType.MerkleKeyCollection2021"></a>

### MethodType.MerkleKeyCollection2021() ⇒ [<code>MethodType</code>](#MethodType)
Expand Down Expand Up @@ -3776,7 +3878,7 @@ Deserializes a `Timestamp` from a JSON object.
* [.controller()](#VerificationMethod+controller) ⇒ [<code>DID</code>](#DID)
* [.SetController(did)](#VerificationMethod+SetController)
* [.type()](#VerificationMethod+type) ⇒ <code>string</code>
* [.data()](#VerificationMethod+data) ⇒ <code>any</code>
* [.data()](#VerificationMethod+data) ⇒ [<code>MethodData</code>](#MethodData)
* [.toJSON()](#VerificationMethod+toJSON) ⇒ <code>any</code>
* [.clone()](#VerificationMethod+clone) ⇒ [<code>VerificationMethod</code>](#VerificationMethod)
* _static_
Expand Down Expand Up @@ -3828,7 +3930,7 @@ Returns a copy of the `VerificationMethod` type.
**Kind**: instance method of [<code>VerificationMethod</code>](#VerificationMethod)
<a name="VerificationMethod+data"></a>

### verificationMethod.data() ⇒ <code>any</code>
### verificationMethod.data() ⇒ [<code>MethodData</code>](#MethodData)
Returns a copy of the `VerificationMethod` public key data.

**Kind**: instance method of [<code>VerificationMethod</code>](#VerificationMethod)
Expand Down Expand Up @@ -3927,10 +4029,25 @@ Deserializes a `VerifierOptions` from a JSON object.
| --- | --- |
| json | <code>any</code> |

<a name="KeyType"></a>
<a name="X25519"></a>

## X25519
An implementation of `X25519` Elliptic-curve Diffie-Hellman (ECDH) cryptographic key exchange.

**Kind**: global class
<a name="X25519.keyExchange"></a>

### X25519.keyExchange(privateKey, publicKey) ⇒ <code>Uint8Array</code>
Performs a cryptographic key exchange process (e.g. Diffie-Hellman) using the private key
of the first party with with the public key of the second party, resulting in a shared secret.

**Kind**: static method of [<code>X25519</code>](#X25519)

| Param | Type |
| --- | --- |
| privateKey | <code>string</code> |
| publicKey | <code>Uint8Array</code> |

## KeyType
**Kind**: global variable
<a name="MethodRelationship"></a>

## MethodRelationship
Expand Down Expand Up @@ -3986,6 +4103,10 @@ Return after the first error occurs.

## Digest
**Kind**: global variable
<a name="KeyType"></a>

## KeyType
**Kind**: global variable
<a name="DIDMessageEncoding"></a>

## DIDMessageEncoding
Expand Down
Loading