1 /* 2 * ngtcp2 3 * 4 * Copyright (c) 2019 ngtcp2 contributors 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining 7 * a copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sublicense, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be 15 * included in all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 24 */ 25 #ifndef NGTCP2_SHARED_H 26 #define NGTCP2_SHARED_H 27 28 #ifdef HAVE_CONFIG_H 29 # include <config.h> 30 #endif /* HAVE_CONFIG_H */ 31 32 #include <ngtcp2/ngtcp2_crypto.h> 33 34 /** 35 * @macro 36 * 37 * :macro:`NGTCP2_INITIAL_SALT_DRAFT` is a salt value which is used to 38 * derive initial secret. It is used for QUIC draft versions. 39 */ 40 #define NGTCP2_INITIAL_SALT_DRAFT \ 41 "\xaf\xbf\xec\x28\x99\x93\xd2\x4c\x9e\x97\x86\xf1\x9c\x61\x11\xe0\x43\x90" \ 42 "\xa8\x99" 43 44 /** 45 * @macro 46 * 47 * :macro:`NGTCP2_INITIAL_SALT_V1` is a salt value which is used to 48 * derive initial secret. It is used for QUIC v1. 49 */ 50 #define NGTCP2_INITIAL_SALT_V1 \ 51 "\x38\x76\x2c\xf7\xf5\x59\x34\xb3\x4d\x17\x9a\xe6\xa4\xc8\x0c\xad\xcc\xbb" \ 52 "\x7f\x0a" 53 54 /* Maximum key usage (encryption) limits */ 55 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_AES_GCM (1ULL << 23) 56 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_CHACHA20_POLY1305 (1ULL << 62) 57 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_AES_CCM (2965820ULL) 58 59 /* Maximum authentication failure (decryption) limits during the 60 lifetime of a connection. */ 61 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_AES_GCM (1ULL << 52) 62 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_CHACHA20_POLY1305 (1ULL << 36) 63 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_AES_CCM (2965820ULL) 64 65 /** 66 * @function 67 * 68 * `ngtcp2_crypto_derive_initial_secrets` derives initial secrets. 69 * |rx_secret| and |tx_secret| must point to the buffer of at least 32 70 * bytes capacity. rx for read and tx for write. This function 71 * writes rx and tx secrets into |rx_secret| and |tx_secret| 72 * respectively. The length of secret is 32 bytes long. 73 * |client_dcid| is the destination connection ID in first Initial 74 * packet of client. If |initial_secret| is not NULL, the initial 75 * secret is written to it. It must point to the buffer which has at 76 * least 32 bytes capacity. The initial secret is 32 bytes long. 77 * |side| specifies the side of application. 78 * 79 * This function returns 0 if it succeeds, or -1. 80 */ 81 int ngtcp2_crypto_derive_initial_secrets(uint32_t version, uint8_t *rx_secret, 82 uint8_t *tx_secret, 83 uint8_t *initial_secret, 84 const ngtcp2_cid *client_dcid, 85 ngtcp2_crypto_side side); 86 87 /** 88 * @function 89 * 90 * `ngtcp2_crypto_update_traffic_secret` derives the next generation 91 * of the traffic secret. |secret| specifies the current secret and 92 * its length is given in |secretlen|. The length of new key is the 93 * same as the current key. This function writes new key into the 94 * buffer pointed by |dest|. |dest| must have the enough capacity to 95 * store the new key. 96 * 97 * This function returns 0 if it succeeds, or -1. 98 */ 99 int ngtcp2_crypto_update_traffic_secret(uint8_t *dest, 100 const ngtcp2_crypto_md *md, 101 const uint8_t *secret, 102 size_t secretlen); 103 104 /** 105 * @function 106 * 107 * `ngtcp2_crypto_set_local_transport_params` sets QUIC transport 108 * parameter, which is encoded in wire format and stored in the buffer 109 * pointed by |buf| of length |len|, to the native handle |tls|. 110 * 111 * |tls| points to a implementation dependent TLS session object. If 112 * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL 113 * object. 114 * 115 * This function returns 0 if it succeeds, or -1. 116 */ 117 int ngtcp2_crypto_set_local_transport_params(void *tls, const uint8_t *buf, 118 size_t len); 119 120 /** 121 * @function 122 * 123 * `ngtcp2_crypto_set_remote_transport_params` retrieves a remote QUIC 124 * transport parameters from |tls| and sets it to |conn| using 125 * `ngtcp2_conn_set_remote_transport_params`. 126 * 127 * |tls| points to a implementation dependent TLS session object. If 128 * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL 129 * object. 130 * 131 * This function returns 0 if it succeeds, or -1. 132 */ 133 int ngtcp2_crypto_set_remote_transport_params(ngtcp2_conn *conn, void *tls); 134 135 /** 136 * @function 137 * 138 * `ngtcp2_crypto_derive_and_install_initial_key` derives initial 139 * keying materials and installs keys to |conn|. 140 * 141 * If |rx_secret| is not NULL, the secret for decryption is written to 142 * the buffer pointed by |rx_secret|. The length of secret is 32 143 * bytes, and |rx_secret| must point to the buffer which has enough 144 * capacity. 145 * 146 * If |tx_secret| is not NULL, the secret for encryption is written to 147 * the buffer pointed by |tx_secret|. The length of secret is 32 148 * bytes, and |tx_secret| must point to the buffer which has enough 149 * capacity. 150 * 151 * If |initial_secret| is not NULL, the initial secret is written to 152 * the buffer pointed by |initial_secret|. The length of secret is 32 153 * bytes, and |initial_secret| must point to the buffer which has 154 * enough capacity. 155 * 156 * |client_dcid| is the destination connection ID in first Initial 157 * packet of client. 158 * 159 * If |rx_key| is not NULL, the derived packet protection key for 160 * decryption is written to the buffer pointed by |rx_key|. If 161 * |rx_iv| is not NULL, the derived packet protection IV for 162 * decryption is written to the buffer pointed by |rx_iv|. If |rx_hp| 163 * is not NULL, the derived header protection key for decryption is 164 * written to the buffer pointed by |rx_hp|. 165 * 166 * If |tx_key| is not NULL, the derived packet protection key for 167 * encryption is written to the buffer pointed by |tx_key|. If 168 * |tx_iv| is not NULL, the derived packet protection IV for 169 * encryption is written to the buffer pointed by |tx_iv|. If |tx_hp| 170 * is not NULL, the derived header protection key for encryption is 171 * written to the buffer pointed by |tx_hp|. 172 * 173 * The length of packet protection key and header protection key is 16 174 * bytes long. The length of packet protection IV is 12 bytes long. 175 * 176 * This function calls `ngtcp2_conn_set_initial_crypto_ctx` to set 177 * initial AEAD and message digest algorithm. After the successful 178 * call of this function, application can use 179 * `ngtcp2_conn_get_initial_crypto_ctx` to get the object. 180 * 181 * This function returns 0 if it succeeds, or -1. 182 */ 183 int ngtcp2_crypto_derive_and_install_initial_key( 184 ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret, 185 uint8_t *initial_secret, uint8_t *rx_key, uint8_t *rx_iv, uint8_t *rx_hp, 186 uint8_t *tx_key, uint8_t *tx_iv, uint8_t *tx_hp, 187 const ngtcp2_cid *client_dcid); 188 189 /** 190 * @function 191 * 192 * `ngtcp2_crypto_cipher_ctx_encrypt_init` initializes |cipher_ctx| 193 * with new cipher context object for encryption which is constructed 194 * to use |key| as encryption key. |cipher| specifies cipher to use. 195 * 196 * This function returns 0 if it succeeds, or -1. 197 */ 198 int ngtcp2_crypto_cipher_ctx_encrypt_init(ngtcp2_crypto_cipher_ctx *cipher_ctx, 199 const ngtcp2_crypto_cipher *cipher, 200 const uint8_t *key); 201 202 /** 203 * @function 204 * 205 * `ngtcp2_crypto_cipher_ctx_free` frees up resources used by 206 * |cipher_ctx|. This function does not free the memory pointed by 207 * |cipher_ctx| itself. 208 */ 209 void ngtcp2_crypto_cipher_ctx_free(ngtcp2_crypto_cipher_ctx *cipher_ctx); 210 211 /* 212 * `ngtcp2_crypto_md_sha256` initializes |md| with SHA256 message 213 * digest algorithm and returns |md|. 214 */ 215 ngtcp2_crypto_md *ngtcp2_crypto_md_sha256(ngtcp2_crypto_md *md); 216 217 ngtcp2_crypto_aead *ngtcp2_crypto_aead_aes_128_gcm(ngtcp2_crypto_aead *aead); 218 219 /* 220 * `ngtcp2_crypto_random` writes cryptographically-secure random 221 * |datalen| bytes into the buffer pointed by |data|. 222 * 223 * This function returns 0 if it succeeds, or -1. 224 */ 225 int ngtcp2_crypto_random(uint8_t *data, size_t datalen); 226 227 #endif /* NGTCP2_SHARED_H */ 228