libdecaf
Macros | Functions | Variables
ed255.h File Reference

A group of prime order p, based on Curve25519. More...

Go to the source code of this file.

Macros

#define DECAF_EDDSA_25519_PUBLIC_BYTES   32
 Number of bytes in an EdDSA public key.
 
#define DECAF_EDDSA_25519_PRIVATE_BYTES   DECAF_EDDSA_25519_PUBLIC_BYTES
 Number of bytes in an EdDSA private key.
 
#define DECAF_EDDSA_25519_SIGNATURE_BYTES   (DECAF_EDDSA_25519_PUBLIC_BYTES + DECAF_EDDSA_25519_PRIVATE_BYTES)
 Number of bytes in an EdDSA private key.
 
#define DECAF_EDDSA_25519_SUPPORTS_CONTEXTLESS_SIGS   1
 Does EdDSA support non-contextual signatures?
 
#define decaf_ed25519_prehash_ctx_s   decaf_sha512_ctx_s
 Prehash context (raw), because each EdDSA instance has a different prehash.
 
#define decaf_ed25519_prehash_ctx_t   decaf_sha512_ctx_t
 Prehash context, array[1] form.
 
#define decaf_ed25519_prehash_update   decaf_sha512_update
 Prehash update.
 
#define decaf_ed25519_prehash_destroy   decaf_sha512_destroy
 Prehash destroy.
 
#define DECAF_255_EDDSA_ENCODE_RATIO   4
 EdDSA encoding ratio.
 
#define DECAF_255_EDDSA_DECODE_RATIO   (8 / 4)
 EdDSA decoding ratio.
 
#define DECAF_EDDSA_NON_KEYPAIR_API_IS_DEPRECATED   0
 If 1, add deprecation attribute to non-keypair API functions. More...
 

Functions

void DECAF_API_VIS decaf_ed25519_derive_public_key (uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const uint8_t privkey[DECAF_EDDSA_25519_PRIVATE_BYTES]) DECAF_NONNULL DECAF_NOINLINE
 EdDSA key generation. More...
 
void DECAF_API_VIS decaf_ed25519_derive_keypair (decaf_eddsa_25519_keypair_t keypair, const uint8_t privkey[DECAF_EDDSA_25519_PRIVATE_BYTES]) DECAF_NONNULL DECAF_NOINLINE
 EdDSA keypair scheduling. More...
 
void DECAF_API_VIS decaf_ed25519_keypair_extract_public_key (uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const decaf_eddsa_25519_keypair_t keypair) DECAF_NONNULL DECAF_NOINLINE
 Extract the public key from an EdDSA keypair. More...
 
void DECAF_API_VIS decaf_ed25519_keypair_extract_private_key (uint8_t privkey[DECAF_EDDSA_25519_PRIVATE_BYTES], const decaf_eddsa_25519_keypair_t keypair) DECAF_NONNULL DECAF_NOINLINE
 Extract the private key from an EdDSA keypair. More...
 
void DECAF_API_VIS decaf_ed25519_keypair_destroy (decaf_eddsa_25519_keypair_t keypair) DECAF_NONNULL DECAF_NOINLINE
 EdDSA keypair destructor. More...
 
void DECAF_API_VIS decaf_ed25519_sign (uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const uint8_t privkey[DECAF_EDDSA_25519_PRIVATE_BYTES], const uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const uint8_t *message, size_t message_len, uint8_t prehashed, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signing. More...
 
void DECAF_API_VIS decaf_ed25519_sign_prehash (uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const uint8_t privkey[DECAF_EDDSA_25519_PRIVATE_BYTES], const uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const decaf_ed25519_prehash_ctx_t hash, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signing with prehash. More...
 
void DECAF_API_VIS decaf_ed25519_keypair_sign (uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const decaf_eddsa_25519_keypair_t keypair, const uint8_t *message, size_t message_len, uint8_t prehashed, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signing. More...
 
void DECAF_API_VIS decaf_ed25519_keypair_sign_prehash (uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const decaf_eddsa_25519_keypair_t keypair, const decaf_ed25519_prehash_ctx_t hash, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signing with prehash. More...
 
void DECAF_API_VIS decaf_ed25519_prehash_init (decaf_ed25519_prehash_ctx_t hash) DECAF_NOINLINE
 Prehash initialization, with contexts if supported. More...
 
decaf_error_t DECAF_API_VIS decaf_ed25519_verify (const uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const uint8_t *message, size_t message_len, uint8_t prehashed, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signature verification. More...
 
decaf_error_t DECAF_API_VIS decaf_ed25519_verify_prehash (const uint8_t signature[DECAF_EDDSA_25519_SIGNATURE_BYTES], const uint8_t pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES], const decaf_ed25519_prehash_ctx_t hash, const uint8_t *context, uint8_t context_len) DECAF_NOINLINE
 EdDSA signature verification. More...
 
void DECAF_API_VIS decaf_255_point_mul_by_ratio_and_encode_like_eddsa (uint8_t enc[DECAF_EDDSA_25519_PUBLIC_BYTES], const decaf_255_point_t p) DECAF_NONNULL DECAF_NOINLINE
 EdDSA point encoding. More...
 
decaf_error_t DECAF_API_VIS decaf_255_point_decode_like_eddsa_and_mul_by_ratio (decaf_255_point_t p, const uint8_t enc[DECAF_EDDSA_25519_PUBLIC_BYTES]) DECAF_NONNULL DECAF_NOINLINE
 EdDSA point decoding. More...
 
void DECAF_API_VIS decaf_ed25519_convert_public_key_to_x25519 (uint8_t x[DECAF_X25519_PUBLIC_BYTES], const uint8_t ed[DECAF_EDDSA_25519_PUBLIC_BYTES]) DECAF_NONNULL DECAF_NOINLINE
 EdDSA to ECDH public key conversion Deserialize the point to get y on Edwards curve, Convert it to u coordinate on Montgomery curve. More...
 
void DECAF_API_VIS decaf_ed25519_convert_private_key_to_x25519 (uint8_t x[DECAF_X25519_PRIVATE_BYTES], const uint8_t ed[DECAF_EDDSA_25519_PRIVATE_BYTES]) DECAF_NONNULL DECAF_NOINLINE
 EdDSA to ECDH private key conversion Using the appropriate hash function, hash the EdDSA private key and keep only the lower bytes to get the ECDH private key. More...
 

Variables

const DECAF_API_VIS uint8_t *const DECAF_ED25519_NO_CONTEXT
 

Detailed Description

A group of prime order p, based on Curve25519.

Author
Mike Hamburg
Warning
This file was automatically generated in Python. Please do not edit it.

Macro Definition Documentation

◆ DECAF_EDDSA_NON_KEYPAIR_API_IS_DEPRECATED

#define DECAF_EDDSA_NON_KEYPAIR_API_IS_DEPRECATED   0

If 1, add deprecation attribute to non-keypair API functions.

For now, deprecate in Doxygen only.

Function Documentation

◆ decaf_255_point_decode_like_eddsa_and_mul_by_ratio()

decaf_error_t DECAF_API_VIS decaf_255_point_decode_like_eddsa_and_mul_by_ratio ( decaf_255_point_t  p,
const uint8_t  enc[DECAF_EDDSA_25519_PUBLIC_BYTES] 
)

EdDSA point decoding.

Multiplies by DECAF_255_EDDSA_DECODE_RATIO, and ignores cofactor information.

See notes on decaf_255_point_mul_by_ratio_and_encode_like_eddsa

Parameters
[out]encThe encoded point.
[in]pThe point.

◆ decaf_255_point_mul_by_ratio_and_encode_like_eddsa()

void DECAF_API_VIS decaf_255_point_mul_by_ratio_and_encode_like_eddsa ( uint8_t  enc[DECAF_EDDSA_25519_PUBLIC_BYTES],
const decaf_255_point_t  p 
)

EdDSA point encoding.

Used internally, exposed externally. Multiplies by DECAF_255_EDDSA_ENCODE_RATIO first.

The multiplication is required because the EdDSA encoding represents the cofactor information, but the Decaf encoding ignores it (which is the whole point). So if you decode from EdDSA and re-encode to EdDSA, the cofactor info must get cleared, because the intermediate representation doesn't track it.

The way libdecaf handles this is to multiply by DECAF_255_EDDSA_DECODE_RATIO when decoding, and by DECAF_255_EDDSA_ENCODE_RATIO when encoding. The product of these ratios is always exactly the cofactor 8, so the cofactor ends up cleared one way or another. But exactly how that shakes out depends on the base points specified in RFC 8032.

The upshot is that if you pass the Decaf/Ristretto base point to this function, you will get DECAF_255_EDDSA_ENCODE_RATIO times the EdDSA base point.

Parameters
[out]encThe encoded point.
[in]pThe point.

◆ decaf_ed25519_convert_private_key_to_x25519()

void DECAF_API_VIS decaf_ed25519_convert_private_key_to_x25519 ( uint8_t  x[DECAF_X25519_PRIVATE_BYTES],
const uint8_t  ed[DECAF_EDDSA_25519_PRIVATE_BYTES] 
)

EdDSA to ECDH private key conversion Using the appropriate hash function, hash the EdDSA private key and keep only the lower bytes to get the ECDH private key.

Parameters
[out]xThe ECDH private key as in RFC7748
[in]edThe EdDSA private key

◆ decaf_ed25519_convert_public_key_to_x25519()

void DECAF_API_VIS decaf_ed25519_convert_public_key_to_x25519 ( uint8_t  x[DECAF_X25519_PUBLIC_BYTES],
const uint8_t  ed[DECAF_EDDSA_25519_PUBLIC_BYTES] 
)

EdDSA to ECDH public key conversion Deserialize the point to get y on Edwards curve, Convert it to u coordinate on Montgomery curve.

Warning
This function does not check that the public key being converted is a valid EdDSA public key (FUTURE?)
Parameters
[out]xThe ECDH public key as in RFC7748(point on Montgomery curve)
[in]edThe EdDSA public key(point on Edwards curve)

◆ decaf_ed25519_derive_keypair()

void DECAF_API_VIS decaf_ed25519_derive_keypair ( decaf_eddsa_25519_keypair_t  keypair,
const uint8_t  privkey[DECAF_EDDSA_25519_PRIVATE_BYTES] 
)

EdDSA keypair scheduling.

This is to add a safer version of the signing algorithm, where it is harder to use the wrong pubkey for your private key..

Parameters
[out]keypairThe scheduled keypair.
[in]privkeyThe private key.

◆ decaf_ed25519_derive_public_key()

void DECAF_API_VIS decaf_ed25519_derive_public_key ( uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const uint8_t  privkey[DECAF_EDDSA_25519_PRIVATE_BYTES] 
)

EdDSA key generation.

This function uses a different (non-Decaf) encoding.

Parameters
[out]pubkeyThe public key.
[in]privkeyThe private key.

◆ decaf_ed25519_keypair_destroy()

void DECAF_API_VIS decaf_ed25519_keypair_destroy ( decaf_eddsa_25519_keypair_t  keypair)

EdDSA keypair destructor.

Parameters
[in]pubkeyThe keypair.

◆ decaf_ed25519_keypair_extract_private_key()

void DECAF_API_VIS decaf_ed25519_keypair_extract_private_key ( uint8_t  privkey[DECAF_EDDSA_25519_PRIVATE_BYTES],
const decaf_eddsa_25519_keypair_t  keypair 
)

Extract the private key from an EdDSA keypair.

Parameters
[out]privkeyThe private key.
[in]keypairThe keypair.

◆ decaf_ed25519_keypair_extract_public_key()

void DECAF_API_VIS decaf_ed25519_keypair_extract_public_key ( uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const decaf_eddsa_25519_keypair_t  keypair 
)

Extract the public key from an EdDSA keypair.

Parameters
[out]pubkeyThe public key.
[in]keypairThe keypair.

◆ decaf_ed25519_keypair_sign()

void DECAF_API_VIS decaf_ed25519_keypair_sign ( uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const decaf_eddsa_25519_keypair_t  keypair,
const uint8_t *  message,
size_t  message_len,
uint8_t  prehashed,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signing.

Parameters
[out]signatureThe signature.
[in]keypairThe private and public key.
[in]messageThe message to sign.
[in]message_lenThe length of the message.
[in]prehashedNonzero if the message is actually the hash of something you want to sign.
[in]contextA "context" for this signature of up to 255 bytes.
[in]context_lenLength of the context.

◆ decaf_ed25519_keypair_sign_prehash()

void DECAF_API_VIS decaf_ed25519_keypair_sign_prehash ( uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const decaf_eddsa_25519_keypair_t  keypair,
const decaf_ed25519_prehash_ctx_t  hash,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signing with prehash.

Parameters
[out]signatureThe signature.
[in]keypairThe private and public key.
[in]hashThe hash of the message. This object will not be modified by the call.
[in]contextA "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
[in]context_lenLength of the context.

◆ decaf_ed25519_prehash_init()

void DECAF_API_VIS decaf_ed25519_prehash_init ( decaf_ed25519_prehash_ctx_t  hash)

Prehash initialization, with contexts if supported.

Parameters
[out]hashThe hash object to be initialized.

◆ decaf_ed25519_sign()

void DECAF_API_VIS decaf_ed25519_sign ( uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const uint8_t  privkey[DECAF_EDDSA_25519_PRIVATE_BYTES],
const uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const uint8_t *  message,
size_t  message_len,
uint8_t  prehashed,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signing.

However, this API is deprecated because it isn't safe: if the wrong public key is passed, it would reveal the private key. Instead, this function checks that the public key is correct, and otherwise aborts.

Deprecated:
Use DECAF_API_VIS decaf_ed25519_keypair_sign instead.
Parameters
[out]signatureThe signature.
[in]privkeyThe private key.
[in]pubkeyThe public key.
[in]messageThe message to sign.
[in]message_lenThe length of the message.
[in]prehashedNonzero if the message is actually the hash of something you want to sign.
[in]contextA "context" for this signature of up to 255 bytes.
[in]context_lenLength of the context.
Warning
For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed messages, at least without some very careful protocol-level disambiguation. For Ed448 it is safe. The C++ wrapper is designed to make it harder to screw this up, but this C code gives you no seat belt.

◆ decaf_ed25519_sign_prehash()

void DECAF_API_VIS decaf_ed25519_sign_prehash ( uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const uint8_t  privkey[DECAF_EDDSA_25519_PRIVATE_BYTES],
const uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const decaf_ed25519_prehash_ctx_t  hash,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signing with prehash.

However, this API is deprecated because it isn't safe: if the wrong public key is passed, it would reveal the private key. Instead, this function checks that the public key is correct, and otherwise aborts.

Deprecated:
Use DECAF_API_VIS decaf_ed25519_keypair_sign_prehash instead.
Parameters
[out]signatureThe signature.
[in]privkeyThe private key.
[in]pubkeyThe public key.
[in]hashThe hash of the message. This object will not be modified by the call.
[in]contextA "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
[in]context_lenLength of the context.

◆ decaf_ed25519_verify()

decaf_error_t DECAF_API_VIS decaf_ed25519_verify ( const uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const uint8_t *  message,
size_t  message_len,
uint8_t  prehashed,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signature verification.

Uses the standard (i.e. less-strict) verification formula.

Parameters
[in]signatureThe signature.
[in]pubkeyThe public key.
[in]messageThe message to verify.
[in]message_lenThe length of the message.
[in]prehashedNonzero if the message is actually the hash of something you want to verify.
[in]contextA "context" for this signature of up to 255 bytes.
[in]context_lenLength of the context.
Warning
For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed messages, at least without some very careful protocol-level disambiguation. For Ed448 it is safe. The C++ wrapper is designed to make it harder to screw this up, but this C code gives you no seat belt.

◆ decaf_ed25519_verify_prehash()

decaf_error_t DECAF_API_VIS decaf_ed25519_verify_prehash ( const uint8_t  signature[DECAF_EDDSA_25519_SIGNATURE_BYTES],
const uint8_t  pubkey[DECAF_EDDSA_25519_PUBLIC_BYTES],
const decaf_ed25519_prehash_ctx_t  hash,
const uint8_t *  context,
uint8_t  context_len 
)

EdDSA signature verification.

Uses the standard (i.e. less-strict) verification formula.

Parameters
[in]signatureThe signature.
[in]pubkeyThe public key.
[in]hashThe hash of the message. This object will not be modified by the call.
[in]contextA "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
[in]context_lenLength of the context.
Warning
For Ed25519, it is unsafe to use the same key for both prehashed and non-prehashed messages, at least without some very careful protocol-level disambiguation. For Ed448 it is safe. The C++ wrapper is designed to make it harder to screw this up, but this C code gives you no seat belt.