Quelle  Hacl_P521.h

/* MIT License
 *
 * Copyright (c) 2016-2022 INRIA, CMU and Microsoft Corporation
 * Copyright (c) 2022-2023 HACL* Contributors
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __Hacl_P521_H
#define __Hacl_P521_H

#if defined(__cplusplus)
extern "C" {
#endif

#include <string.h>
#include "krml/internal/types.h"
#include "krml/lowstar_endianness.h"

#include "lib_intrinsics.h"

/*******************************************************************************

 Verified C library for ECDSA and ECDH functions over the P-521 NIST curve.

 This module implements signing and verification, key validation, conversions
 between various point representations, and ECDH key agreement.

*******************************************************************************/

/*****************/
/* ECDSA signing */
/*****************/

/**
Create an ECDSA signature WITHOUT hashing first.

  This function is intended to receive a hash of the input.
  For convenience, we recommend using one of the hash-and-sign combined functions above.

  The argument `msg` MUST be at least 66 bytes (i.e. `msg_len >= 66`).

  NOTE: The equivalent functions in OpenSSL and Fiat-Crypto both accept inputs
  smaller than 66 bytes. These libraries left-pad the input with enough zeroes to
  reach the minimum 66 byte size. Clients who need behavior identical to OpenSSL
  need to perform the left-padding themselves.

  The function returns `true` for successful creation of an ECDSA signature and `false` otherwise.

  The outparam `signature` (R || S) points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len].
  The arguments `private_key` and `nonce` point to 66 bytes of valid memory, i.e., uint8_t[66].

  The function also checks whether `private_key` and `nonce` are valid values:
    • 0 < `private_key` < the order of the curve
    • 0 < `nonce` < the order of the curve
*/
bool
Hacl_P521_ecdsa_sign_p521_without_hash(
    uint8_t *signature,
    uint32_t msg_len,
    uint8_t *msg,
    uint8_t *private_key,
    uint8_t *nonce);

/**********************/
/* ECDSA verification */
/**********************/

/**
Verify an ECDSA signature WITHOUT hashing first.

  This function is intended to receive a hash of the input.
  For convenience, we recommend using one of the hash-and-verify combined functions above.

  The argument `msg` MUST be at least 66 bytes (i.e. `msg_len >= 66`).

  The function returns `true` if the signature is valid and `false` otherwise.

  The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len].
  The argument `public_key` (x || y) points to 132 bytes of valid memory, i.e., uint8_t[132].
  The arguments `signature_r` and `signature_s` point to 66 bytes of valid memory, i.e., uint8_t[66].

  The function also checks whether `public_key` is valid
*/
bool
Hacl_P521_ecdsa_verif_without_hash(
    uint32_t msg_len,
    uint8_t *msg,
    uint8_t *public_key,
    uint8_t *signature_r,
    uint8_t *signature_s);

/******************/
/* Key validation */
/******************/

/**
Public key validation.

  The function returns `true` if a public key is valid and `false` otherwise.

  The argument `public_key` points to 132 bytes of valid memory, i.e., uint8_t[132].

  The public key (x || y) is valid (with respect to SP 800-56A):
    • the public key is not the “point at infinity”, represented as O.
    • the affine x and y coordinates of the point represented by the public key are
      in the range [0, p – 1] where p is the prime defining the finite field.
    • y^2 = x^3 + ax + b where a and b are the coefficients of the curve equation.
  The last extract is taken from: https://neilmadden.blog/2017/05/17/so-how-do-you-validate-nist-ecdh-public-keys/
*/
bool Hacl_P521_validate_public_key(uint8_t *public_key);

/**
Private key validation.

  The function returns `true` if a private key is valid and `false` otherwise.

  The argument `private_key` points to 66 bytes of valid memory, i.e., uint8_t[66].

  The private key is valid:
    • 0 < `private_key` < the order of the curve
*/
bool Hacl_P521_validate_private_key(uint8_t *private_key);

/*******************************************************************************
  Parsing and Serializing public keys.

  A public key is a point (x, y) on the P-521 NIST curve.

  The point can be represented in the following three ways.
    • raw          = [ x || y ], 132 bytes
    • uncompressed = [ 0x04 || x || y ], 133 bytes
    • compressed   = [ (0x02 for even `y` and 0x03 for odd `y`) || x ], 33 bytes

*******************************************************************************/

/**
Convert a public key from uncompressed to its raw form.

  The function returns `true` for successful conversion of a public key and `false` otherwise.

  The outparam `pk_raw` points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `pk` points to 133 bytes of valid memory, i.e., uint8_t[133].

  The function DOESN'T check whether (x, y) is a valid point.
*/
bool Hacl_P521_uncompressed_to_raw(uint8_t *pk, uint8_t *pk_raw);

/**
Convert a public key from compressed to its raw form.

  The function returns `true` for successful conversion of a public key and `false` otherwise.

  The outparam `pk_raw` points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `pk` points to 33 bytes of valid memory, i.e., uint8_t[33].

  The function also checks whether (x, y) is a valid point.
*/
bool Hacl_P521_compressed_to_raw(uint8_t *pk, uint8_t *pk_raw);

/**
Convert a public key from raw to its uncompressed form.

  The outparam `pk` points to 133 bytes of valid memory, i.e., uint8_t[133].
  The argument `pk_raw` points to 132 bytes of valid memory, i.e., uint8_t[132].

  The function DOESN'T check whether (x, y) is a valid point.
*/
void Hacl_P521_raw_to_uncompressed(uint8_t *pk_raw, uint8_t *pk);

/**
Convert a public key from raw to its compressed form.

  The outparam `pk` points to 33 bytes of valid memory, i.e., uint8_t[33].
  The argument `pk_raw` points to 132 bytes of valid memory, i.e., uint8_t[132].

  The function DOESN'T check whether (x, y) is a valid point.
*/
void Hacl_P521_raw_to_compressed(uint8_t *pk_raw, uint8_t *pk);

/******************/
/* ECDH agreement */
/******************/

/**
Compute the public key from the private key.

  The function returns `true` if a private key is valid and `false` otherwise.

  The outparam `public_key`  points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `private_key` points to 66 bytes of valid memory, i.e., uint8_t[66].

  The private key is valid:
    • 0 < `private_key` < the order of the curve.
*/
bool Hacl_P521_dh_initiator(uint8_t *public_key, uint8_t *private_key);

/**
Execute the diffie-hellmann key exchange.

  The function returns `true` for successful creation of an ECDH shared secret and
  `false` otherwise.

  The outparam `shared_secret` points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `their_pubkey` points to 132 bytes of valid memory, i.e., uint8_t[132].
  The argument `private_key` points to 66 bytes of valid memory, i.e., uint8_t[66].

  The function also checks whether `private_key` and `their_pubkey` are valid.
*/
bool
Hacl_P521_dh_responder(uint8_t *shared_secret, uint8_t *their_pubkey, uint8_t *private_key);

#if defined(__cplusplus)
}
#endif

#define __Hacl_P521_H_DEFINED
#endif