Documentation

Documentation

Includes

coap_session.h

#include "coap_session.h"
#include "coap_session.h"

pdu.h

#include "pdu.h"
#include "pdu.h"

Macros

Marco COAP_DTLS_H_

#define COAP_DTLS_H_


      

Marco COAP_TLS_LIBRARY_NOTLS

#define COAP_TLS_LIBRARY_NOTLS 0 /**< No DTLS library */


      

Marco COAP_TLS_LIBRARY_TINYDTLS

#define COAP_TLS_LIBRARY_TINYDTLS 1 /**< Using TinyDTLS library */


      

Marco COAP_TLS_LIBRARY_OPENSSL

#define COAP_TLS_LIBRARY_OPENSSL 2 /**< Using OpenSSL library */


      

Marco COAP_TLS_LIBRARY_GNUTLS

#define COAP_TLS_LIBRARY_GNUTLS 3 /**< Using GnuTLS library */


      

Marco COAP_DTLS_PKI_SETUP_VERSION

#define COAP_DTLS_PKI_SETUP_VERSION 1 /**< Latest PKI setup version */

      

Functions

Func coap_dtls_is_supported

int coap_dtls_is_supported(void);
/**
 * Check whether DTLS is available.
 *
 * @return @c 1 if support for DTLS is enabled, or @c 0 otherwise.
 */

Func coap_tls_is_supported

int coap_tls_is_supported(void);
/**
 * Check whether TLS is available.
 *
 * @return @c 1 if support for TLS is enabled, or @c 0 otherwise.
 */

Func coap_dtls_new_context

void *
coap_dtls_new_context(struct coap_context_t *coap_context);
/**
 * Creates a new DTLS context for the given @p coap_context. This function
 * returns a pointer to a new DTLS context object or @c NULL on error.
 *
 * Internal function.
 *
 * @param coap_context The CoAP context where the DTLS object shall be used.
 *
 * @return A DTLS context object or @c NULL on error.
 */

Func coap_dtls_context_set_psk

int
coap_dtls_context_set_psk(struct coap_context_t *coap_context,
                         const char *identity_hint,
                         coap_dtls_role_t role);


      

Func coap_dtls_context_set_pki

int
coap_dtls_context_set_pki(struct coap_context_t *coap_context,
                         coap_dtls_pki_t *setup_data,
                         coap_dtls_role_t role);


      

Func coap_dtls_context_set_pki_root_cas

int
coap_dtls_context_set_pki_root_cas(struct coap_context_t *coap_context,
                                  const char *ca_file,
                                  const char *ca_dir);


      

Func coap_dtls_context_check_keys_enabled

int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);


      

Func coap_dtls_free_context

void coap_dtls_free_context(void *dtls_context);
/**
 * Releases the storage allocated for @p dtls_context.
 *
 * Internal function.
 *
 * @param dtls_context The DTLS context as returned by coap_dtls_new_context().
 */

Func coap_dtls_new_client_session

void *coap_dtls_new_client_session(coap_session_t *coap_session);
/**
 * Create a new client-side session. This should send a HELLO to the server.
 *
 * Internal function.
 *
 * @param coap_session   The CoAP session.
 *
 * @return Opaque handle to underlying TLS library object containing security
 *         parameters for the session.
*/

Func coap_dtls_new_server_session

void *coap_dtls_new_server_session(coap_session_t *coap_session);
/**
 * Create a new DTLS server-side session.
 * Called after coap_dtls_hello() has returned @c 1, signalling that a validated
 * HELLO was received from a client.
 * This should send a HELLO to the server.
 *
 * Internal function.
 *
 * @param coap_session   The CoAP session.
 *
 * @return Opaque handle to underlying TLS library object containing security
 *         parameters for the DTLS session.
 */

Func coap_dtls_free_session

void coap_dtls_free_session(coap_session_t *coap_session);
/**
 * Terminates the DTLS session (may send an ALERT if necessary) then frees the
 * underlying TLS library object containing security parameters for the session.
 *
 * Internal function.
 *
 * @param coap_session   The CoAP session.
 */

Func coap_dtls_session_update_mtu

void coap_dtls_session_update_mtu(coap_session_t *coap_session);
/**
 * Notify of a change in the CoAP session's MTU, for example after
 * a PMTU update.
 *
 * Internal function.
 *
 * @param coap_session   The CoAP session.
 */

Func coap_dtls_send

int coap_dtls_send(coap_session_t *coap_session,
                  const uint8_t *data,
                  size_t data_len);
/**
 * Send data to a DTLS peer.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param data      pointer to data.
 * @param data_len  Number of bytes to send.
 *
 * @return @c 0 if this would be blocking, @c -1 if there is an error or the
 *         number of cleartext bytes sent.
 */

Func coap_dtls_is_context_timeout

int coap_dtls_is_context_timeout(void);
/**
 * Check if timeout is handled per CoAP session or per CoAP context.
 *
 * Internal function.
 *
 * @return @c 1 of timeout and retransmit is per context, @c 0 if it is
 *         per session.
 */

Func coap_dtls_get_context_timeout

coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
/**
 * Do all pending retransmits and get next timeout
 *
 * Internal function.
 *
 * @param dtls_context The DTLS context.
 *
 * @return @c 0 if no event is pending or date of the next retransmit.
 */

Func coap_dtls_get_timeout

coap_tick_t coap_dtls_get_timeout(coap_session_t *coap_session);
/**
 * Get next timeout for this session.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 *
 * @return @c 0 If no event is pending or date of the next retransmit.
 */

Func coap_dtls_handle_timeout

void coap_dtls_handle_timeout(coap_session_t *coap_session);
/**
 * Handle a DTLS timeout expiration.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 */

Func coap_dtls_receive

int coap_dtls_receive(coap_session_t *coap_session,
                     const uint8_t *data,
                     size_t data_len);
/**
 * Handling incoming data from a DTLS peer.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param data      Encrypted datagram.
 * @param data_len  Encrypted datagram size.
 *
 * @return Result of coap_handle_dgram on the decrypted CoAP PDU
 *         or @c -1 for error.
 */

Func coap_dtls_hello

int coap_dtls_hello(coap_session_t *coap_session,
                   const uint8_t *data,
                   size_t data_len);
/**
 * Handling client HELLO messages from a new candiate peer.
 * Note that session->tls is empty.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param data      Encrypted datagram.
 * @param data_len  Encrypted datagram size.
 *
 * @return @c 0 if a cookie verification message has been sent, @c 1 if the
 *        HELLO contains a valid cookie and a server session should be created,
 *        @c -1 if the message is invalid.
 */

Func coap_dtls_get_overhead

unsigned int coap_dtls_get_overhead(coap_session_t *coap_session);
/**
 * Get DTLS overhead over cleartext PDUs.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 *
 * @return Maximum number of bytes added by DTLS layer.
 */

Func coap_tls_new_client_session

void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected);
/**
 * Create a new TLS client-side session.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param connected Updated with whether the connection is connected yet or not.
 *                  @c 0 is not connected, @c 1 is connected.
 *
 * @return Opaque handle to underlying TLS library object containing security
 *         parameters for the session.
*/

Func coap_tls_new_server_session

void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected);
/**
 * Create a TLS new server-side session.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param connected Updated with whether the connection is connected yet or not.
 *                  @c 0 is not connected, @c 1 is connected.
 *
 * @return Opaque handle to underlying TLS library object containing security
 *         parameters for the session.
 */

Func coap_tls_free_session

void coap_tls_free_session( coap_session_t *coap_session );
/**
 * Terminates the TLS session (may send an ALERT if necessary) then frees the
 * underlying TLS library object containing security parameters for the session.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 */

Func coap_tls_write

ssize_t coap_tls_write(coap_session_t *coap_session,
                      const uint8_t *data,
                      size_t data_len
                      );
/**
 * Send data to a TLS peer, with implicit flush.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param data      Pointer to data.
 * @param data_len  Number of bytes to send.
 *
 * @return          @c 0 if this should be retried, @c -1 if there is an error
 *                  or the number of cleartext bytes sent.
 */

Func coap_tls_read

ssize_t coap_tls_read(coap_session_t *coap_session,
                     uint8_t *data,
                     size_t data_len
                     );
/**
 * Read some data from a TLS peer.
 *
 * Internal function.
 *
 * @param coap_session The CoAP session.
 * @param data      Pointer to data.
 * @param data_len  Maximum number of bytes to read.
 *
 * @return          @c 0 if this should be retried, @c -1 if there is an error
 *                  or the number of cleartext bytes read.
 */

Func coap_dtls_startup

void coap_dtls_startup(void);
/**
 * Initialize the underlying (D)TLS Library layer.
 *
 * Internal function.
 *
 */

Func coap_dtls_set_log_level

void coap_dtls_set_log_level(int level);
/**
 * @ingroup logging
 * Sets the (D)TLS logging level to the specified @p level.
 * Note: coap_log_level() will influence output if at a specified level.
 *
 * @param level The logging level to use - LOG_*
 */

Func coap_dtls_get_log_level

int coap_dtls_get_log_level(void);
/**
 * @ingroup logging
 * Get the current (D)TLS logging.
 *
 * @return The current log level (one of LOG_*).
 */

Vars

Variable coap_tls_version_t

coap_tls_version_t *coap_get_tls_library_version(void);
/**
 * Determine the type and version of the underlying (D)TLS library.
 *
 * @return The version and type of library libcoap was compiled against.
 */

Variable coap_dtls_pki_t

struct coap_dtls_pki_t;

      

Consts

Types

Typedefs

Typedef coap_tls_version_t;

typedef struct coap_tls_version_t {
 uint64_t version; /**< (D)TLS runtime Library Version */
 int type; /**< Library type. One of COAP_TLS_LIBRARY_* */
 uint64_t built_version; /**< (D)TLS Built against Library Version */
} coap_tls_version_t;
/**
 * The structure used for returning the underlying (D)TLS library
 * information.
 */

Typedef coap_dtls_security_setup_t

typedef int (*coap_dtls_security_setup_t)(void* tls_session,
                                       struct coap_dtls_pki_t *setup_data);
/**
 * Additional Security setup handler that can be set up by
 * coap_context_set_pki().
 * Invoked when libcoap has done the validation checks at the TLS level,
 * but the application needs to do some additional checks/changes/updates.
 *
 * @param tls_session The security session definition - e.g. SSL * for OpenSSL.
 *                    NULL if server call-back.
 *                    This will be dependent on the underlying TLS library -
 *                    see coap_get_tls_library_version()
 * @param setup_data A structure containing setup data originally passed into
 *                   coap_context_set_pki() or coap_new_client_session_pki().
 *
 * @return @c 1 if successful, else @c 0.
 */

Typedef coap_dtls_cn_callback_t

typedef int (*coap_dtls_cn_callback_t)(const char *cn,
            const uint8_t *asn1_public_cert,
            size_t asn1_length,
            coap_session_t *coap_session,
            unsigned depth,
            int validated,
            void *arg);
/**
 * CN Validation call-back that can be set up by coap_context_set_pki().
 * Invoked when libcoap has done the validation checks at the TLS level,
 * but the application needs to check that the CN is allowed.
 * CN is the SubjectAltName in the cert, if not present, then the leftmost
 * Common Name (CN) component of the subject name.
 *
 * @param cn  The determined CN from the certificate
 * @param asn1_public_cert  The ASN.1 DER encoded X.509 certificate
 * @param asn1_length  The ASN.1 length
 * @param coap_session  The CoAP session associated with the certificate update
 * @param depth  Depth in cert chain.  If 0, then client cert, else a CA
 * @param validated  TLS layer can find no issues if 1
 * @param arg  The same as was passed into coap_context_set_pki()
 *             in setup_data->cn_call_back_arg
 *
 * @return @c 1 if accepted, else @c 0 if to be rejected.
 */

Typedef coap_asn1_privatekey_type_t;

typedef enum coap_asn1_privatekey_type_t {
 COAP_ASN1_PKEY_NONE,    /**< NONE */
 COAP_ASN1_PKEY_RSA,     /**< RSA type */
 COAP_ASN1_PKEY_RSA2,    /**< RSA2 type */
 COAP_ASN1_PKEY_DSA,     /**< DSA type */
 COAP_ASN1_PKEY_DSA1,    /**< DSA1 type */
 COAP_ASN1_PKEY_DSA2,    /**< DSA2 type */
 COAP_ASN1_PKEY_DSA3,    /**< DSA3 type */
 COAP_ASN1_PKEY_DSA4,    /**< DSA4 type */
 COAP_ASN1_PKEY_DH,      /**< DH type */
 COAP_ASN1_PKEY_DHX,     /**< DHX type */
 COAP_ASN1_PKEY_EC,      /**< EC type */
 COAP_ASN1_PKEY_HMAC,    /**< HMAC type */
 COAP_ASN1_PKEY_CMAC,    /**< CMAC type */
 COAP_ASN1_PKEY_TLS1_PRF, /**< TLS1_PRF type */
 COAP_ASN1_PKEY_HKDF     /**< HKDF type */
} coap_asn1_privatekey_type_t;
/**
 * The enum used for determining the provided PKI ASN.1 (DER) Private Key
 * formats.
 */

Typedef coap_pki_key_t;

typedef enum coap_pki_key_t {
 COAP_PKI_KEY_PEM = 0,  /**< The PKI key type is PEM */
 COAP_PKI_KEY_ASN1,     /**< The PKI key type is ASN.1 (DER) */
} coap_pki_key_t;
/**
 * The enum used for determining the PKI key formats.
 */

Typedef coap_pki_key_pem_t;

typedef struct coap_pki_key_pem_t {
 const char *ca_file;      /**< File location of Common CA in PEM format */
 const char *public_cert;  /**< File location of Public Cert in PEM format */
 const char *private_key;  /**< File location of Private Key in PEM format */
} coap_pki_key_pem_t;
/**
 * The structure that holds the PKI PEM definitions.
 */

Typedef coap_pki_key_asn1_t;

typedef struct coap_pki_key_asn1_t {
 const uint8_t *ca_cert;    /**< ASN1 (DER) Common CA Cert */
 const uint8_t *public_cert; /**< ASN1 (DER) Public Cert */
 const uint8_t *private_key; /**< ASN1 (DER) Private Key */
 size_t ca_cert_len;        /**< ASN1 CA Cert length */
 size_t public_cert_len;    /**< ASN1 Public Cert length */
 size_t private_key_len;    /**< ASN1 Private Key length */
 coap_asn1_privatekey_type_t private_key_type; /**< Private Key Type */
} coap_pki_key_asn1_t;
/**
 * The structure that holds the PKI ASN.1 (DER) definitions.
 */

Typedef key;

typedef struct coap_dtls_key_t {
 coap_pki_key_t key_type;         /**< key format type */
 union {
   coap_pki_key_pem_t pem;        /**< for PEM keys */
   coap_pki_key_asn1_t asn1;      /**< for ASN.1 (DER) keys */
 } key;
/**
 * The structure that holds the PKI key information.
 */

Typedef coap_dtls_key_t

typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
            void* arg);
/**
 * Server Name Indication (SNI) Validation call-back that can be set up by
 * coap_context_set_pki().
 * Invoked if the SNI is not previously seen and prior to sending a certificate
 * set back to the client so that the appropriate certificate set can be used
 * based on the requesting SNI.
 *
 * @param sni  The requested SNI
 * @param arg  The same as was passed into coap_context_set_pki()
 *             in setup_data->sni_call_back_arg
 *
 * @return New set of certificates to use, or @c NULL if SNI is to be rejected.
 */

Typedef coap_dtls_pki_t;

typedef struct coap_dtls_pki_t {
 uint8_t version; /** Set to 1 to support this version of the struct */

 /* Options to enable different TLS functionality in libcoap */
 uint8_t verify_peer_cert;       /**< 1 if peer cert is to be verified */
 uint8_t require_peer_cert;      /**< 1 if peer cert is required */
 uint8_t allow_self_signed;      /**< 1 if self signed certs are allowed */
 uint8_t allow_expired_certs;    /**< 1 if expired certs are allowed */
 uint8_t cert_chain_validation;  /**< 1 if to check cert_chain_verify_depth */
 uint8_t cert_chain_verify_depth; /**< recommended depth is 3 */
 uint8_t check_cert_revocation;  /**< 1 if revocation checks wanted */
 uint8_t allow_no_crl;           /**< 1 ignore if CRL not there */
 uint8_t allow_expired_crl;      /**< 1 if expired crl is allowed */
 uint8_t reserved[6];            /**< Reserved - must be set to 0 for
                                        future compatibility */
                                  /* Size of 6 chosen to align to next
                                    * parameter, so if newly defined option
                                    * it can use one of the reserverd slot so
                                    * no need to change
                                    * COAP_DTLS_PKI_SETUP_VERSION and just
                                    * decrement the reserved[] count.
                                    */

 /** CN check call-back function.
   * If not NULL, is called when the TLS connection has passed the configured
   * TLS options above for the application to verify if the CN is valid.
   */
 coap_dtls_cn_callback_t validate_cn_call_back;
 void *cn_call_back_arg; /**< Passed in to the CN call-back function */

 /** SNI check call-back function.
   * If not @p NULL, called if the SNI is not previously seen and prior to
   * sending a certificate set back to the client so that the appropriate
   * certificate set can be used based on the requesting SNI.
   */
 coap_dtls_sni_callback_t validate_sni_call_back;
 void *sni_call_back_arg; /**< Passed in to the sni call-back function */

 /** Additional Security call-back handler that is invoked when libcoap has
   * done the standerd, defined validation checks at the TLS level,
   * If not @p NULL, called from within the TLS Client Hello connection
   * setup.
   */
 coap_dtls_security_setup_t additional_tls_setup_call_back;

 char* client_sni;   /**<  If not NULL, SNI to use in client TLS setup.
                             Owned by the client app and must remain valid
                             during the call to coap_new_client_session_pki() */

 coap_dtls_key_t pki_key; /**< PKI key definition */
} coap_dtls_pki_t;
/**
 * The structure used for defining the PKI setup data to be used.
 */

Typedef coap_dtls_role_t;

typedef enum coap_dtls_role_t {
 COAP_DTLS_ROLE_CLIENT, /**< Internal function invoked for client */
 COAP_DTLS_ROLE_SERVER /**< Internal function invoked for server */
} coap_dtls_role_t;