tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

Hacl_P256.h (8554B)

      1 /* MIT License
      2 *
      3 * Copyright (c) 2016-2022 INRIA, CMU and Microsoft Corporation
      4 * Copyright (c) 2022-2023 HACL* Contributors
      5 *
      6 * Permission is hereby granted, free of charge, to any person obtaining a copy
      7 * of this software and associated documentation files (the "Software"), to deal
      8 * in the Software without restriction, including without limitation the rights
      9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     10 * copies of the Software, and to permit persons to whom the Software is
     11 * furnished to do so, subject to the following conditions:
     12 *
     13 * The above copyright notice and this permission notice shall be included in all
     14 * copies or substantial portions of the Software.
     15 *
     16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
     21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
     22 * SOFTWARE.
     23 */
     24 
     25 #ifndef __Hacl_P256_H
     26 #define __Hacl_P256_H
     27 
     28 #if defined(__cplusplus)
     29 extern "C" {
     30 #endif
     31 
     32 #include <string.h>
     33 #include "krml/internal/types.h"
     34 #include "krml/lowstar_endianness.h"
     35 #include "krml/internal/target.h"
     36 
     37 #include "Hacl_Krmllib.h"
     38 #include "lib_intrinsics.h"
     39 
     40 /*******************************************************************************
     41 
     42 Verified C library for ECDSA and ECDH functions over the P-256 NIST curve.
     43 
     44 This module implements signing and verification, key validation, conversions
     45 between various point representations, and ECDH key agreement.
     46 
     47 *******************************************************************************/
     48 
     49 /*****************/
     50 /* ECDSA signing */
     51 /*****************/
     52 
     53 /**
     54 Create an ECDSA signature WITHOUT hashing first.
     55 
     56  This function is intended to receive a hash of the input.
     57  For convenience, we recommend using one of the hash-and-sign combined functions above.
     58 
     59  The argument `msg` MUST be at least 32 bytes (i.e. `msg_len >= 32`).
     60 
     61  NOTE: The equivalent functions in OpenSSL and Fiat-Crypto both accept inputs
     62  smaller than 32 bytes. These libraries left-pad the input with enough zeroes to
     63  reach the minimum 32 byte size. Clients who need behavior identical to OpenSSL
     64  need to perform the left-padding themselves.
     65 
     66  The function returns `true` for successful creation of an ECDSA signature and `false` otherwise.
     67 
     68  The outparam `signature` (R || S) points to 64 bytes of valid memory, i.e., uint8_t[64].
     69  The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len].
     70  The arguments `private_key` and `nonce` point to 32 bytes of valid memory, i.e., uint8_t[32].
     71 
     72  The function also checks whether `private_key` and `nonce` are valid values:
     73    • 0 < `private_key` < the order of the curve
     74    • 0 < `nonce` < the order of the curve
     75 */
     76 bool
     77 Hacl_P256_ecdsa_sign_p256_without_hash(
     78    uint8_t *signature,
     79    uint32_t msg_len,
     80    uint8_t *msg,
     81    uint8_t *private_key,
     82    uint8_t *nonce);
     83 
     84 /**********************/
     85 /* ECDSA verification */
     86 /**********************/
     87 
     88 /**
     89 Verify an ECDSA signature WITHOUT hashing first.
     90 
     91  This function is intended to receive a hash of the input.
     92  For convenience, we recommend using one of the hash-and-verify combined functions above.
     93 
     94  The argument `msg` MUST be at least 32 bytes (i.e. `msg_len >= 32`).
     95 
     96  The function returns `true` if the signature is valid and `false` otherwise.
     97 
     98  The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len].
     99  The argument `public_key` (x || y) points to 64 bytes of valid memory, i.e., uint8_t[64].
    100  The arguments `signature_r` and `signature_s` point to 32 bytes of valid memory, i.e., uint8_t[32].
    101 
    102  The function also checks whether `public_key` is valid
    103 */
    104 bool
    105 Hacl_P256_ecdsa_verif_without_hash(
    106    uint32_t msg_len,
    107    uint8_t *msg,
    108    uint8_t *public_key,
    109    uint8_t *signature_r,
    110    uint8_t *signature_s);
    111 
    112 /******************/
    113 /* Key validation */
    114 /******************/
    115 
    116 /**
    117 Public key validation.
    118 
    119  The function returns `true` if a public key is valid and `false` otherwise.
    120 
    121  The argument `public_key` points to 64 bytes of valid memory, i.e., uint8_t[64].
    122 
    123  The public key (x || y) is valid (with respect to SP 800-56A):
    124    • the public key is not the “point at infinity”, represented as O.
    125    • the affine x and y coordinates of the point represented by the public key are
    126      in the range [0, p – 1] where p is the prime defining the finite field.
    127    • y^2 = x^3 + ax + b where a and b are the coefficients of the curve equation.
    128  The last extract is taken from: https://neilmadden.blog/2017/05/17/so-how-do-you-validate-nist-ecdh-public-keys/
    129 */
    130 bool Hacl_P256_validate_public_key(uint8_t *public_key);
    131 
    132 /**
    133 Private key validation.
    134 
    135  The function returns `true` if a private key is valid and `false` otherwise.
    136 
    137  The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32].
    138 
    139  The private key is valid:
    140    • 0 < `private_key` < the order of the curve
    141 */
    142 bool Hacl_P256_validate_private_key(uint8_t *private_key);
    143 
    144 /*******************************************************************************
    145  Parsing and Serializing public keys.
    146 
    147  A public key is a point (x, y) on the P-256 NIST curve.
    148 
    149  The point can be represented in the following three ways.
    150    • raw          = [ x || y ], 64 bytes
    151    • uncompressed = [ 0x04 || x || y ], 65 bytes
    152    • compressed   = [ (0x02 for even `y` and 0x03 for odd `y`) || x ], 33 bytes
    153 
    154 *******************************************************************************/
    155 
    156 /**
    157 Convert a public key from uncompressed to its raw form.
    158 
    159  The function returns `true` for successful conversion of a public key and `false` otherwise.
    160 
    161  The outparam `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64].
    162  The argument `pk` points to 65 bytes of valid memory, i.e., uint8_t[65].
    163 
    164  The function DOESN'T check whether (x, y) is a valid point.
    165 */
    166 bool Hacl_P256_uncompressed_to_raw(uint8_t *pk, uint8_t *pk_raw);
    167 
    168 /**
    169 Convert a public key from compressed to its raw form.
    170 
    171  The function returns `true` for successful conversion of a public key and `false` otherwise.
    172 
    173  The outparam `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64].
    174  The argument `pk` points to 33 bytes of valid memory, i.e., uint8_t[33].
    175 
    176  The function also checks whether (x, y) is a valid point.
    177 */
    178 bool Hacl_P256_compressed_to_raw(uint8_t *pk, uint8_t *pk_raw);
    179 
    180 /**
    181 Convert a public key from raw to its uncompressed form.
    182 
    183  The outparam `pk` points to 65 bytes of valid memory, i.e., uint8_t[65].
    184  The argument `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64].
    185 
    186  The function DOESN'T check whether (x, y) is a valid point.
    187 */
    188 void Hacl_P256_raw_to_uncompressed(uint8_t *pk_raw, uint8_t *pk);
    189 
    190 /**
    191 Convert a public key from raw to its compressed form.
    192 
    193  The outparam `pk` points to 33 bytes of valid memory, i.e., uint8_t[33].
    194  The argument `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64].
    195 
    196  The function DOESN'T check whether (x, y) is a valid point.
    197 */
    198 void Hacl_P256_raw_to_compressed(uint8_t *pk_raw, uint8_t *pk);
    199 
    200 /******************/
    201 /* ECDH agreement */
    202 /******************/
    203 
    204 /**
    205 Compute the public key from the private key.
    206 
    207  The function returns `true` if a private key is valid and `false` otherwise.
    208 
    209  The outparam `public_key`  points to 64 bytes of valid memory, i.e., uint8_t[64].
    210  The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32].
    211 
    212  The private key is valid:
    213    • 0 < `private_key` < the order of the curve.
    214 */
    215 bool Hacl_P256_dh_initiator(uint8_t *public_key, uint8_t *private_key);
    216 
    217 /**
    218 Execute the diffie-hellmann key exchange.
    219 
    220  The function returns `true` for successful creation of an ECDH shared secret and
    221  `false` otherwise.
    222 
    223  The outparam `shared_secret` points to 64 bytes of valid memory, i.e., uint8_t[64].
    224  The argument `their_pubkey` points to 64 bytes of valid memory, i.e., uint8_t[64].
    225  The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32].
    226 
    227  The function also checks whether `private_key` and `their_pubkey` are valid.
    228 */
    229 bool
    230 Hacl_P256_dh_responder(uint8_t *shared_secret, uint8_t *their_pubkey, uint8_t *private_key);
    231 
    232 #if defined(__cplusplus)
    233 }
    234 #endif
    235 
    236 #define __Hacl_P256_H_DEFINED
    237 #endif