Loading...
Searching...
No Matches
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 1
| If 1, add deprecation attribute to non-keypair API functions.

## 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.
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.
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.
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.
void DECAF_API_VIS | decaf_ed25519_keypair_destroy (decaf_eddsa_25519_keypair_t keypair) DECAF_NONNULL DECAF_NOINLINE
| EdDSA keypair destructor.
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.
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.
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.
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.
void DECAF_API_VIS | decaf_ed25519_prehash_init (decaf_ed25519_prehash_ctx_t hash) DECAF_NOINLINE
| Prehash initialization, with contexts if supported.
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.
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.
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.
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.
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.
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.

## Variables

DECAF_API_VIS const uint8_t *const | DECAF_ED25519_NO_CONTEXT

## Detailed Description

A group of prime order p, based on Curve25519.

Author
  Mike Hamburg

Copyright
  Copyright (c) 2015-2016 Cryptography Research, Inc.
  Released under the MIT License. See LICENSE.txt for license information.

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 1

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

Now deprecated.

## 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] | enc | The encoded point.
  [in] | p | The 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] | enc | The encoded point.
  [in] | p | The 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] | x | The ECDH private key as in RFC7748
  [in] | ed | The 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] | x | The ECDH public key as in RFC7748(point on Montgomery curve)
  [in] | ed | The 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] | keypair | The scheduled keypair.
  [in] | privkey | The 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] | pubkey | The public key.
  [in] | privkey | The 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] | pubkey | The 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] | privkey | The private key.
  [in] | keypair | The 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] | pubkey | The public key.
  [in] | keypair | The 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] | signature | The signature.
  [in] | keypair | The private and public key.
  [in] | message | The message to sign.
  [in] | message_len | The length of the message.
  [in] | prehashed | Nonzero if the message is actually the hash of something you want to sign.
  [in] | context | A "context" for this signature of up to 255 bytes.
  [in] | context_len | Length 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] | signature | The signature.
  [in] | keypair | The private and public key.
  [in] | hash | The hash of the message. This object will not be modified by the call.
  [in] | context | A "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
  [in] | context_len | Length 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] | hash | The 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] | signature | The signature.
  [in] | privkey | The private key.
  [in] | pubkey | The public key.
  [in] | message | The message to sign.
  [in] | message_len | The length of the message.
  [in] | prehashed | Nonzero if the message is actually the hash of something you want to sign.
  [in] | context | A "context" for this signature of up to 255 bytes.
  [in] | context_len | Length 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] | signature | The signature.
  [in] | privkey | The private key.
  [in] | pubkey | The public key.
  [in] | hash | The hash of the message. This object will not be modified by the call.
  [in] | context | A "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
  [in] | context_len | Length 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] | signature | The signature.
  [in] | pubkey | The public key.
  [in] | message | The message to verify.
  [in] | message_len | The length of the message.
  [in] | prehashed | Nonzero if the message is actually the hash of something you want to verify.
  [in] | context | A "context" for this signature of up to 255 bytes.
  [in] | context_len | Length 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] | signature | The signature.
  [in] | pubkey | The public key.
  [in] | hash | The hash of the message. This object will not be modified by the call.
  [in] | context | A "context" for this signature of up to 255 bytes. Must be the same as what was used for the prehash.
  [in] | context_len | Length 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.