P-256

Bindings for ECDSA secp256r1.

Danger

The nonce MUST be unique per invocation with the same key, MUST NOT be communicated, MUST NOT be predicable, and MUST be uniformally distributed. Failure to meet those requirements makes it trivial to find the key.

RFC 6979 gives guidance to safely generate nonces for ECDSA, section 3.3 describes how to use pyhacl.drbg.DRBGRandom.

Note

ECDSA signatures are often serialiazed using the following ASN.1 structure:

Dss-Sig-Value  ::=  SEQUENCE  {
  r       INTEGER,
  s       INTEGER  }

HACL* has no utility to encode or decode this structure, it instead uses the raw 32 bytes r and s integers.

pyhacl.signature.p256.sign_sha2(message: bytes, private_key: bytes, nonce: bytes) → bytes

Hash message using SHA-256 and sign the digest.

Parameters:

  • message – The message (of any length) to be signed.

  • private_key – The private key that’ll sign the digest.

  • nonce – A unique, secret, unpredicable and uniformly distributed 32-bytes random value. See RFC 6979 for guidance.

Returns:

A 64-bytes signature that is the concatenation of 32-bytes R and 32-bytes S.

Raises:

  • ValueError – When the key or nonce has incorrect length.

  • HACLError – When the underlying C function failed to produce a signature, e.g. because the private key was invalid.

Binding for Hacl_P256_ecdsa_sign_p256_sha2.

pyhacl.signature.p256.sign_sha256(message: bytes, private_key: bytes, nonce: bytes) → bytes

Hash message using SHA-256 and sign the digest.

Parameters:

  • message – The message (of any length) to be signed.

  • private_key – The private key that’ll sign the digest.

  • nonce – A unique, secret, unpredicable and uniformly distributed 32-bytes random value. See RFC 6979 for guidance.

Returns:

A 64-bytes signature that is the concatenation of 32-bytes R and 32-bytes S.

Raises:

  • ValueError – When the key or nonce has incorrect length.

  • HACLError – When the underlying C function failed to produce a signature, e.g. because the private key was invalid.

Binding for Hacl_P256_ecdsa_sign_p256_sha2.

pyhacl.signature.p256.sign_sha384(message: bytes, private_key: bytes, nonce: bytes) → bytes

Hash message using SHA-384 and sign the digest.

Parameters:

  • message – The message (of any length) to be signed.

  • private_key – The private key that’ll sign the digest.

  • nonce – A unique, secret, unpredicable and uniformly distributed 32-bytes random value. See RFC 6979 for guidance.

Returns:

A 64-bytes signature that is the concatenation of 32-bytes R and 32-bytes S.

Raises:

  • ValueError – When the key or nonce has incorrect length.

  • HACLError – When the underlying C function failed to produce a signature, e.g. because the private key was invalid.

Binding for Hacl_P256_ecdsa_sign_p256_sha384.

pyhacl.signature.p256.sign_sha512(message: bytes, private_key: bytes, nonce: bytes) → bytes

Hash message using SHA-512 and sign the digest.

Parameters:

  • message – The message (of any length) to be signed.

  • private_key – The private key that’ll sign the digest.

  • nonce – A unique, secret, unpredicable and uniformly distributed 32-bytes random value. See RFC 6979 for guidance.

Returns:

A 64-bytes signature that is the concatenation of 32-bytes R and 32-bytes S.

Raises:

  • ValueError – When the key or nonce has incorrect length.

  • HACLError – When the underlying C function failed to produce a signature, e.g. because the private key was invalid.

Binding for Hacl_P256_ecdsa_sign_p256_sha512.

pyhacl.signature.p256.sign_without_hash(message: bytes, private_key: bytes, nonce: bytes) → bytes

Sign the message.

ECDSA is slow on long inputs so it is assumed that the message is somewhat short. The other sign_ functions are preferred if the input is long.

Warning

This function is only working on messages that are precisely 32 bytes long, see #1.

Parameters:

  • message – The short message to be signed.

  • private_key – The private key that’ll sign the message.

  • nonce – A unique, secret, unpredicable and uniformly distributed 32-bytes random value. See RFC 6979 for guidance.

Returns:

A 64-bytes signature that is the concatenation of 32-bytes R and 32-bytes S.

Raises:

  • ValueError – When the key or nonce has incorrect length.

  • HACLError – When the underlying C function failed to produce a signature, e.g. because the private key was invalid.

Binding for Hacl_P256_ecdsa_sign_p256_without_hash.

pyhacl.signature.p256.validate_private_key(private_key: bytes) → bool

Determine if the key is between 0 and the order of the curve.

Returns:

True when the key is valid; False otherwise.

Raises:

ValueError – When the key is not a 32-bytes point.

It uses Hacl_P256_validate_private_key.

pyhacl.signature.p256.validate_public_key(public_key: bytes) → bool

Determine if the public key is valid. See the documentation in HACL* for details.

Returns:

True when the key is valid; False otherwise.

Raises:

ValueError – When the key is not two concatenated 32-bytes points (64 bytes x || y).

It uses Hacl_P256_validate_public_key.

pyhacl.signature.p256.verif_sha2(message: bytes, public_key: bytes, signature: bytes) → bool

Verify that the signature matches the SHA-256 digest of the message.

Parameters:

  • message – The message (of any length) that is signed.

  • public_key – The public key counter part of the private key that was used to generate the signature.

  • signature – The signature of the message as the 64-bytes concatenation of 32-bytes R and 32-bytes S.

Returns:

True when the signature matches; False otherwise.

Raises:

ValueError – When the key or signature has incorrect length.

Binding for Hacl_P256_ecdsa_verif_p256_sha2.

pyhacl.signature.p256.verif_sha256(message: bytes, public_key: bytes, signature: bytes) → bool

Verify that the signature matches the SHA-256 digest of the message.

Parameters:

  • message – The message (of any length) that is signed.

  • public_key – The public key counter part of the private key that was used to generate the signature.

  • signature – The signature of the message as the 64-bytes concatenation of 32-bytes R and 32-bytes S.

Returns:

True when the signature matches; False otherwise.

Raises:

ValueError – When the key or signature has incorrect length.

Binding for Hacl_P256_ecdsa_verif_p256_sha2.

pyhacl.signature.p256.verif_sha384(message: bytes, public_key: bytes, signature: bytes) → bool

Verify that the signature matches the SHA-384 digest of the message.

Parameters:

  • message – The message (of any length) that is signed.

  • public_key – The public key counter part of the private key that was used to generate the signature.

  • signature – The signature of the message as the 64-bytes concatenation of 32-bytes R and 32-bytes S.

Returns:

True when the signature matches; False otherwise.

Raises:

ValueError – When the key or signature has incorrect length.

Binding for Hacl_P256_ecdsa_verif_p256_sha384.

pyhacl.signature.p256.verif_sha512(message: bytes, public_key: bytes, signature: bytes) → bool

Verify that the signature matches the SHA-512 digest of the message.

Parameters:

  • message – The message (of any length) that is signed.

  • public_key – The public key counter part of the private key that was used to generate the signature.

  • signature – The signature of the message as the 64-bytes concatenation of 32-bytes R and 32-bytes S.

Returns:

True when the signature matches; False otherwise.

Raises:

ValueError – When the key or signature has incorrect length.

Binding for Hacl_P256_ecdsa_verif_p256_sha512.

pyhacl.signature.p256.verif_without_hash(message: bytes, public_key: bytes, signature: bytes) → bool

Verify that the signature matches the message.

Warning

This function is only working on messages that are precisely 32 bytes long, see #1.

Parameters:

  • message – The message that is signed.

  • public_key – The public key counter part of the private key that was used to generate the signature.

  • signature – The signature of the message as the 64-bytes concatenation of 32-bytes R and 32-bytes S.

Returns:

True when the signature matches; False otherwise.

Raises:

ValueError – When the key or signature has incorrect length.

Binding for Hacl_P256_ecdsa_verif_p256_without_hash.