Javascript library for generating and working with Ed25519VerificationKey2020 key pairs, for use with crypto-ld.
For use with:
crypto-ld
^5.0.0
.@digitalbazaar/ed25519-signature-2020
^2.1.0
crypto suite (with jsonld-signatures
^9.0.0
)@digitalbazaar/vc
^1.0.0
See also (related specs):
As with most security- and cryptography-related tools, the overall security of your system will largely depend on your design decisions.
To install locally (for development):
git clone https://github.com/digitalbazaar/ed25519-verification-key-2020.git
cd ed25519-verification-key-2020
npm install
To generate a new public/private key pair:
{string} [controller]
Optional controller URI or DID to initialize the
generated key. (This will also init the key id.) {string} [seed]
Optional deterministic seed value from which to generate the
key.import {Ed25519VerificationKey2020} from '@digitalbazaar/ed25519-verification-key-2020';
const edKeyPair = await Ed25519VerificationKey2020.generate();
To create an instance of a public/private key pair from data imported from
storage, use .from()
:
const serializedKeyPair = { ... };
const keyPair = await Ed25519VerificationKey2020.from(serializedKeyPair);
To export just the public key of a pair:
await keyPair.export({publicKey: true});
// ->
{
type: 'Ed25519VerificationKey2020',
id: 'did:example:1234#z6MkszZtxCmA2Ce4vUV132PCuLQmwnaDD5mw2L23fGNnsiX3',
controller: 'did:example:1234',
publicKeyMultibase: 'zEYJrMxWigf9boyeJMTRN4Ern8DJMoCXaLK77pzQmxVjf'
}
To export the full key pair, including private key (warning: this should be a carefully considered operation, best left to dedicated Key Management Systems):
await keyPair.export({publicKey: true, privateKey: true});
// ->
{
type: 'Ed25519VerificationKey2020',
id: 'did:example:1234#z6MkszZtxCmA2Ce4vUV132PCuLQmwnaDD5mw2L23fGNnsiX3',
controller: 'did:example:1234',
publicKeyMultibase: 'zEYJrMxWigf9boyeJMTRN4Ern8DJMoCXaLK77pzQmxVjf',
privateKeyMultibase: 'z4E7Q4neNHwv3pXUNzUjzc6TTYspqn9Aw6vakpRKpbVrCzwKWD4hQDHnxuhfrTaMjnR8BTp9NeUvJiwJoSUM6xHAZ'
}
To generate a fingerprint:
keyPair.fingerprint();
// ->
'z6MkszZtxCmA2Ce4vUV132PCuLQmwnaDD5mw2L23fGNnsiX3'
To verify a fingerprint:
const fingerprint = 'z6MkszZtxCmA2Ce4vUV132PCuLQmwnaDD5mw2L23fGNnsiX3';
keyPair.verifyFingerprint({fingerprint});
// ->
{valid: true}
In order to perform a cryptographic signature, you need to create a sign
function, and then invoke it.
const keyPair = Ed25519VerificationKey2020.generate();
const {sign} = keyPair.signer();
// data is a Uint8Array of bytes
const data = (new TextEncoder()).encode('test data goes here');
// Signing also outputs a Uint8Array, which you can serialize to text etc.
const signatureValueBytes = await sign({data});
In order to verify a cryptographic signature, you need to create a verify
function, and then invoke it (passing it the data to verify, and the signature).
const keyPair = Ed25519VerificationKey2020.generate();
const {verify} = keyPair.verifier();
const valid = await verify({data, signature});
// true
If you have serialized and stored keys of the previous
Ed25519VerificationKey2018
key type (for example, generated using
the ed25519-verification-key-2018
)
library, or using the Ed25519KeyPair
keys bundled with crypto-ld v3.x
),
things to keep in mind:
publicKeyBase58
and privateKeyBase58
properties,
and the 2020 suite key (this repo) serializes using corresponding
publicKeyMultibase
and privateKeyMultibase
property.Ed25519VerificationKey2020.fromEd25519VerificationKey2018()
method (see below).generate()
the same key material, given the same seed
parameter.Example of converting:
import {Ed25519VerificationKey2018}
from '@digitalbazaar/ed25519-verification-key-2018';
import {Ed25519VerificationKey2020}
from '@digitalbazaar/ed25519-verification-key-2020';
const keyPair2018 = await Ed25519VerificationKey2018.generate({
controller: 'did:example:1234'
});
const keyPair2020 = await Ed25519VerificationKey2020
.fromEd25519VerificationKey2018({keyPair: keyPair2018});
// The resulting keyPair2020 will have the same `id` and `controller` properties
// as its 2018 source. They will also produce and verify the same signatures.
// data is a Uint8Array of bytes
const data = (new TextEncoder()).encode('test data goes here');
const signatureBytes2018 = await keyPair2018.signer().sign({data});
// this is the same signature as that produced by the 2020 key. And will verify
// the same.
await keyPair2020.verifier().verify({data, signature: signatureBytes2018})
// true
See the contribute file!
PRs accepted.
If editing the Readme, please conform to the standard-readme specification.
Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com
New BSD License (3-clause) © 2020 Digital Bazaar