1 /* dtls -- a very basic DTLS implementation
3 * Copyright (C) 2011--2012 Olaf Bergmann <bergmann@tzi.org>
4 * Copyright (C) 2013 Hauke Mehrtens <hauke@hauke-m.de>
6 * Permission is hereby granted, free of charge, to any person
7 * obtaining a copy of this software and associated documentation
8 * files (the "Software"), to deal in the Software without
9 * restriction, including without limitation the rights to use, copy,
10 * modify, merge, publish, distribute, sublicense, and/or sell copies
11 * of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
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
21 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
22 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
23 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 #ifndef _DTLS_CRYPTO_H_
28 #define _DTLS_CRYPTO_H_
30 #include <stdlib.h> /* for rand() and srand() */
35 #include "aes/rijndael.h"
44 /* TLS_PSK_WITH_AES_128_CCM_8 */
45 #define DTLS_CCM_MAC_KEY_LENGTH 0 /* MAC Key length for AES-CCM cipher suites */
46 #define DTLS_CBC_MAC_KEY_LENGTH 32 /* MAC Key length for AES-CBC Cipher suites */
47 #define DTLS_KEY_LENGTH 16 /* AES-128 */
48 #define DTLS_BLK_LENGTH 16 /* AES-128 */
49 #define DTLS_MAC_LENGTH DTLS_HMAC_DIGEST_SIZE
50 #define DTLS_CCM_IV_LENGTH 4 /* length of nonce_explicit */
51 #define DTLS_CBC_IV_LENGTH 16
54 * Maximum size of the generated keyblock. Note that MAX_KEYBLOCK_LENGTH must
55 * be large enough to hold the pre_master_secret, i.e. twice the length of the
58 #define CCM_KB_LENGTH \
59 (2 * DTLS_KEY_LENGTH + 2 * DTLS_CCM_IV_LENGTH)
61 #define CBC_KB_LENGTH \
62 (2 * DTLS_CBC_MAC_KEY_LENGTH + 2 * DTLS_KEY_LENGTH )
64 #define MAX_KEYBLOCK_LENGTH \
65 ((CCM_KB_LENGTH) > (CBC_KB_LENGTH) ? (CCM_KB_LENGTH) : (CBC_KB_LENGTH) )
67 /** Length of DTLS master_secret */
68 #define DTLS_MASTER_SECRET_LENGTH 48
69 #define DTLS_RANDOM_LENGTH 32
71 typedef enum { AES128=0
75 DTLS_ECDH_CURVE_SECP256R1
78 /** Crypto context for TLS_PSK_WITH_AES_128_CCM_8 cipher suite. */
80 rijndael_ctx ctx; /**< AES-128 encryption context */
83 typedef struct dtls_cipher_context_t {
84 /** numeric identifier of this cipher suite in host byte order. */
85 aes128_t data; /**< The crypto context */
86 } dtls_cipher_context_t;
89 uint8 own_eph_priv[32];
90 uint8 other_eph_pub_x[32];
91 uint8 other_eph_pub_y[32];
92 uint8 other_pub_x[32];
93 uint8 other_pub_y[32];
94 } dtls_handshake_parameters_ecc_t;
97 /* This is the maximal supported length of the psk client identity and psk
98 * server identity hint */
99 #define DTLS_PSK_MAX_CLIENT_IDENTITY_LEN 32
101 /* This is the maximal supported length of the pre-shared key. */
102 #define DTLS_PSK_MAX_KEY_LEN 32
106 unsigned char identity[DTLS_PSK_MAX_CLIENT_IDENTITY_LEN];
107 } dtls_handshake_parameters_psk_t;
110 dtls_compression_t compression; /**< compression method */
112 dtls_cipher_t cipher; /**< cipher type */
113 uint16_t epoch; /**< counter for cipher state changes*/
114 uint64_t rseq; /**< sequence number of last record sent */
117 * The key block generated from PRF applied to client and server
118 * random bytes. The actual size is given by the selected cipher and
119 * can be calculated using dtls_kb_size(). Use \c dtls_kb_ macros to
120 * access the components of the key block.
122 uint8 key_block[MAX_KEYBLOCK_LENGTH];
123 } dtls_security_parameters_t;
128 uint8 client[DTLS_RANDOM_LENGTH]; /**< client random gmt and bytes */
129 uint8 server[DTLS_RANDOM_LENGTH]; /**< server random gmt and bytes */
131 /** the session's master secret */
132 uint8 master_secret[DTLS_MASTER_SECRET_LENGTH];
134 LIST_STRUCT(reorder_queue); /**< the packets to reorder */
135 dtls_hs_state_t hs_state; /**< handshake protocol status */
137 dtls_compression_t compression; /**< compression method */
138 dtls_cipher_t cipher; /**< cipher type */
139 unsigned int do_client_auth:1;
141 #if defined(DTLS_ECC) && defined(DTLS_PSK)
143 dtls_handshake_parameters_ecc_t ecc;
144 dtls_handshake_parameters_psk_t psk;
146 #else /* DTLS_ECC && DTLS_PSK */
148 #if defined(DTLS_ECC) || defined(DTLS_X509)
149 dtls_handshake_parameters_ecc_t ecc;
150 #endif /* DTLS_ECC */
152 dtls_handshake_parameters_psk_t psk;
153 #endif /* DTLS_PSK */
155 #endif /* DTLS_ECC && DTLS_PSK */
156 } dtls_handshake_parameters_t;
158 /* The following macros provide access to the components of the
159 * key_block in the security parameters. */
161 INLINE_API int dtls_kb_mac_secret_size(dtls_cipher_t cipher)
165 case TLS_NULL_WITH_NULL_NULL:
170 case TLS_ECDH_anon_WITH_AES_128_CBC_SHA_256:
171 case TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA_256:
173 return DTLS_CBC_MAC_KEY_LENGTH;
176 case TLS_PSK_WITH_AES_128_CCM_8:
177 case TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8:
179 return DTLS_CCM_MAC_KEY_LENGTH;
187 INLINE_API int dtls_kb_iv_size(dtls_cipher_t cipher)
191 case TLS_NULL_WITH_NULL_NULL:
192 case TLS_ECDH_anon_WITH_AES_128_CBC_SHA_256:
193 case TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA_256:
198 case TLS_PSK_WITH_AES_128_CCM_8:
199 case TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8:
201 return DTLS_CCM_IV_LENGTH;
211 #define dtls_kb_client_mac_secret(Param, Role) ((Param)->key_block)
212 #define dtls_kb_server_mac_secret(Param, Role) \
213 (dtls_kb_client_mac_secret(Param, Role) + dtls_kb_mac_secret_size((Param)->cipher))
214 #define dtls_kb_remote_mac_secret(Param, Role) \
215 ((Role) == DTLS_SERVER \
216 ? dtls_kb_client_mac_secret(Param, Role) \
217 : dtls_kb_server_mac_secret(Param, Role))
218 #define dtls_kb_local_mac_secret(Param, Role) \
219 ((Role) == DTLS_CLIENT \
220 ? dtls_kb_client_mac_secret(Param, Role) \
221 : dtls_kb_server_mac_secret(Param, Role))
222 #define dtls_kb_client_write_key(Param, Role) \
223 (dtls_kb_server_mac_secret(Param, Role) + dtls_kb_mac_secret_size((Param)->cipher))
224 #define dtls_kb_server_write_key(Param, Role) \
225 (dtls_kb_client_write_key(Param, Role) + DTLS_KEY_LENGTH)
226 #define dtls_kb_remote_write_key(Param, Role) \
227 ((Role) == DTLS_SERVER \
228 ? dtls_kb_client_write_key(Param, Role) \
229 : dtls_kb_server_write_key(Param, Role))
230 #define dtls_kb_local_write_key(Param, Role) \
231 ((Role) == DTLS_CLIENT \
232 ? dtls_kb_client_write_key(Param, Role) \
233 : dtls_kb_server_write_key(Param, Role))
234 #define dtls_kb_key_size(Param, Role) DTLS_KEY_LENGTH
235 #define dtls_kb_client_iv(Param, Role) \
236 (dtls_kb_server_write_key(Param, Role) + DTLS_KEY_LENGTH)
237 #define dtls_kb_server_iv(Param, Role) \
238 (dtls_kb_client_iv(Param, Role) + dtls_kb_iv_size((Param)->cipher))
239 #define dtls_kb_remote_iv(Param, Role) \
240 ((Role) == DTLS_SERVER \
241 ? dtls_kb_client_iv(Param, Role) \
242 : dtls_kb_server_iv(Param, Role))
243 #define dtls_kb_local_iv(Param, Role) \
244 ((Role) == DTLS_CLIENT \
245 ? dtls_kb_client_iv(Param, Role) \
246 : dtls_kb_server_iv(Param, Role))
248 #define dtls_kb_size(Param, Role) \
249 (2 * (dtls_kb_mac_secret_size((Param)->cipher) + \
250 dtls_kb_key_size(Param, Role) + dtls_kb_iv_size((Param)->cipher)))
252 /* just for consistency */
253 #define dtls_kb_digest_size(Param, Role) DTLS_MAC_LENGTH
256 * Expands the secret and key to a block of DTLS_HMAC_MAX
257 * size according to the algorithm specified in section 5 of
260 * \param h Identifier of the hash function to use.
261 * \param key The secret.
262 * \param keylen Length of \p key.
263 * \param seed The seed.
264 * \param seedlen Length of \p seed.
265 * \param buf Output buffer where the result is XORed into
266 * The buffe must be capable to hold at least
268 * \return The actual number of bytes written to \p buf or 0
271 size_t dtls_p_hash(dtls_hashfunc_t h,
272 const unsigned char *key, size_t keylen,
273 const unsigned char *label, size_t labellen,
274 const unsigned char *random1, size_t random1len,
275 const unsigned char *random2, size_t random2len,
276 unsigned char *buf, size_t buflen);
279 * This function implements the TLS PRF for DTLS_VERSION. For version
280 * 1.0, the PRF is P_MD5 ^ P_SHA1 while version 1.2 uses
281 * P_SHA256. Currently, the actual PRF is selected at compile time.
283 size_t dtls_prf(const unsigned char *key, size_t keylen,
284 const unsigned char *label, size_t labellen,
285 const unsigned char *random1, size_t random1len,
286 const unsigned char *random2, size_t random2len,
287 unsigned char *buf, size_t buflen);
290 * Calculates MAC for record + cleartext packet and places the result
291 * in \p buf. The given \p hmac_ctx must be initialized with the HMAC
292 * function to use and the proper secret. As the DTLS mac calculation
293 * requires data from the record header, \p record must point to a
294 * buffer of at least \c sizeof(dtls_record_header_t) bytes. Usually,
295 * the remaining packet will be encrypted, therefore, the cleartext
296 * is passed separately in \p packet.
298 * \param hmac_ctx The HMAC context to use for MAC calculation.
299 * \param record The record header.
300 * \param packet Cleartext payload to apply the MAC to.
301 * \param length Size of \p packet.
302 * \param buf A result buffer that is large enough to hold
303 * the generated digest.
305 void dtls_mac(dtls_hmac_context_t *hmac_ctx,
306 const unsigned char *record,
307 const unsigned char *packet, size_t length,
311 * Encrypts the specified \p src of given \p length, writing the
312 * result to \p buf. The cipher implementation may add more data to
313 * the result buffer such as an initialization vector or padding
314 * (e.g. for block cipers in CBC mode). The caller therefore must
315 * ensure that \p buf provides sufficient storage to hold the result.
316 * Usually this means ( 2 + \p length / blocksize ) * blocksize. The
317 * function returns a value less than zero on error or otherwise the
318 * number of bytes written.
320 * \param ctx The cipher context to use.
321 * \param src The data to encrypt.
322 * \param length The actual size of of \p src.
323 * \param buf The result buffer. \p src and \p buf must not
325 * \param aad additional data for AEAD ciphers
326 * \param aad_length actual size of @p aad
327 * \return The number of encrypted bytes on success, less than zero
330 int dtls_encrypt(const unsigned char *src, size_t length,
332 unsigned char *nounce,
333 unsigned char *write_key, size_t write_keylen,
334 unsigned char *mac_key, size_t mac_keylen,
335 const unsigned char *aad, size_t aad_length,
336 const dtls_cipher_t cipher);
339 * Decrypts the given buffer \p src of given \p length, writing the
340 * result to \p buf. The function returns \c -1 in case of an error,
341 * or the number of bytes written. Note that for block ciphers, \p
342 * length must be a multiple of the cipher's block size. A return
343 * value between \c 0 and the actual length indicates that only \c n-1
344 * block have been processed. Unlike dtls_encrypt(), the source
345 * and destination of dtls_decrypt() may overlap.
347 * \param ctx The cipher context to use.
348 * \param src The buffer to decrypt.
349 * \param length The length of the input buffer.
350 * \param buf The result buffer.
351 * \param aad additional authentication data for AEAD ciphers
352 * \param aad_length actual size of @p aad
353 * \return Less than zero on error, the number of decrypted bytes
356 int dtls_decrypt(const unsigned char *src, size_t length,
358 unsigned char *nounce,
359 unsigned char *read_key, size_t read_keylen,
360 unsigned char *mac_key, size_t mac_keylen,
361 const unsigned char *a_data, size_t a_data_length,
362 const dtls_cipher_t cipher);
364 /* helper functions */
367 * Generates pre_master_sercet from given PSK and fills the result
368 * according to the "plain PSK" case in section 2 of RFC 4279.
369 * Diffie-Hellman and RSA key exchange are currently not supported.
371 * @param key The shared key.
372 * @param keylen Length of @p key in bytes.
373 * @param result The derived pre master secret.
374 * @return The actual length of @p result.
376 int dtls_psk_pre_master_secret(unsigned char *key, size_t keylen,
377 unsigned char *result, size_t result_len);
379 #define DTLS_EC_KEY_SIZE 32
381 int dtls_ecdh_pre_master_secret(unsigned char *priv_key,
382 unsigned char *pub_key_x,
383 unsigned char *pub_key_y,
385 unsigned char *result,
388 void dtls_ecdsa_generate_key(unsigned char *priv_key,
389 unsigned char *pub_key_x,
390 unsigned char *pub_key_y,
393 void dtls_ecdsa_create_sig_hash(const unsigned char *priv_key, size_t key_size,
394 const unsigned char *sign_hash, size_t sign_hash_size,
395 uint32_t point_r[9], uint32_t point_s[9]);
397 void dtls_ecdsa_create_sig(const unsigned char *priv_key, size_t key_size,
398 const unsigned char *client_random, size_t client_random_size,
399 const unsigned char *server_random, size_t server_random_size,
400 const unsigned char *keyx_params, size_t keyx_params_size,
401 uint32_t point_r[9], uint32_t point_s[9]);
403 int dtls_ecdsa_verify_sig_hash(const unsigned char *pub_key_x,
404 const unsigned char *pub_key_y, size_t key_size,
405 const unsigned char *sign_hash, size_t sign_hash_size,
406 unsigned char *result_r, unsigned char *result_s);
408 int dtls_ecdsa_verify_sig(const unsigned char *pub_key_x,
409 const unsigned char *pub_key_y, size_t key_size,
410 const unsigned char *client_random, size_t client_random_size,
411 const unsigned char *server_random, size_t server_random_size,
412 const unsigned char *keyx_params, size_t keyx_params_size,
413 unsigned char *result_r, unsigned char *result_s);
415 int dtls_ecdhe_psk_pre_master_secret(unsigned char *psk, size_t psklen,
416 unsigned char *ecc_priv_key,
417 unsigned char *ecc_pub_key_x,
418 unsigned char *ecc_pub_key_y,
420 unsigned char *result,
423 int dtls_ec_key_from_uint32_asn1(const uint32_t *key, size_t key_size,
427 dtls_handshake_parameters_t *dtls_handshake_new();
429 void dtls_handshake_free(dtls_handshake_parameters_t *handshake);
431 dtls_security_parameters_t *dtls_security_new();
433 void dtls_security_free(dtls_security_parameters_t *security);
436 #endif /* _DTLS_CRYPTO_H_ */