extlibs/tinydtls/dtls.h

   1 /* dtls -- a very basic DTLS implementation
   2  *
   3  * Copyright (C) 2011--2013 Olaf Bergmann <bergmann@tzi.org>
   4  * Copyright (C) 2013 Hauke Mehrtens <hauke@hauke-m.de>
   5  *
   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:
  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
  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
  24  * SOFTWARE.
  25  */
  26
  27 /**
  28  * @file dtls.h
  29  * @brief High level DTLS API and visible structures.
  30  */
  31
  32 #ifndef _DTLS_DTLS_H_
  33 #define _DTLS_DTLS_H_
  34
  35 #include <stdint.h>
  36
  37 #include "t_list.h"
  38 #include "state.h"
  39 #include "peer.h"
  40
  41 #ifndef WITH_CONTIKI
  42 #include "uthash.h"
  43 #include "t_list.h"
  44 #endif /* WITH_CONTIKI */
  45
  46 #include "alert.h"
  47 #include "crypto.h"
  48 #include "hmac.h"
  49
  50 #include "global.h"
  51 #include "dtls_time.h"
  52
  53 #ifndef DTLSv12
  54 #define DTLS_VERSION 0xfeff     /* DTLS v1.1 */
  55 #else
  56 #define DTLS_VERSION 0xfefd     /* DTLS v1.2 */
  57 #endif
  58
  59 #ifdef DTLS_X509
  60 #define DTLS_MAX_CERT_SIZE       1400
  61 #endif
  62
  63 typedef enum dtls_credentials_type_t {
  64   DTLS_PSK_HINT, DTLS_PSK_IDENTITY, DTLS_PSK_KEY
  65 } dtls_credentials_type_t;
  66
  67 typedef struct dtls_ecc_key_t {
  68   dtls_ecdh_curve curve;
  69   const unsigned char *priv_key;        /** < private key as bytes > */
  70   const unsigned char *pub_key_x;       /** < x part of the public key for the given private key > */
  71   const unsigned char *pub_key_y;       /** < y part of the public key for the given private key > */
  72 } dtls_ecc_key_t;
  73
  74 /** Length of the secret that is used for generating Hello Verify cookies. */
  75 #define DTLS_COOKIE_SECRET_LENGTH 12
  76
  77 struct dtls_context_t;
  78
  79 /**
  80  * This structure contains callback functions used by tinydtls to
  81  * communicate with the application. At least the write function must
  82  * be provided. It is called by the DTLS state machine to send packets
  83  * over the network. The read function is invoked to deliver decrypted
  84  * and verfified application data. The third callback is an event
  85  * handler function that is called when alert messages are encountered
  86  * or events generated by the library have occured.
  87  */
  88 typedef struct {
  89   /**
  90    * Called from dtls_handle_message() to send DTLS packets over the
  91    * network. The callback function must use the network interface
  92    * denoted by session->ifindex to send the data.
  93    *
  94    * @param ctx  The current DTLS context.
  95    * @param session The session object, including the address of the
  96    *              remote peer where the data shall be sent.
  97    * @param buf  The data to send.
  98    * @param len  The actual length of @p buf.
  99    * @return The callback function must return the number of bytes
 100    *         that were sent, or a value less than zero to indicate an
 101    *         error.
 102    */
 103   int (*write)(struct dtls_context_t *ctx,
 104                session_t *session, uint8 *buf, size_t len);
 105
 106   /**
 107    * Called from dtls_handle_message() deliver application data that was
 108    * received on the given session. The data is delivered only after
 109    * decryption and verification have succeeded.
 110    *
 111    * @param ctx  The current DTLS context.
 112    * @param session The session object, including the address of the
 113    *              data's origin.
 114    * @param buf  The received data packet.
 115    * @param len  The actual length of @p buf.
 116    * @return ignored
 117    */
 118   int (*read)(struct dtls_context_t *ctx,
 119                session_t *session, uint8 *buf, size_t len);
 120
 121   /**
 122    * The event handler is called when a message from the alert
 123    * protocol is received or the state of the DTLS session changes.
 124    *
 125    * @param ctx     The current dtls context.
 126    * @param session The session object that was affected.
 127    * @param level   The alert level or @c 0 when an event ocurred that
 128    *                is not an alert.
 129    * @param code    Values less than @c 256 indicate alerts, while
 130    *                @c 256 or greater indicate internal DTLS session changes.
 131    * @return ignored
 132    */
 133   int (*event)(struct dtls_context_t *ctx, session_t *session,
 134                 dtls_alert_level_t level, unsigned short code);
 135
 136 #ifdef DTLS_PSK
 137   /**
 138    * Called during handshake to get information related to the
 139    * psk key exchange. The type of information requested is
 140    * indicated by @p type which will be one of DTLS_PSK_HINT,
 141    * DTLS_PSK_IDENTITY, or DTLS_PSK_KEY. The called function
 142    * must store the requested item in the buffer @p result of
 143    * size @p result_length. On success, the function must return
 144    * the actual number of bytes written to @p result, of a
 145    * value less than zero on error. The parameter @p desc may
 146    * contain additional request information (e.g. the psk_identity
 147    * for which a key is requested when @p type == @c DTLS_PSK_KEY.
 148    *
 149    * @param ctx     The current dtls context.
 150    * @param session The session where the key will be used.
 151    * @param type    The type of the requested information.
 152    * @param desc    Additional request information
 153    * @param desc_len The actual length of desc.
 154    * @param result  Must be filled with the requested information.
 155    * @param result_length  Maximum size of @p result.
 156    * @return The number of bytes written to @p result or a value
 157    *         less than zero on error.
 158    */
 159   int (*get_psk_info)(struct dtls_context_t *ctx,
 160                       const session_t *session,
 161                       dtls_credentials_type_t type,
 162                       const unsigned char *desc, size_t desc_len,
 163                       unsigned char *result, size_t result_length);
 164
 165 #endif /* DTLS_PSK */
 166
 167 #ifdef DTLS_ECC
 168   /**
 169    * Called during handshake to get the server's or client's ecdsa
 170    * key used to authenticate this server or client in this
 171    * session. If found, the key must be stored in @p result and
 172    * the return value must be @c 0. If not found, @p result is
 173    * undefined and the return value must be less than zero.
 174    *
 175    * If ECDSA should not be supported, set this pointer to NULL.
 176    *
 177    * Implement this if you want to provide your own certificate to
 178    * the other peer. This is mandatory for a server providing ECDSA
 179    * support and optional for a client. A client doing DTLS client
 180    * authentication has to implementing this callback.
 181    *
 182    * @param ctx     The current dtls context.
 183    * @param session The session where the key will be used.
 184    * @param result  Must be set to the key object to used for the given
 185    *                session.
 186    * @return @c 0 if result is set, or less than zero on error.
 187    */
 188   int (*get_ecdsa_key)(struct dtls_context_t *ctx,
 189                        const session_t *session,
 190                        const dtls_ecc_key_t **result);
 191
 192
 193   /**
 194    * Called during handshake to check the peer's pubic key in this
 195    * session. If the public key matches the session and should be
 196    * considered valid the return value must be @c 0. If not valid,
 197    * the return value must be less than zero.
 198    *
 199    * If ECDSA should not be supported, set this pointer to NULL.
 200    *
 201    * Implement this if you want to verify the other peers public key.
 202    * This is mandatory for a DTLS client doing based ECDSA
 203    * authentication. A server implementing this will request the
 204    * client to do DTLS client authentication.
 205    *
 206    * @param ctx          The current dtls context.
 207    * @param session      The session where the key will be used.
 208    * @param other_pub_x  x component of the public key.
 209    * @param other_pub_y  y component of the public key.
 210    * @return @c 0 if public key matches, or less than zero on error.
 211    * error codes:
 212    *   return dtls_alert_fatal_create(DTLS_ALERT_BAD_CERTIFICATE);
 213    *   return dtls_alert_fatal_create(DTLS_ALERT_UNSUPPORTED_CERTIFICATE);
 214    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_REVOKED);
 215    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_EXPIRED);
 216    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_UNKNOWN);
 217    *   return dtls_alert_fatal_create(DTLS_ALERT_UNKNOWN_CA);
 218    */
 219   int (*verify_ecdsa_key)(struct dtls_context_t *ctx,
 220                           const session_t *session,
 221                           const unsigned char *other_pub_x,
 222                           const unsigned char *other_pub_y,
 223                           size_t key_size);
 224 #endif /* DTLS_ECC */
 225 #ifdef DTLS_X509
 226   /**
 227    * Called during handshake to get the server's or client's ecdsa
 228    * key used to authenticate this server or client in this
 229    * session. If found, the key must be stored in @p result and
 230    * the return value must be @c 0. If not found, @p result is
 231    * undefined and the return value must be less than zero.
 232    *
 233    * If ECDSA should not be supported, set this pointer to NULL.
 234    *
 235    * Implement this if you want to provide your own certificate to
 236    * the other peer. This is mandatory for a server providing X.509
 237    * support and optional for a client. A client doing DTLS client
 238    * authentication has to implementing this callback.
 239    *
 240    * @param ctx     The current dtls context.
 241    * @param session The session where the key will be used.
 242    * @param result  Must be set to the key object to used for the given
 243    *                session.
 244    * @return @c 0 if result is set, or less than zero on error.
 245    */
 246   int (*get_x509_key)(struct dtls_context_t *ctx,
 247                const session_t *session,
 248                const dtls_ecc_key_t **result);
 249   /**
 250    * Called during handshake to get the server's or client's
 251    * certificate used to authenticate this server or client in this
 252    * session. If found, the certificate must be stored in @p cert and
 253    * the return value must be @c 0. If not found, @p cert is
 254    * undefined and the return value must be less than zero.
 255    *
 256    * If X.509 should not be supported, set this pointer to NULL.
 257    *
 258    * Implement this if you want to provide your own certificate to
 259    * the other peer. This is mandatory for a server providing X.509
 260    * support and optional for a client. A client doing DTLS client
 261    * authentication has to implementing this callback.
 262    *
 263    * @param ctx       The current dtls context.
 264    * @param session   The session where the certificate will be used.
 265    * @param cert      Must be set to the certificate object to used for
 266    *                  the given session.
 267    * @param cert_size Size of certificate in bytes.
 268    * @return @c 0 if result is set, or less than zero on error.
 269    */
 270   int (*get_x509_cert)(struct dtls_context_t *ctx,
 271                         const session_t *session,
 272                         const unsigned char **cert,
 273                         size_t *cert_size);
 274
 275   /**
 276    * Called during handshake to check the peer's certificate in this
 277    * session. If the certificate matches the session and is valid the
 278    * return value must be @c 0. If not valid, the return value must be
 279    * less than zero.
 280    *
 281    * If X.509 should not be supported, set this pointer to NULL.
 282    *
 283    * Implement this if you want to verify the other peers certificate.
 284    * This is mandatory for a DTLS client doing based X.509
 285    * authentication. A server implementing this will request the
 286    * client to do DTLS client authentication.
 287    *
 288    * @param ctx       The current dtls context.
 289    * @param session   The session where the key will be used.
 290    * @param cert      Peer's certificate to check.
 291    * @param cert_size Size of certificate in bytes.
 292    * @param x         Allocated memory to store peer's public key part x.
 293    * @param x_size    Size of allocated memory to store peer's public key part x.
 294    * @param y         Allocated memory to store peer's public key part y.
 295    * @param y_size    Size of allocated memory to store peer's public key part y.
 296    * @return @c 0 if public key matches, or less than zero on error.
 297    * error codes:
 298    *   return dtls_alert_fatal_create(DTLS_ALERT_BAD_CERTIFICATE);
 299    *   return dtls_alert_fatal_create(DTLS_ALERT_UNSUPPORTED_CERTIFICATE);
 300    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_REVOKED);
 301    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_EXPIRED);
 302    *   return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_UNKNOWN);
 303    *   return dtls_alert_fatal_create(DTLS_ALERT_UNKNOWN_CA);
 304    */
 305   int (*verify_x509_cert)(struct dtls_context_t *ctx,
 306                            const session_t *session,
 307                            const unsigned char *cert,
 308                            size_t cert_size,
 309                unsigned char *x,
 310                            size_t x_size,
 311                unsigned char *y,
 312                            size_t y_size);
 313
 314   /**
 315    * Called during handshake to check if certificate format should be X.509
 316    *
 317    * If X.509 should not be supported, set this pointer to NULL.
 318    *
 319    * @param ctx       The current dtls context.
 320    * @return @c 0 if certificate format should be X.509, or less than zero on error.
 321    */
 322   int (*is_x509_active)(struct dtls_context_t *ctx);
 323 #endif /* DTLS_X509 */
 324
 325 } dtls_handler_t;
 326
 327 /** Holds global information of the DTLS engine. */
 328 typedef struct dtls_context_t {
 329   unsigned char cookie_secret[DTLS_COOKIE_SECRET_LENGTH];
 330   clock_time_t cookie_secret_age; /**< the time the secret has been generated */
 331
 332 #ifndef WITH_CONTIKI
 333   dtls_peer_t *peers;           /**< peer hash map */
 334 #else /* WITH_CONTIKI */
 335   LIST_STRUCT(peers);
 336
 337   struct etimer retransmit_timer; /**< fires when the next packet must be sent */
 338 #endif /* WITH_CONTIKI */
 339
 340   LIST_STRUCT(sendqueue);       /**< the packets to send */
 341
 342   void *app;                    /**< application-specific data */
 343
 344   dtls_handler_t *h;            /**< callback handlers */
 345
 346   dtls_cipher_enable_t is_anon_ecdh_eabled;    /**< enable/disable the TLS_ECDH_anon_WITH_AES_128_CBC_SHA_256 */
 347
 348   dtls_cipher_t selected_cipher; /**< selected ciper suite for handshake */
 349
 350   unsigned char readbuf[DTLS_MAX_BUF];
 351 } dtls_context_t;
 352
 353 /**
 354  * This function initializes the tinyDTLS memory management and must
 355  * be called first.
 356  */
 357 void dtls_init();
 358
 359 /**
 360  * Creates a new context object. The storage allocated for the new
 361  * object must be released with dtls_free_context(). */
 362 dtls_context_t *dtls_new_context(void *app_data);
 363
 364 /** Releases any storage that has been allocated for \p ctx. */
 365 void dtls_free_context(dtls_context_t *ctx);
 366
 367 #define dtls_set_app_data(CTX,DATA) ((CTX)->app = (DATA))
 368 #define dtls_get_app_data(CTX) ((CTX)->app)
 369
 370 /** Sets the callback handler object for @p ctx to @p h. */
 371 INLINE_API void dtls_set_handler(dtls_context_t *ctx, dtls_handler_t *h) {
 372   ctx->h = h;
 373 }
 374
 375  /**
 376   * @brief Enabling the TLS_ECDH_anon_WITH_AES_128_CBC_SHA_256
 377   *
 378   * @param ctx              The DTLS context to use.
 379   * @param is_enable    DTLS_CIPHER_ENABLE(1) or DTLS_CIPHER_DISABLE(0)
 380   */
 381 void dtls_enables_anon_ecdh(dtls_context_t* ctx, dtls_cipher_enable_t is_enable);
 382
 383 /**
 384  * @brief Select the cipher suite for handshake
 385  *
 386  * @param ctx              The DTLS context to use.
 387  * @param cipher         TLS_ECDH_anon_WITH_AES_128_CBC_SHA_256 (0xC018)
 388  *                                  TLS_PSK_WITH_AES_128_CCM_8 (0xX0A8)
 389  *                                  TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 (0xC0AE)
 390  */
 391 void dtls_select_cipher(dtls_context_t* ctx, const dtls_cipher_t cipher);
 392
 393 /**
 394  * Establishes a DTLS channel with the specified remote peer @p dst.
 395  * This function returns @c 0 if that channel already exists, a value
 396  * greater than zero when a new ClientHello message was sent, and
 397  * a value less than zero on error.
 398  *
 399  * @param ctx    The DTLS context to use.
 400  * @param dst    The remote party to connect to.
 401  * @return A value less than zero on error, greater or equal otherwise.
 402  */
 403 int dtls_connect(dtls_context_t *ctx, const session_t *dst);
 404
 405 /**
 406  * Establishes a DTLS channel with the specified remote peer.
 407  * This function returns @c 0 if that channel already exists, a value
 408  * greater than zero when a new ClientHello message was sent, and
 409  * a value less than zero on error.
 410  *
 411  * @param ctx    The DTLS context to use.
 412  * @param peer   The peer object that describes the session.
 413  * @return A value less than zero on error, greater or equal otherwise.
 414  */
 415 int dtls_connect_peer(dtls_context_t *ctx, dtls_peer_t *peer);
 416
 417 /**
 418  * Closes the DTLS connection associated with @p remote. This function
 419  * returns zero on success, and a value less than zero on error.
 420  */
 421 int dtls_close(dtls_context_t *ctx, const session_t *remote);
 422
 423 int dtls_renegotiate(dtls_context_t *ctx, const session_t *dst);
 424
 425 /**
 426  * Writes the application data given in @p buf to the peer specified
 427  * by @p session.
 428  *
 429  * @param ctx      The DTLS context to use.
 430  * @param session  The remote transport address and local interface.
 431  * @param buf      The data to write.
 432  * @param len      The actual length of @p data.
 433  *
 434  * @return The number of bytes written or @c -1 on error.
 435  */
 436 int dtls_write(struct dtls_context_t *ctx, session_t *session,
 437                uint8 *buf, size_t len);
 438
 439 /**
 440  * Checks sendqueue of given DTLS context object for any outstanding
 441  * packets to be transmitted.
 442  *
 443  * @param context The DTLS context object to use.
 444  * @param next    If not NULL, @p next is filled with the timestamp
 445  *  of the next scheduled retransmission, or @c 0 when no packets are
 446  *  waiting.
 447  */
 448 void dtls_check_retransmit(dtls_context_t *context, clock_time_t *next);
 449
 450 #define DTLS_COOKIE_LENGTH 16
 451
 452 #define DTLS_CT_CHANGE_CIPHER_SPEC 20
 453 #define DTLS_CT_ALERT              21
 454 #define DTLS_CT_HANDSHAKE          22
 455 #define DTLS_CT_APPLICATION_DATA   23
 456
 457 #if defined(_MSC_VER)
 458 #define PACKED_STRUCT_START __pragma(pack(push,1)); typedef struct
 459 #define PACKED_STRUCT_END   __pragma(pack(pop))
 460 #else
 461 #define PACKED_STRUCT_START typedef struct __attribute__((__packed__))
 462 #define PACKED_STRUCT_END
 463 #endif
 464
 465 /** Generic header structure of the DTLS record layer. */
 466 PACKED_STRUCT_START {
 467   uint8 content_type;           /**< content type of the included message */
 468   uint16 version;               /**< Protocol version */
 469   uint16 epoch;                 /**< counter for cipher state changes */
 470   uint48 sequence_number;       /**< sequence number */
 471   uint16 length;                /**< length of the following fragment */
 472   /* fragment */
 473 } dtls_record_header_t;
 474 PACKED_STRUCT_END;
 475
 476 /* Handshake types */
 477
 478 #define DTLS_HT_HELLO_REQUEST        0
 479 #define DTLS_HT_CLIENT_HELLO         1
 480 #define DTLS_HT_SERVER_HELLO         2
 481 #define DTLS_HT_HELLO_VERIFY_REQUEST 3
 482 #define DTLS_HT_CERTIFICATE         11
 483 #define DTLS_HT_SERVER_KEY_EXCHANGE 12
 484 #define DTLS_HT_CERTIFICATE_REQUEST 13
 485 #define DTLS_HT_SERVER_HELLO_DONE   14
 486 #define DTLS_HT_CERTIFICATE_VERIFY  15
 487 #define DTLS_HT_CLIENT_KEY_EXCHANGE 16
 488 #define DTLS_HT_FINISHED            20
 489
 490 /** Header structure for the DTLS handshake protocol. */
 491 PACKED_STRUCT_START {
 492   uint8 msg_type; /**< Type of handshake message  (one of DTLS_HT_) */
 493   uint24 length;  /**< length of this message */
 494   uint16 message_seq;   /**< Message sequence number */
 495   uint24 fragment_offset;       /**< Fragment offset. */
 496   uint24 fragment_length;       /**< Fragment length. */
 497   /* body */
 498 } dtls_handshake_header_t;
 499 PACKED_STRUCT_END;
 500
 501 /** Structure of the Client Hello message. */
 502 PACKED_STRUCT_START {
 503   uint16 version;         /**< Client version */
 504   uint32 gmt_random;      /**< GMT time of the random byte creation */
 505   unsigned char random[28];     /**< Client random bytes */
 506   /* session id (up to 32 bytes) */
 507   /* cookie (up to 32 bytes) */
 508   /* cipher suite (2 to 2^16 -1 bytes) */
 509   /* compression method */
 510 } dtls_client_hello_t;
 511 PACKED_STRUCT_END;
 512
 513 /** Structure of the Hello Verify Request. */
 514 PACKED_STRUCT_START {
 515   uint16 version;               /**< Server version */
 516   uint8 cookie_length;  /**< Length of the included cookie */
 517   uint8 cookie[];               /**< up to 32 bytes making up the cookie */
 518 } dtls_hello_verify_t;
 519 PACKED_STRUCT_END;
 520
 521 #if 0
 522 /**
 523  * Checks a received DTLS record for consistency and eventually decrypt,
 524  * verify, decompress and reassemble the contained fragment for
 525  * delivery to high-lever clients.
 526  *
 527  * \param state The DTLS record state for the current session.
 528  * \param
 529  */
 530 int dtls_record_read(dtls_state_t *state, uint8 *msg, int msglen);
 531 #endif
 532
 533 /**
 534  * Handles incoming data as DTLS message from given peer.
 535  *
 536  * @param ctx     The dtls context to use.
 537  * @param session The current session
 538  * @param msg     The received data
 539  * @param msglen  The actual length of @p msg.
 540  * @return A value less than zero on error, zero on success.
 541  */
 542 int dtls_handle_message(dtls_context_t *ctx, session_t *session,
 543                         uint8 *msg, int msglen);
 544
 545 /**
 546  * Check if @p session is associated with a peer object in @p context.
 547  * This function returns a pointer to the peer if found, NULL otherwise.
 548  *
 549  * @param context  The DTLS context to search.
 550  * @param session  The remote address and local interface
 551  * @return A pointer to the peer associated with @p session or NULL if
 552  *  none exists.
 553  */
 554 dtls_peer_t *dtls_get_peer(const dtls_context_t *context,
 555                            const session_t *session);
 556
 557 /**
 558 * Invokes the DTLS PRF using the current key block for @p session as
 559 * key and @p label + @p random1 + @p random2 as its input. This function
 560 * writes upto @p buflen bytes into the given output buffer @p buf.
 561 *
 562 * @param ctx The dtls context to use.
 563 * @param session The session whose key shall be used.
 564 * @param label A PRF label.
 565 * @param labellen Actual length of @p label.
 566 * @param random1 Random seed.
 567 * @param random1len Actual length of @p random1 (may be zero).
 568 * @param random2 Random seed.
 569 * @param random2len Actual length of @p random2 (may be zero).
 570 * @param buf Output buffer for generated random data.
 571 * @param buflen Maximum size of @p buf.
 572 *
 573 * @return The actual number of bytes written to @p buf or @c 0 on error.
 574 */
 575 size_t dtls_prf_with_current_keyblock(dtls_context_t *ctx, session_t *session,
 576                                       const uint8_t* label, const uint32_t labellen,
 577                                       const uint8_t* random1, const uint32_t random1len,
 578                                       const uint8_t* random2, const uint32_t random2len,
 579                                       uint8_t* buf, const uint32_t buflen);
 580
 581
 582 #endif /* _DTLS_DTLS_H_ */
 583
 584 /**
 585  * @mainpage
 586  *
 587  * @author Olaf Bergmann, TZI Uni Bremen
 588  *
 589  * This library provides a very simple datagram server with DTLS
 590  * support. It is designed to support session multiplexing in
 591  * single-threaded applications and thus targets specifically on
 592  * embedded systems.
 593  *
 594  * @section license License
 595  *
 596  * This software is under the <a
 597  * href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>.
 598  *
 599  * @subsection uthash UTHash
 600  *
 601  * This library uses <a href="http://uthash.sourceforge.net/">uthash</a> to manage
 602  * its peers (not used for Contiki). @b uthash uses the <b>BSD revised license</b>, see
 603  * <a href="http://uthash.sourceforge.net/license.html">http://uthash.sourceforge.net/license.html</a>.
 604  *
 605  * @subsection sha256 Aaron D. Gifford's SHA256 Implementation
 606  *
 607  * tinyDTLS provides HMAC-SHA256 with BSD-licensed code from Aaron D. Gifford,
 608  * see <a href="http://www.aarongifford.com/">www.aarongifford.com</a>.
 609  *
 610  * @subsection aes Rijndael Implementation From OpenBSD
 611  *
 612  * The AES implementation is taken from rijndael.{c,h} contained in the crypto
 613  * sub-system of the OpenBSD operating system. It is copyright by Vincent Rijmen, *
 614  * Antoon Bosselaers and Paulo Barreto. See <a
 615  * href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/crypto/rijndael.c">rijndael.c</a>
 616  * for License info.
 617  *
 618  * @section download Getting the Files
 619  *
 620  * You can get the sources either from the <a
 621  * href="http://sourceforge.net/projects/tinydtls/files">downloads</a> section or
 622  * through git from the <a
 623  * href="http://sourceforge.net/projects/tinydtls/develop">project develop page</a>.
 624  *
 625  * @section config Configuration
 626  *
 627  * Use @c configure to set up everything for a successful build. For Contiki, use the
 628  * option @c --with-contiki.
 629  *
 630  * @section build Building
 631  *
 632  * After configuration, just type
 633  * @code
 634 make
 635  * @endcode
 636  * optionally followed by
 637  * @code
 638 make install
 639  * @endcode
 640  * The Contiki version is integrated with the Contiki build system, hence you do not
 641  * need to invoke @c make explicitely. Just add @c tinydtls to the variable @c APPS
 642  * in your @c Makefile.
 643  *
 644  * @addtogroup dtls_usage DTLS Usage
 645  *
 646  * @section dtls_server_example DTLS Server Example
 647  *
 648  * This section shows how to use the DTLS library functions to setup a
 649  * simple secure UDP echo server. The application is responsible for the
 650  * entire network communication and thus will look like a usual UDP
 651  * server with socket creation and binding and a typical select-loop as
 652  * shown below. The minimum configuration required for DTLS is the
 653  * creation of the dtls_context_t using dtls_new_context(), and a callback
 654  * for sending data. Received packets are read by the application and
 655  * passed to dtls_handle_message() as shown in @ref dtls_read_cb.
 656  * For any useful communication to happen, read and write call backs
 657  * and a key management function should be registered as well.
 658  *
 659  * @code
 660  dtls_context_t *the_context = NULL;
 661  int fd, result;
 662
 663  static dtls_handler_t cb = {
 664    .write = send_to_peer,
 665    .read  = read_from_peer,
 666    .event = NULL,
 667    .get_psk_key = get_psk_key
 668  };
 669
 670  fd = socket(...);
 671  if (fd < 0 || bind(fd, ...) < 0)
 672    exit(-1);
 673
 674  the_context = dtls_new_context(&fd);
 675  dtls_set_handler(the_context, &cb);
 676
 677  while (1) {
 678    ...initialize fd_set rfds and timeout ...
 679    result = select(fd+1, &rfds, NULL, 0, NULL);
 680
 681    if (FD_ISSET(fd, &rfds))
 682      dtls_handle_read(the_context);
 683  }
 684
 685  dtls_free_context(the_context);
 686  * @endcode
 687  *
 688  * @subsection dtls_read_cb The Read Callback
 689  *
 690  * The DTLS library expects received raw data to be passed to
 691  * dtls_handle_message(). The application is responsible for
 692  * filling a session_t structure with the address data of the
 693  * remote peer as illustrated by the following example:
 694  *
 695  * @code
 696 int dtls_handle_read(struct dtls_context_t *ctx) {
 697   int *fd;
 698   session_t session;
 699   static uint8 buf[DTLS_MAX_BUF];
 700   int len;
 701
 702   fd = dtls_get_app_data(ctx);
 703
 704   assert(fd);
 705
 706   session.size = sizeof(session.addr);
 707   len = recvfrom(*fd, buf, sizeof(buf), 0, &session.addr.sa, &session.size);
 708
 709   return len < 0 ? len : dtls_handle_message(ctx, &session, buf, len);
 710 }
 711  * @endcode
 712  *
 713  * Once a new DTLS session was established and DTLS ApplicationData has been
 714  * received, the DTLS server invokes the read callback with the MAC-verified
 715  * cleartext data as its argument. A read callback for a simple echo server
 716  * could look like this:
 717  * @code
 718 int read_from_peer(struct dtls_context_t *ctx, session_t *session, uint8 *data, size_t len) {
 719   return dtls_write(ctx, session, data, len);
 720 }
 721  * @endcode
 722  *
 723  * @subsection dtls_send_cb The Send Callback
 724  *
 725  * The callback function send_to_peer() is called whenever data must be
 726  * sent over the network. Here, the sendto() system call is used to
 727  * transmit data within the given session. The socket descriptor required
 728  * by sendto() has been registered as application data when the DTLS context
 729  * was created with dtls_new_context().
 730  * Note that it is on the application to buffer the data when it cannot be
 731  * sent at the time this callback is invoked. The following example thus
 732  * is incomplete as it would have to deal with EAGAIN somehow.
 733  * @code
 734 int send_to_peer(struct dtls_context_t *ctx, session_t *session, uint8 *data, size_t len) {
 735   int fd = *(int *)dtls_get_app_data(ctx);
 736   return sendto(fd, data, len, MSG_DONTWAIT, &session->addr.sa, session->size);
 737 }
 738  * @endcode
 739  *
 740  * @subsection dtls_get_psk_info The Key Storage
 741  *
 742  * When a new DTLS session is created, the library must ask the application
 743  * for keying material. To do so, it invokes the registered call-back function
 744  * get_psk_info() with the current context and session information as parameter.
 745  * When the call-back function is invoked with the parameter @p type set to
 746  * @c DTLS_PSK_IDENTITY, the result parameter @p result must be filled with
 747  * the psk_identity_hint in case of a server, or the actual psk_identity in
 748  * case of a client. When @p type is @c DTLS_PSK_KEY, the result parameter
 749  * must be filled with a key for the given identity @p id. The function must
 750  * return the number of bytes written to @p result which must not exceed
 751  * @p result_length.
 752  * In case of an error, the function must return a negative value that
 753  * corresponds to a valid error code defined in alert.h.
 754  *
 755  * @code
 756 int get_psk_info(struct dtls_context_t *ctx UNUSED_PARAM,
 757             const session_t *session UNUSED_PARAM,
 758             dtls_credentials_type_t type,
 759             const unsigned char *id, size_t id_len,
 760             unsigned char *result, size_t result_length) {
 761
 762   switch (type) {
 763   case DTLS_PSK_IDENTITY:
 764     if (result_length < psk_id_length) {
 765       dtls_warn("cannot set psk_identity -- buffer too small\n");
 766       return dtls_alert_fatal_create(DTLS_ALERT_INTERNAL_ERROR);
 767     }
 768
 769     memcpy(result, psk_id, psk_id_length);
 770     return psk_id_length;
 771   case DTLS_PSK_KEY:
 772     if (id_len != psk_id_length || memcmp(psk_id, id, id_len) != 0) {
 773       dtls_warn("PSK for unknown id requested, exiting\n");
 774       return dtls_alert_fatal_create(DTLS_ALERT_ILLEGAL_PARAMETER);
 775     } else if (result_length < psk_key_length) {
 776       dtls_warn("cannot set psk -- buffer too small\n");
 777       return dtls_alert_fatal_create(DTLS_ALERT_INTERNAL_ERROR);
 778     }
 779
 780     memcpy(result, psk_key, psk_key_length);
 781     return psk_key_length;
 782   default:
 783     dtls_warn("unsupported request type: %d\n", type);
 784   }
 785
 786   return dtls_alert_fatal_create(DTLS_ALERT_INTERNAL_ERROR);
 787 }
 788  * @endcode
 789  *
 790  * @subsection dtls_events The Event Notifier
 791  *
 792  * Applications that want to be notified whenever the status of a DTLS session
 793  * has changed can register an event handling function with the field @c event
 794  * in the dtls_handler_t structure (see \ref dtls_server_example). The call-back
 795  * function is called for alert messages and internal state changes. For alert
 796  * messages, the argument @p level will be set to a value greater than zero, and
 797  * @p code will indicate the notification code. For internal events, @p level
 798  * is @c 0, and @p code a value greater than @c 255.
 799  *
 800  * Internal events are DTLS_EVENT_CONNECTED, @c DTLS_EVENT_CONNECT, and
 801  * @c DTLS_EVENT_RENEGOTIATE.
 802  *
 803  * @code
 804 int handle_event(struct dtls_context_t *ctx, session_t *session,
 805                  dtls_alert_level_t level, unsigned short code) {
 806   ... do something with event ...
 807   return 0;
 808 }
 809  * @endcode
 810  *
 811  * @section dtls_client_example DTLS Client Example
 812  *
 813  * A DTLS client is constructed like a server but needs to actively setup
 814  * a new session by calling dtls_connect() at some point. As this function
 815  * usually returns before the new DTLS channel is established, the application
 816  * must register an event handler and wait for @c DTLS_EVENT_CONNECT before
 817  * it can send data over the DTLS channel.
 818  *
 819  */
 820
 821 /**
 822  * @addtogroup contiki Contiki
 823  *
 824  * To use tinyDTLS as Contiki application, place the source code in the directory
 825  * @c apps/tinydtls in the Contiki source tree and invoke configure with the option
 826  * @c --with-contiki. This will define WITH_CONTIKI in tinydtls.h and include
 827  * @c Makefile.contiki in the main Makefile. To cross-compile for another platform
 828  * you will need to set your host and build system accordingly. For example,
 829  * when configuring for ARM, you would invoke
 830  * @code
 831 ./configure --with-contiki --build=x86_64-linux-gnu --host=arm-none-eabi
 832  * @endcode
 833  * on an x86_64 linux host.
 834  *
 835  * Then, create a Contiki project with @c APPS += tinydtls in its Makefile. A sample
 836  * server could look like this (with read_from_peer() and get_psk_key() as shown above).
 837  *
 838  * @code
 839 #include "contiki.h"
 840
 841 #include "tinydtls.h"
 842 #include "dtls.h"
 843
 844 #define UIP_IP_BUF   ((struct uip_ip_hdr *)&uip_buf[UIP_LLH_LEN])
 845 #define UIP_UDP_BUF  ((struct uip_udp_hdr *)&uip_buf[UIP_LLIPH_LEN])
 846
 847 int send_to_peer(struct dtls_context_t *, session_t *, uint8 *, size_t);
 848
 849 static struct uip_udp_conn *server_conn;
 850 static dtls_context_t *dtls_context;
 851
 852 static dtls_handler_t cb = {
 853   .write = send_to_peer,
 854   .read  = read_from_peer,
 855   .event = NULL,
 856   .get_psk_key = get_psk_key
 857 };
 858
 859 PROCESS(server_process, "DTLS server process");
 860 AUTOSTART_PROCESSES(&server_process);
 861
 862 PROCESS_THREAD(server_process, ev, data)
 863 {
 864   PROCESS_BEGIN();
 865
 866   dtls_init();
 867
 868   server_conn = udp_new(NULL, 0, NULL);
 869   udp_bind(server_conn, UIP_HTONS(5684));
 870
 871   dtls_context = dtls_new_context(server_conn);
 872   if (!dtls_context) {
 873     dtls_emerg("cannot create context\n");
 874     PROCESS_EXIT();
 875   }
 876
 877   dtls_set_handler(dtls_context, &cb);
 878
 879   while(1) {
 880     PROCESS_WAIT_EVENT();
 881     if(ev == tcpip_event && uip_newdata()) {
 882       session_t session;
 883
 884       uip_ipaddr_copy(&session.addr, &UIP_IP_BUF->srcipaddr);
 885       session.port = UIP_UDP_BUF->srcport;
 886       session.size = sizeof(session.addr) + sizeof(session.port);
 887
 888       dtls_handle_message(ctx, &session, uip_appdata, uip_datalen());
 889     }
 890   }
 891
 892   PROCESS_END();
 893 }
 894
 895 int send_to_peer(struct dtls_context_t *ctx, session_t *session, uint8 *data, size_t len) {
 896   struct uip_udp_conn *conn = (struct uip_udp_conn *)dtls_get_app_data(ctx);
 897
 898   uip_ipaddr_copy(&conn->ripaddr, &session->addr);
 899   conn->rport = session->port;
 900
 901   uip_udp_packet_send(conn, data, len);
 902
 903   memset(&conn->ripaddr, 0, sizeof(server_conn->ripaddr));
 904   memset(&conn->rport, 0, sizeof(conn->rport));
 905
 906   return len;
 907 }
 908  * @endcode
 909  */