Branch data     Line data    Source code

       1                 :            : /*
       2                 :            :  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
       3                 :            :  *
       4                 :            :  * Licensed under the Apache License, Version 2.0 (the "License").
       5                 :            :  * You may not use this file except in compliance with the License.
       6                 :            :  * A copy of the License is located at
       7                 :            :  *
       8                 :            :  *  http://aws.amazon.com/apache2.0
       9                 :            :  *
      10                 :            :  * or in the "license" file accompanying this file. This file is distributed
      11                 :            :  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
      12                 :            :  * express or implied. See the License for the specific language governing
      13                 :            :  * permissions and limitations under the License.
      14                 :            :  */
      15                 :            : 
      16                 :            : #pragma once
      17                 :            : 
      18                 :            : #include <stdint.h>
      19                 :            : 
      20                 :            : #include "crypto/s2n_ecc_evp.h"
      21                 :            : #include "stuffer/s2n_stuffer.h"
      22                 :            : #include "tls/s2n_crypto_constants.h"
      23                 :            : #include "utils/s2n_blob.h"
      24                 :            : 
      25                 :            : typedef uint16_t kem_extension_size;
      26                 :            : typedef uint16_t kem_public_key_size;
      27                 :            : typedef uint16_t kem_private_key_size;
      28                 :            : typedef uint16_t kem_shared_secret_size;
      29                 :            : typedef uint16_t kem_ciphertext_key_size;
      30                 :            : 
      31                 :            : #define IN  /* Indicates a necessary function input */
      32                 :            : #define OUT /* Indicates a function output */
      33                 :            : 
      34                 :            : #if defined(S2N_LIBCRYPTO_SUPPORTS_MLKEM)
      35                 :            :     #define S2N_NID_MLKEM768  NID_MLKEM768
      36                 :            :     #define S2N_NID_MLKEM1024 NID_MLKEM1024
      37                 :            : #else
      38                 :            :     #define S2N_NID_MLKEM768  NID_undef
      39                 :            :     #define S2N_NID_MLKEM1024 NID_undef
      40                 :            : #endif
      41                 :            : 
      42                 :            : struct s2n_kem {
      43                 :            :     const char *name;
      44                 :            :     int kem_nid;
      45                 :            :     const kem_extension_size kem_extension_id;
      46                 :            :     const kem_public_key_size public_key_length;
      47                 :            :     const kem_private_key_size private_key_length;
      48                 :            :     const kem_shared_secret_size shared_secret_key_length;
      49                 :            :     const kem_ciphertext_key_size ciphertext_length;
      50                 :            :     /* NIST Post Quantum KEM submissions require the following API for compatibility */
      51                 :            :     int (*generate_keypair)(IN const struct s2n_kem *kem, OUT uint8_t *public_key, OUT uint8_t *private_key);
      52                 :            :     int (*encapsulate)(IN const struct s2n_kem *kem, OUT uint8_t *ciphertext, OUT uint8_t *shared_secret, IN const uint8_t *public_key);
      53                 :            :     int (*decapsulate)(IN const struct s2n_kem *kem, OUT uint8_t *shared_secret, IN const uint8_t *ciphertext, IN const uint8_t *private_key);
      54                 :            : };
      55                 :            : 
      56                 :            : struct s2n_kem_params {
      57                 :            :     const struct s2n_kem *kem;
      58                 :            :     struct s2n_blob public_key;
      59                 :            :     struct s2n_blob private_key;
      60                 :            :     struct s2n_blob shared_secret;
      61                 :            :     /* Store whether the client included the length prefix of the PQ and ECC Shares in their ClientHello, so that the
      62                 :            :      * server can match the client's behavior. For the client side, store whether it should send the length prefix. */
      63                 :            :     bool len_prefixed;
      64                 :            : };
      65                 :            : 
      66                 :            : struct s2n_iana_to_kem {
      67                 :            :     const uint8_t iana_value[S2N_TLS_CIPHER_SUITE_LEN];
      68                 :            :     const struct s2n_kem **kems;
      69                 :            :     uint8_t kem_count;
      70                 :            : };
      71                 :            : 
      72                 :            : struct s2n_kem_group {
      73                 :            :     const char *name;
      74                 :            :     uint16_t iana_id;
      75                 :            :     const struct s2n_ecc_named_curve *curve;
      76                 :            :     const struct s2n_kem *kem;
      77                 :            : 
      78                 :            :     /* Whether the PQ KeyShare should be sent before the ECC KeyShare. Only enabled for X25519MLKEM768.
      79                 :            :      * See: https://datatracker.ietf.org/doc/html/draft-kwiatkowski-tls-ecdhe-mlkem-02#name-negotiated-groups */
      80                 :            :     bool send_kem_first;
      81                 :            : };
      82                 :            : 
      83                 :            : struct s2n_kem_group_params {
      84                 :            :     const struct s2n_kem_group *kem_group;
      85                 :            :     struct s2n_kem_params kem_params;
      86                 :            :     struct s2n_ecc_evp_params ecc_params;
      87                 :            : };
      88                 :            : 
      89                 :            : extern const struct s2n_kem s2n_mlkem_768;
      90                 :            : extern const struct s2n_kem s2n_mlkem_1024;
      91                 :            : 
      92                 :         20 : #define S2N_KEM_GROUPS_COUNT 4
      93                 :            : extern const struct s2n_kem_group *ALL_SUPPORTED_KEM_GROUPS[S2N_KEM_GROUPS_COUNT];
      94                 :            : 
      95                 :            : /* NIST curve KEM Groups */
      96                 :            : extern const struct s2n_kem_group s2n_secp256r1_mlkem_768;
      97                 :            : extern const struct s2n_kem_group s2n_secp384r1_mlkem_1024;
      98                 :            : 
      99                 :            : /* x25519 KEM Groups */
     100                 :            : extern const struct s2n_kem_group s2n_x25519_mlkem_768;
     101                 :            : 
     102                 :            : /* Pure ML-KEM Groups */
     103                 :            : extern const struct s2n_kem_group s2n_pure_mlkem_1024;
     104                 :            : 
     105                 :            : S2N_RESULT s2n_kem_generate_keypair(struct s2n_kem_params *kem_params);
     106                 :            : S2N_RESULT s2n_kem_encapsulate(struct s2n_kem_params *kem_params, struct s2n_blob *ciphertext);
     107                 :            : S2N_RESULT s2n_kem_decapsulate(struct s2n_kem_params *kem_params, const struct s2n_blob *ciphertext);
     108                 :            : int s2n_choose_kem_with_peer_pref_list(const uint8_t iana_value[S2N_TLS_CIPHER_SUITE_LEN],
     109                 :            :         struct s2n_blob *client_kem_ids, const struct s2n_kem *server_kem_pref_list[],
     110                 :            :         const uint8_t num_server_supported_kems, const struct s2n_kem **chosen_kem);
     111                 :            : int s2n_choose_kem_without_peer_pref_list(const uint8_t iana_value[S2N_TLS_CIPHER_SUITE_LEN],
     112                 :            :         const struct s2n_kem *server_kem_pref_list[], const uint8_t num_server_supported_kems,
     113                 :            :         const struct s2n_kem **chosen_kem);
     114                 :            : int s2n_kem_free(struct s2n_kem_params *kem_params);
     115                 :            : int s2n_kem_group_free(struct s2n_kem_group_params *kem_group_params);
     116                 :            : int s2n_cipher_suite_to_kem(const uint8_t iana_value[S2N_TLS_CIPHER_SUITE_LEN],
     117                 :            :         const struct s2n_iana_to_kem **supported_params);
     118                 :            : int s2n_get_kem_from_extension_id(kem_extension_size kem_id, const struct s2n_kem **kem);
     119                 :            : int s2n_kem_send_public_key(struct s2n_stuffer *out, struct s2n_kem_params *kem_params);
     120                 :            : int s2n_kem_recv_public_key(struct s2n_stuffer *in, struct s2n_kem_params *kem_params);
     121                 :            : int s2n_kem_send_ciphertext(struct s2n_stuffer *out, struct s2n_kem_params *kem_params);
     122                 :            : int s2n_kem_recv_ciphertext(struct s2n_stuffer *in, struct s2n_kem_params *kem_params);
     123                 :            : bool s2n_kem_is_available(const struct s2n_kem *kem);
     124                 :            : bool s2n_kem_group_is_available(const struct s2n_kem_group *kem_group);
     125                 :            : int s2n_find_kem_group_from_iana_id(uint16_t iana_id, const struct s2n_kem_group **out, bool *found);
     126                 :            : 
     127                 :            : /* mlkem768 */
     128                 :            : #define S2N_MLKEM_768_PUBLIC_KEY_BYTES    1184
     129                 :            : #define S2N_MLKEM_768_SECRET_KEY_BYTES    2400
     130                 :            : #define S2N_MLKEM_768_CIPHERTEXT_BYTES    1088
     131                 :            : #define S2N_MLKEM_768_SHARED_SECRET_BYTES 32
     132                 :            : 
     133                 :            : /* mlkem1024 */
     134                 :            : #define S2N_MLKEM_1024_PUBLIC_KEY_BYTES    1568
     135                 :            : #define S2N_MLKEM_1024_SECRET_KEY_BYTES    3168
     136                 :            : #define S2N_MLKEM_1024_CIPHERTEXT_BYTES    1568
     137                 :            : #define S2N_MLKEM_1024_SHARED_SECRET_BYTES 32