Class X25519

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 X25519 elliptic curve 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 'X25519'.
• d: The private key component, base64url-encoded.
• x: The derived public key, base64url-encoded.

This method is useful for converting raw public keys into a standardized JSON format, facilitating their use in cryptographic operations and making them easy to share and store.

Example

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

Converts a raw public 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 X25519 elliptic curve and transforms it into a JWK object. The conversion 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.

This method is useful for converting raw public keys into a standardized JSON format, facilitating their use in cryptographic operations and making them easy to share and store.

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 X25519 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. The public key is then encoded into base64url format to construct a JWK representation.

The process ensures that the derived public key correctly corresponds to the given private key, adhering to the Curve25519 elliptic curve in Twisted Edwards form standards. This method is useful in cryptographic operations where a public key is needed for operations like signature verification, but only the private key is available.

Example

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

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

Remarks

This method creates a new private key suitable for use with the X25519 elliptic curve. 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 'X25519'.
• d: The private key component, base64url-encoded.
• x: The derived public key, base64url-encoded.

The key is returned in a format suitable for direct use in key agreement operations.

Example

const privateKey = await X25519.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 X25519 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 500 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 X25519 private key
const publicKey = await X25519.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.

This conversion is essential for operations that require the private key in its raw binary form, such as certain low-level cryptographic operations or when interfacing with systems and libraries that expect keys in a byte array format.

Example

const privateKey = { ... }; // An X25519 private key in JWK format
const privateKeyBytes = await X25519.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.

This conversion is essential for operations that require the public key in its raw binary form, such as certain low-level cryptographic operations or when interfacing with systems and libraries that expect keys in a byte array format.

Example

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

Computes an RFC6090-compliant Elliptic Curve Diffie-Hellman (ECDH) shared secret using secp256k1 private and public keys in JSON Web Key (JWK) format.

Remarks

This method facilitates the ECDH key agreement protocol, which is a method of securely deriving a shared secret between two parties based on their private and public keys. It takes the private key of one party (privateKeyA) and the public key of another party (publicKeyB) to compute a shared secret. The shared secret is derived from the x-coordinate of the elliptic curve point resulting from the multiplication of the public key with the private key.

Note: When performing Elliptic Curve Diffie-Hellman (ECDH) key agreement, the resulting shared secret is a point on the elliptic curve, which consists of an x-coordinate and a y-coordinate. With a 256-bit curve like secp256k1, each of these coordinates is 32 bytes (256 bits) long. However, in the ECDH process, it's standard practice to use only the x-coordinate of the shared secret point as the resulting shared key. This is because the y-coordinate does not add to the entropy of the key, and both parties can independently compute the x-coordinate. Consquently, this implementation omits the y-coordinate for simplicity and standard compliance.

Example

const privateKeyA = { ... }; // A Jwk object for party A
const publicKeyB = { ... }; // A PublicKeyJwk object for party B
const sharedSecret = await Secp256k1.sharedSecret({
  privateKeyA,
  publicKeyB
});
Copy