package hacl-star

  1. Overview
  2. Docs
package hacl-star
Legend:
Library
Module
Module type
Parameter
Class
Class type

ECDSA on the K-256 curve

Buffers have the following size constraints:

Point representation and conversions

Elliptic curve points have two 32-byte coordinates (x, y) and can be represented in 3 ways:

  • "raw" form (64 bytes): the concatenation of the 2 coordinates x || y
  • "compressed" form (33 bytes): the first byte is equal to 0x02 + (y % 2), followed by x
  • "uncompressed" form (65 bytes): the first byte is 0x04, followed by the "raw" form

These functions convert points between these representations:

val raw_to_compressed : bytes -> bytes

raw_to_compressed p converts a "raw" point p (64 bytes) to a "compressed" point (33 bytes).

val raw_to_uncompressed : bytes -> bytes

raw_to_uncompressed p converts a "raw" point p (64 bytes) to an "uncompressed" point (65 bytes).

val compressed_to_raw : bytes -> bytes option

compressed_to_raw p attempts to convert a "compressed" point p (33 bytes) to a "raw" point (64 bytes) and returns it if successful.

val uncompressed_to_raw : bytes -> bytes option

uncompressed_to_raw p attempts to convert an "uncompressed" point p (65 bytes) to a "raw" point (64 bytes) and returns it if successful.

Point validation

val valid_sk : sk:bytes -> bool

valid_sk sk checks if the contents of sk can be used as a secret key or as a signing secret. This is the case if:

  • sk is 32 bytes long
  • 0 < sk < the order of the curve
val valid_pk : pk:bytes -> bool

valid_pk pk checks if the contents of pk is a valid public key. This is the case if:

  • pk is 64 bytes long (it is in the "raw" form)
  • the first 32 bytes encode x and the last 32 bytes encode y such that (x, y) is on the curve and both x and y are greater than 0 and less than the order of the curve

ECDSA

ECDSA signing and signature verification functions

For the sign and verify functions included in this module, msg is the 32-byte digest of the message to be signed, requiring users to use a cryptographic hash function of their choosing before calling them.

val secret_to_public : sk:bytes -> bytes option

secret_to_public sk checks if sk is a valid secret key and, if it is, returns its corresponding public key.

val sign : sk:bytes -> msg:bytes -> k:bytes -> bytes option

sign sk msg k attempts to sign the message msg with secret key sk and signing secret k and returns the signature if successful.

val verify : pk:bytes -> msg:bytes -> signature:bytes -> bool

verify pk msg signature checks the signature of msg using public key pk and returns true if it is valid.

module Libsecp256k1 : sig ... end

Versions of the ECDSA functions which work on low-S normalized signatures. These functions can be used when compatibility with libsecp256k1 is required.

module Noalloc : sig ... end

Versions of these functions which write their output in a buffer passed in as an argument