coap_dtls.h

Go to the documentation of this file.

/*
 * coap_dtls.h -- (Datagram) Transport Layer Support for libcoap
 *
 * Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org>
 * Copyright (C) 2017 Jean-Claude Michelou <jcm@spinetix.com>
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */
 
#ifndef COAP_DTLS_H_
#define COAP_DTLS_H_
 
#include "coap_time.h"
#include "str.h"
 
#ifndef COAP_DTLS_HINT_LENGTH
#define COAP_DTLS_HINT_LENGTH 128
#endif
 
/* https://tools.ietf.org/html/rfc6347#section-4.2.4.1 */
#ifndef COAP_DTLS_RETRANSMIT_MS
#define COAP_DTLS_RETRANSMIT_MS 1000
#endif
#ifndef COAP_DTLS_RETRANSMIT_TOTAL_MS
#define COAP_DTLS_RETRANSMIT_TOTAL_MS 60000
#endif
 
#define COAP_DTLS_RETRANSMIT_COAP_TICKS (COAP_DTLS_RETRANSMIT_MS * COAP_TICKS_PER_SECOND / 1000)
 
#define COAP_DTLS_RPK_CERT_CN "RPK"
 
int coap_dtls_is_supported(void);
 
int coap_tls_is_supported(void);
 
typedef enum coap_tls_library_t {
  COAP_TLS_LIBRARY_NOTLS = 0, 
  COAP_TLS_LIBRARY_TINYDTLS,  
  COAP_TLS_LIBRARY_OPENSSL,   
  COAP_TLS_LIBRARY_GNUTLS,    
  COAP_TLS_LIBRARY_MBEDTLS,   
} coap_tls_library_t;
 
typedef struct coap_tls_version_t {
  uint64_t version; 
  coap_tls_library_t type; 
  uint64_t built_version; 
} coap_tls_version_t;
 
coap_tls_version_t *coap_get_tls_library_version(void);
 
typedef int (*coap_dtls_security_setup_t)(void* tls_session,
                                        struct coap_dtls_pki_t *setup_data);
 
typedef int (*coap_dtls_cn_callback_t)(const char *cn,
             const uint8_t *asn1_public_cert,
             size_t asn1_length,
             struct coap_session_t *coap_session,
             unsigned int depth,
             int validated,
             void *arg);
 
typedef enum coap_asn1_privatekey_type_t {
  COAP_ASN1_PKEY_NONE,     
  COAP_ASN1_PKEY_RSA,      
  COAP_ASN1_PKEY_RSA2,     
  COAP_ASN1_PKEY_DSA,      
  COAP_ASN1_PKEY_DSA1,     
  COAP_ASN1_PKEY_DSA2,     
  COAP_ASN1_PKEY_DSA3,     
  COAP_ASN1_PKEY_DSA4,     
  COAP_ASN1_PKEY_DH,       
  COAP_ASN1_PKEY_DHX,      
  COAP_ASN1_PKEY_EC,       
  COAP_ASN1_PKEY_HMAC,     
  COAP_ASN1_PKEY_CMAC,     
  COAP_ASN1_PKEY_TLS1_PRF, 
  COAP_ASN1_PKEY_HKDF      
} coap_asn1_privatekey_type_t;
 
typedef enum coap_pki_key_t {
  COAP_PKI_KEY_PEM = 0,        
  COAP_PKI_KEY_ASN1,           
  COAP_PKI_KEY_PEM_BUF,        
  COAP_PKI_KEY_PKCS11,         
} coap_pki_key_t;
 
typedef struct coap_pki_key_pem_t {
  const char *ca_file;       
  const char *public_cert;   
  const char *private_key;   
} coap_pki_key_pem_t;
 
typedef struct coap_pki_key_pem_buf_t {
  const uint8_t *ca_cert;     
  const uint8_t *public_cert; 
  const uint8_t *private_key; 
  size_t ca_cert_len;         
  size_t public_cert_len;     
  size_t private_key_len;     
} coap_pki_key_pem_buf_t;
 
typedef struct coap_pki_key_asn1_t {
  const uint8_t *ca_cert;     
  const uint8_t *public_cert; 
  const uint8_t *private_key; 
  size_t ca_cert_len;         
  size_t public_cert_len;     
  size_t private_key_len;     
  coap_asn1_privatekey_type_t private_key_type; 
} coap_pki_key_asn1_t;
 
typedef struct coap_pki_key_pkcs11_t {
  const char *ca;            
  const char *public_cert;   
  const char *private_key;   
  const char *user_pin;      
} coap_pki_key_pkcs11_t;
 
typedef struct coap_dtls_key_t {
  coap_pki_key_t key_type;          
  union {
    coap_pki_key_pem_t pem;          
    coap_pki_key_pem_buf_t pem_buf;  
    coap_pki_key_asn1_t asn1;        
    coap_pki_key_pkcs11_t pkcs11;    
  } key;
} coap_dtls_key_t;
 
typedef coap_dtls_key_t *(*coap_dtls_pki_sni_callback_t)(const char *sni,
             void* arg);
 
 
#define COAP_DTLS_PKI_SETUP_VERSION 1 
typedef struct coap_dtls_pki_t {
  uint8_t version; 
  /* Options to enable different TLS functionality in libcoap */
  uint8_t verify_peer_cert;        
  uint8_t check_common_ca;         
  uint8_t allow_self_signed;       
  uint8_t allow_expired_certs;     
  uint8_t cert_chain_validation;   
  uint8_t cert_chain_verify_depth; 
  uint8_t check_cert_revocation;   
  uint8_t allow_no_crl;            
  uint8_t allow_expired_crl;       
  uint8_t allow_bad_md_hash;      
  uint8_t allow_short_rsa_length; 
  uint8_t is_rpk_not_cert;        
  uint8_t reserved[3];             
                                   /* Size of 3 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.
                                    */
 
  coap_dtls_cn_callback_t validate_cn_call_back;
  void *cn_call_back_arg;  
  coap_dtls_pki_sni_callback_t validate_sni_call_back;
  void *sni_call_back_arg;  
  coap_dtls_security_setup_t additional_tls_setup_call_back;
 
  char* client_sni;    
  coap_dtls_key_t pki_key;  
} coap_dtls_pki_t;
 
typedef struct coap_dtls_cpsk_info_t {
  coap_bin_const_t identity;
  coap_bin_const_t key;
} coap_dtls_cpsk_info_t;
 
typedef const coap_dtls_cpsk_info_t *(*coap_dtls_ih_callback_t)(
                                struct coap_str_const_t *hint,
                                struct coap_session_t *coap_session,
                                void *arg);
 
#define COAP_DTLS_CPSK_SETUP_VERSION 1 
typedef struct coap_dtls_cpsk_t {
  uint8_t version; 
  /* Options to enable different TLS functionality in libcoap */
  uint8_t reserved[7];             
                                   /* Size of 7 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_CPSK_SETUP_VERSION and just
                                    * decrement the reserved[] count.
                                    */
 
  coap_dtls_ih_callback_t validate_ih_call_back;
  void *ih_call_back_arg;  
  char* client_sni;    
  coap_dtls_cpsk_info_t psk_info;  
} coap_dtls_cpsk_t;
 
typedef struct coap_dtls_spsk_info_t {
  coap_bin_const_t hint;
  coap_bin_const_t key;
} coap_dtls_spsk_info_t;
 
 
typedef const coap_bin_const_t *(*coap_dtls_id_callback_t)(
                                 struct coap_bin_const_t *identity,
                                 struct coap_session_t *coap_session,
                                 void *arg);
typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
                                 const char *sni,
                                 struct coap_session_t *coap_session,
                                 void *arg);
 
#define COAP_DTLS_SPSK_SETUP_VERSION 1 
typedef struct coap_dtls_spsk_t {
  uint8_t version; 
  /* Options to enable different TLS functionality in libcoap */
  uint8_t reserved[7];             
                                   /* Size of 7 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_SPSK_SETUP_VERSION and just
                                    * decrement the reserved[] count.
                                    */
 
  coap_dtls_id_callback_t validate_id_call_back;
  void *id_call_back_arg;  
  coap_dtls_psk_sni_callback_t validate_sni_call_back;
  void *sni_call_back_arg;  
  coap_dtls_spsk_info_t psk_info;  
} coap_dtls_spsk_t;
 
 
void *
coap_dtls_new_context(struct coap_context_t *coap_context);
 
typedef enum coap_dtls_role_t {
  COAP_DTLS_ROLE_CLIENT, 
  COAP_DTLS_ROLE_SERVER  
} coap_dtls_role_t;
 
int
coap_dtls_context_set_spsk(struct coap_context_t *coap_context,
                          coap_dtls_spsk_t *setup_data);
 
int
coap_dtls_context_set_cpsk(struct coap_context_t *coap_context,
                          coap_dtls_cpsk_t *setup_data);
 
int
coap_dtls_context_set_pki(struct coap_context_t *coap_context,
                          const coap_dtls_pki_t *setup_data,
                          const coap_dtls_role_t role);
 
int
coap_dtls_context_set_pki_root_cas(struct coap_context_t *coap_context,
                                   const char *ca_file,
                                   const char *ca_dir);
 
int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
 
void coap_dtls_free_context(void *dtls_context);
 
void *coap_dtls_new_client_session(struct coap_session_t *coap_session);
 
void *coap_dtls_new_server_session(struct coap_session_t *coap_session);
 
void coap_dtls_free_session(struct coap_session_t *coap_session);
 
void coap_dtls_session_update_mtu(struct coap_session_t *coap_session);
 
int coap_dtls_send(struct coap_session_t *coap_session,
                   const uint8_t *data,
                   size_t data_len);
 
int coap_dtls_is_context_timeout(void);
 
coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
 
coap_tick_t coap_dtls_get_timeout(struct coap_session_t *coap_session,
                                  coap_tick_t now);
 
void coap_dtls_handle_timeout(struct coap_session_t *coap_session);
 
int coap_dtls_receive(struct coap_session_t *coap_session,
                      const uint8_t *data,
                      size_t data_len);
 
int coap_dtls_hello(struct coap_session_t *coap_session,
                    const uint8_t *data,
                    size_t data_len);
 
unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session);
 
void *coap_tls_new_client_session(struct coap_session_t *coap_session, int *connected);
 
void *coap_tls_new_server_session(struct coap_session_t *coap_session, int *connected);
 
void coap_tls_free_session( struct coap_session_t *coap_session );
 
ssize_t coap_tls_write(struct coap_session_t *coap_session,
                       const uint8_t *data,
                       size_t data_len
                       );
 
ssize_t coap_tls_read(struct coap_session_t *coap_session,
                      uint8_t *data,
                      size_t data_len
                      );
 
void coap_dtls_startup(void);
 
void coap_dtls_shutdown(void);
 
void coap_dtls_set_log_level(int level);
 
int coap_dtls_get_log_level(void);
 
 
#endif /* COAP_DTLS_H */