Class Ed25519

Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.

Remarks

This method accepts a private key as a byte array (Uint8Array) for the Curve25519 curve in Twisted Edwards form and transforms it into a JWK object. The process involves first deriving the public key from the private key, then encoding both the private and public keys into base64url format.

The resulting JWK object includes the following properties:

• kty: Key Type, set to 'OKP' for Octet Key Pair.
• crv: Curve Name, set to 'Ed25519'.
• d: The private key component, base64url-encoded.
• x: The computed public key, base64url-encoded.

Example

const privateKeyBytes = new Uint8Array([...]); // Replace with actual private key bytes
const privateKey = await Ed25519.bytesToPrivateKey({ privateKeyBytes });
Copy

Converts a raw private key in bytes to its corresponding JSON Web Key (JWK) format.

Remarks

This method accepts a public key as a byte array (Uint8Array) for the Curve25519 curve in Twisted Edwards form and transforms it into a JWK object. The process involves encoding the public key bytes into base64url format.

The resulting JWK object includes the following properties:

• kty: Key Type, set to 'OKP' for Octet Key Pair.
• crv: Curve Name, set to 'X25519'.
• x: The public key, base64url-encoded.

Example

const publicKeyBytes = new Uint8Array([...]); // Replace with actual public key bytes
const publicKey = await X25519.bytesToPublicKey({ publicKeyBytes });
Copy

Derives the public key in JWK format from a given Ed25519 private key.

Remarks

This method takes a private key in JWK format and derives its corresponding public key, also in JWK format. The derivation process involves converting the private key to a raw byte array and then computing the corresponding public key on the Curve25519 curve in Twisted Edwards form. The public key is then encoded into base64url format to construct a JWK representation.

Example

const privateKey = { ... }; // A Jwk object representing an Ed25519 private key
const publicKey = await Ed25519.computePublicKey({ key: privateKey });
Copy

Converts an Ed25519 private key to its X25519 counterpart.

Remarks

This method enables the use of the same key pair for both digital signature (Ed25519) and key exchange (X25519) operations. It takes an Ed25519 private key and converts it to the corresponding X25519 format, facilitating interoperability between signing and encryption protocols.

Example

const ed25519PrivateKey = { ... }; // An Ed25519 private key in JWK format
const x25519PrivateKey = await Ed25519.convertPrivateKeyToX25519({
  privateKey: ed25519PrivateKey
});
Copy

Converts an Ed25519 public key to its X25519 counterpart.

Remarks

This method enables the use of the same key pair for both digital signature (Ed25519) and key exchange (X25519) operations. It takes an Ed25519 public key and converts it to the corresponding X25519 format, facilitating interoperability between signing and encryption protocols.

Example

const ed25519PublicKey = { ... }; // An Ed25519 public key in JWK format
const x25519PublicKey = await Ed25519.convertPublicKeyToX25519({
  publicKey: ed25519PublicKey
});
Copy

Generates an Ed25519 private key in JSON Web Key (JWK) format.

Remarks

This method creates a new private key suitable for use with the Curve25519 elliptic curve in Twisted Edwards form. The key generation process involves using cryptographically secure random number generation to ensure the uniqueness and security of the key. The resulting private key adheres to the JWK format making it compatible with common cryptographic standards and easy to use in various cryptographic processes.

The generated private key in JWK format includes the following components:

• kty: Key Type, set to 'OKP' for Octet Key Pair.
• crv: Curve Name, set to 'Ed25519'.
• d: The private key component, base64url-encoded.
• x: The derived public key, base64url-encoded.

Example

const privateKey = await Ed25519.generateKey();
Copy

Retrieves the public key properties from a given private key in JWK format.

Remarks

This method extracts the public key portion from an Ed25519 private key in JWK format. It does so by removing the private key property 'd' and making a shallow copy, effectively yielding the public key. The method sets the 'kid' (key ID) property using the JWK thumbprint if it is not already defined. This approach is used under the assumption that a private key in JWK format always contains the corresponding public key properties.

Note: This method offers a significant performance advantage, being about 100 times faster than computePublicKey(). However, it does not mathematically validate the private key, nor does it derive the public key from the private key. It simply extracts existing public key properties from the private key object. This makes it suitable for scenarios where speed is critical and the private key's integrity is already assured.

Example

const privateKey = { ... }; // A Jwk object representing an Ed25519 private key
const publicKey = await Ed25519.getPublicKey({ key: privateKey });
Copy

Converts a private key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).

Remarks

This method accepts a private key in JWK format and extracts its raw byte representation.

This method accepts a public key in JWK format and converts it into its raw binary form. The conversion process involves decoding the 'd' parameter of the JWK from base64url format into a byte array.

Example

const privateKey = { ... }; // An Ed25519 private key in JWK format
const privateKeyBytes = await Ed25519.privateKeyToBytes({ privateKey });
Copy

Converts a public key from JSON Web Key (JWK) format to a raw byte array (Uint8Array).

Remarks

This method accepts a public key in JWK format and converts it into its raw binary form. The conversion process involves decoding the 'x' parameter of the JWK (which represent the x coordinate of the elliptic curve point) from base64url format into a byte array.

Example

const publicKey = { ... }; // An Ed25519 public key in JWK format
const publicKeyBytes = await Ed25519.publicKeyToBytes({ publicKey });
Copy

Generates an RFC8032-compliant EdDSA signature of given data using an Ed25519 private key.

Remarks

This method signs the provided data with a specified private key using the EdDSA (Edwards-curve Digital Signature Algorithm) as defined in RFC8032. It involves converting the private key from JWK format to a byte array and then employing the Ed25519 algorithm to sign the data. The output is a digital signature in the form of a Uint8Array, uniquely corresponding to both the data and the private key used for signing.

Example

const data = new TextEncoder().encode('Messsage'); // Data to be signed
const privateKey = { ... }; // A Jwk object representing an Ed25519 private key
const signature = await Ed25519.sign({ key: privateKey, data });
Copy

Validates a given public key to confirm its mathematical correctness on the Edwards curve.

Remarks

This method decodes the Edwards points from the key bytes and asserts their validity on the Curve25519 curve in Twisted Edwards form. If the points are not valid, the method returns false. If the points are valid, the method returns true.

Note that this validation strictly pertains to the key's format and numerical validity; it does not assess whether the key corresponds to a known entity or its security status (e.g., whether it has been compromised).

Example

const publicKeyBytes = new Uint8Array([...]); // A public key in byte format
const isValid = await Ed25519.validatePublicKey({ publicKeyBytes });
console.log(isValid); // true if the key is valid on the Edwards curve, false otherwise
Copy

Verifies an RFC8032-compliant EdDSA signature against given data using an Ed25519 public key.

Remarks

This method validates a digital signature to ensure its authenticity and integrity. It uses the EdDSA (Edwards-curve Digital Signature Algorithm) as specified in RFC8032. The verification process involves converting the public key from JWK format to a raw byte array and using the Ed25519 algorithm to validate the signature against the provided data.

Example

const data = new TextEncoder().encode('Messsage'); // Data that was signed
const publicKey = { ... }; // A Jwk object representing an Ed25519 public key
const signature = new Uint8Array([...]); // Signature to verify
const isValid = await Ed25519.verify({ key: publicKey, signature, data });
console.log(isValid); // true if the signature is valid, false otherwise
Copy