dilithium.h

All headers
  1. DILITHIUM_private_key
  2. DILITHIUM_public_key
  3. DILITHIUM_PRIVATE_KEY_BYTES
  4. DILITHIUM_PUBLIC_KEY_BYTES
  5. DILITHIUM_SIGNATURE_BYTES
  6. DILITHIUM_generate_key
  7. DILITHIUM_sign
  8. DILITHIUM_verify
  9. Serialisation of keys
  10. DILITHIUM_marshal_public_key
  11. DILITHIUM_parse_public_key
  12. DILITHIUM_marshal_private_key
  13. DILITHIUM_parse_private_key
#if defined(OPENSSL_UNSTABLE_EXPERIMENTAL_DILITHIUM)

This header implements experimental, draft versions of not-yet-standardized primitives. When the standard is complete, these functions will be removed and replaced with the final, incompatible standard version. They are available now for short-lived experiments, but must not be deployed anywhere durable, such as a long-lived key store. To use these functions define OPENSSL_UNSTABLE_EXPERIMENTAL_DILITHIUM.

Dilithium3.

DILITHIUM_private_key contains a Dilithium3 private key. The contents of this object should never leave the address space since the format is unstable.

struct DILITHIUM_private_key {
  union {
    uint8_t bytes[32 + 32 + 64 + 256 * 4 * (5 + 6 + 6)];
    uint32_t alignment;
  } opaque;
};

DILITHIUM_public_key contains a Dilithium3 public key. The contents of this object should never leave the address space since the format is unstable.

struct DILITHIUM_public_key {
  union {
    uint8_t bytes[32 + 64 + 256 * 4 * 6];
    uint32_t alignment;
  } opaque;
};

DILITHIUM_PRIVATE_KEY_BYTES is the number of bytes in an encoded Dilithium3 private key.

#define DILITHIUM_PRIVATE_KEY_BYTES 4032

DILITHIUM_PUBLIC_KEY_BYTES is the number of bytes in an encoded Dilithium3 public key.

#define DILITHIUM_PUBLIC_KEY_BYTES 1952

DILITHIUM_SIGNATURE_BYTES is the number of bytes in an encoded Dilithium3 signature.

#define DILITHIUM_SIGNATURE_BYTES 3309

DILITHIUM_generate_key generates a random public/private key pair, writes the encoded public key to out_encoded_public_key and sets out_private_key to the private key. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int DILITHIUM_generate_key(
    uint8_t out_encoded_public_key[DILITHIUM_PUBLIC_KEY_BYTES],
    struct DILITHIUM_private_key *out_private_key);

DILITHIUM_sign generates a signature for the message msg of length msg_len using private_key following the randomized algorithm, and writes the encoded signature to out_encoded_signature. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int DILITHIUM_sign(
    uint8_t out_encoded_signature[DILITHIUM_SIGNATURE_BYTES],
    const struct DILITHIUM_private_key *private_key, const uint8_t *msg,
    size_t msg_len);

DILITHIUM_verify verifies that encoded_signature constitutes a valid signature for the message msg of length msg_len using public_key.

OPENSSL_EXPORT int DILITHIUM_verify(
    const struct DILITHIUM_public_key *public_key,
    const uint8_t encoded_signature[DILITHIUM_SIGNATURE_BYTES],
    const uint8_t *msg, size_t msg_len);

Serialisation of keys.

DILITHIUM_marshal_public_key serializes public_key to out in the standard format for Dilithium public keys. It returns one on success or zero on allocation error.

OPENSSL_EXPORT int DILITHIUM_marshal_public_key(
    CBB *out, const struct DILITHIUM_public_key *public_key);

DILITHIUM_parse_public_key parses a public key, in the format generated by DILITHIUM_marshal_public_key, from in and writes the result to out_public_key. It returns one on success or zero on parse error or if there are trailing bytes in in.

OPENSSL_EXPORT int DILITHIUM_parse_public_key(
    struct DILITHIUM_public_key *public_key, CBS *in);

DILITHIUM_marshal_private_key serializes private_key to out in the standard format for Dilithium private keys. It returns one on success or zero on allocation error.

OPENSSL_EXPORT int DILITHIUM_marshal_private_key(
    CBB *out, const struct DILITHIUM_private_key *private_key);

DILITHIUM_parse_private_key parses a private key, in the format generated by DILITHIUM_marshal_private_key, from in and writes the result to out_private_key. It returns one on success or zero on parse error or if there are trailing bytes in in.

OPENSSL_EXPORT int DILITHIUM_parse_private_key(
    struct DILITHIUM_private_key *private_key, CBS *in);
#endif  // OPENSSL_UNSTABLE_EXPERIMENTAL_DILITHIUM