Class Secp256r1

Adjusts an ECDSA signature to a normalized, low-S form.

Remarks

All ECDSA signatures, regardless of the curve, consist of two components, r and s, both of which are integers. The curve's order (the total number of points on the curve) is denoted by n. In a valid ECDSA signature, both r and s must be in the range [1, n-1]. However, due to the mathematical properties of ECDSA, if (r, s) is a valid signature, then (r, n - s) is also a valid signature for the same message and public key. In other words, for every signature, there's a "mirror" signature that's equally valid. For these elliptic curves:

• Low S Signature: A signature where the s component is in the lower half of the range, specifically less than or equal to n/2.

• High S Signature: This is where the s component is in the upper half of the range, greater than n/2.

The practical implication is that a third-party can forge a second valid signature for the same message by negating the s component of the original signature, without any knowledge of the private key. This is known as a "signature malleability" attack.

This type of forgery is not a problem in all systems, but it can be an issue in systems that rely on digital signature uniqueness to ensure transaction integrity. For example, in Bitcoin, transaction malleability is an issue because it allows for the modification of transaction identifiers (and potentially, transactions themselves) after they're signed but before they're confirmed in a block. By enforcing low s values, the Bitcoin network reduces the likelihood of this occurring, making the system more secure and predictable.

For this reason, it's common practice to normalize ECDSA signatures to a low-S form. This form is considered standard and preferable in some systems and is known as the "normalized" form of the signature.

This method takes a signature, and if it's high-S, returns the normalized low-S form. If the signature is already low-S, it's returned unmodified. It's important to note that this method does not change the validity of the signature but makes it compliant with systems that enforce low-S signatures.

Example

const signature = new Uint8Array([...]); // Your ECDSA signature
const adjustedSignature = await Secp256r1.adjustSignatureToLowS({ signature });
// Now 'adjustedSignature' is in the low-S form.
Copy

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

Remarks

This method takes a private key represented as a byte array (Uint8Array) and converts it into a JWK object. The conversion involves extracting the elliptic curve point (x and y coordinates) from the private key and encoding them into base64url format, alongside other JWK parameters.

The resulting JWK object includes the following properties:

• kty: Key Type, set to 'EC' for Elliptic Curve.
• crv: Curve Name, set to 'P-256'.
• d: The private key component, base64url-encoded.
• x: The x-coordinate of the public key point, base64url-encoded.
• y: The y-coordinate of the public key point, 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 Secp256r1.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 in a byte array (Uint8Array) format and transforms it to a JWK object. It involves decoding the elliptic curve point (x and y coordinates) from the raw public key bytes and encoding them into base64url format, along with setting appropriate JWK parameters.

The resulting JWK object includes the following properties:

• kty: Key Type, set to 'EC' for Elliptic Curve.
• crv: Curve Name, set to 'P-256'.
• x: The x-coordinate of the public key point, base64url-encoded.
• y: The y-coordinate of the public key point, 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 Secp256r1.bytesToPublicKey({ publicKeyBytes });
Copy

Converts a public key to its compressed form.

Remarks

This method takes a public key represented as a byte array and compresses it. Public key compression is a process that reduces the size of the public key by removing the y-coordinate, making it more efficient for storage and transmission. The compressed key retains the same level of security as the uncompressed key.

Example

const uncompressedPublicKeyBytes = new Uint8Array([...]); // Replace with actual uncompressed public key bytes
const compressedPublicKey = await Secp256r1.compressPublicKey({
  publicKeyBytes: uncompressedPublicKeyBytes
});
Copy

Derives the public key in JWK format from a given 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, then computing the elliptic curve point (x and y coordinates) from this private key. These coordinates are then encoded into base64url format to construct the public key in JWK format.

The process ensures that the derived public key correctly corresponds to the given private key, adhering to the secp256r1 elliptic curve 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 a secp256r1 private key
const publicKey = await Secp256r1.computePublicKey({ key: privateKey });
Copy

Converts an ASN.1 DER encoded ECDSA signature to a compact R+S format.

Remarks

This method is used for converting an ECDSA signature from the ASN.1 DER encoding to the more compact R+S format. This conversion is often required when dealing with ECDSA signatures in certain cryptographic standards such as JWS (JSON Web Signature).

The method decodes the DER-encoded signature, extracts the R and S values, and concatenates them into a single byte array. This process involves handling the ASN.1 structure to correctly parse the R and S values, considering padding and integer encoding specifics of DER.

Example

const derSignature = new Uint8Array([...]); // Replace with your DER-encoded signature
const signature = await Secp256r1.convertDerToCompactSignature({ derSignature });
Copy

Converts a public key to its uncompressed form.

Remarks

This method takes a compressed public key represented as a byte array and decompresses it. Public key decompression involves reconstructing the y-coordinate from the x-coordinate, resulting in the full public key. This method is used when the uncompressed key format is required for certain cryptographic operations or interoperability.

Example

const compressedPublicKeyBytes = new Uint8Array([...]); // Replace with actual compressed public key bytes
const decompressedPublicKey = await Secp256r1.decompressPublicKey({
  publicKeyBytes: compressedPublicKeyBytes
});
Copy

Generates a secp256r1 private key in JSON Web Key (JWK) format.

Remarks

This method creates a new private key suitable for use with the secp256r1 elliptic curve. The key is generated using cryptographically secure random number generation to ensure its uniqueness and security. The resulting private key adheres to the JWK format, specifically tailored for secp256r1, making it compatible with common cryptographic standards and easy to use in various cryptographic processes.

The private key generated by this method includes the following components:

• kty: Key Type, set to 'EC' for Elliptic Curve.
• crv: Curve Name, set to 'P-256'.
• d: The private key component, base64url-encoded.
• x: The x-coordinate of the public key point, derived from the private key, base64url-encoded.
• y: The y-coordinate of the public key point, derived from the private key, base64url-encoded.

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

Example

const privateKey = await Secp256r1.generateKey();
Copy

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

Remarks

This method extracts the public key portion from a secp256r1 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 200 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 a secp256r1 private key
const publicKey = await Secp256r1.getPublicKey({ key: privateKey });
Copy

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

Remarks

This method takes a private key in JWK format and extracts its raw byte representation. It specifically focuses on the 'd' parameter of the JWK, which represents the private key component in base64url encoding. The method decodes this value 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 Secp256r1.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' and 'y' parameters of the JWK (which represent the x and y coordinates of the elliptic curve point, respectively) from base64url format into a byte array. The method then concatenates these values, along with a prefix indicating the key format, to form the full public key.

This function is particularly useful for use cases where the public key is needed in its raw byte format, such as for certain cryptographic operations or when interfacing with systems that require raw key formats.

Example

const publicKey = { ... }; // A Jwk public key object
const publicKeyBytes = await Secp256r1.publicKeyToBytes({ publicKey });
Copy

Computes an RFC6090-compliant Elliptic Curve Diffie-Hellman (ECDH) shared secret using secp256r1 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 secp256r1, 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 private key object for party A
const publicKeyB = { ... }; // A Jwk public key object for party B
const sharedSecret = await Secp256r1.sharedSecret({
  privateKeyA,
  publicKeyB
});
Copy

Generates an RFC6979-compliant ECDSA signature of given data using a secp256r1 private key.

Remarks

This method signs the provided data with a specified private key using the ECDSA (Elliptic Curve Digital Signature Algorithm) signature algorithm, as defined in RFC6979. The data to be signed is first hashed using the SHA-256 algorithm, and this hash is then signed using the private key. The output is a digital signature in the form of a Uint8Array, which uniquely corresponds to both the data and the private key used for signing.

This method is commonly used in cryptographic applications to ensure data integrity and authenticity. The signature can later be verified by parties with access to the corresponding public key, ensuring that the data has not been tampered with and was indeed signed by the holder of the private key.

Example

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

Validates a given private key to ensure its compliance with the secp256r1 curve standards.

Remarks

This method checks whether a provided private key is a valid 32-byte number and falls within the range defined by the secp256r1 curve's order. It is essential for ensuring the private key's mathematical correctness in the context of secp256r1-based cryptographic operations.

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 privateKeyBytes = new Uint8Array([...]); // A 32-byte private key
const isValid = await Secp256r1.validatePrivateKey({ privateKeyBytes });
console.log(isValid); // true or false based on the key's validity
Copy

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

Remarks

This method checks if the provided public key represents a valid point on the secp256r1 curve. It decodes the key's Weierstrass points (x and y coordinates) and verifies their validity against the curve's parameters. A valid point must lie on the curve and meet specific mathematical criteria defined by the curve's equation.

It's important to note that this method does not verify the key's ownership or whether it has been compromised; it solely focuses on the key's adherence to the curve's mathematical principles.

Example

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

Verifies an RFC6979-compliant ECDSA signature against given data and a secp256r1 public key.

Remarks

This method validates a digital signature to ensure that it was generated by the holder of the corresponding private key and that the signed data has not been altered. The signature verification is performed using the ECDSA (Elliptic Curve Digital Signature Algorithm) as specified in RFC6979. The data to be verified is first hashed using the SHA-256 algorithm, and this hash is then used along with the public key to verify the signature.

The method returns a boolean value indicating whether the signature is valid. A valid signature proves that the signed data was indeed signed by the owner of the private key corresponding to the provided public key and that the data has not been tampered with since it was signed.

Note: The verification process does not consider the malleability of low-s signatures, which may be relevant in certain contexts, such as Bitcoin transactions.

Example

const data = new TextEncoder().encode('Messsage'); // Data that was signed
const publicKey = { ... }; // Public key in JWK format corresponding to the private key that signed the data
const signature = new Uint8Array([...]); // Signature to verify
const isSignatureValid = await Secp256r1.verify({
  key: publicKey,
  signature,
  data
});
console.log(isSignatureValid); // true if the signature is valid, false otherwise
Copy