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>
 * Copyright (C) 2023-2026 Jon Shallow <supjps-libcoap@jpshallow.com>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * 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 "coap_str.h"
 
#ifdef __cplusplus
extern "C" {
#endif

 
typedef struct coap_dtls_pki_t coap_dtls_pki_t;
 
#ifndef COAP_DTLS_HINT_LENGTH
#define COAP_DTLS_HINT_LENGTH 128
#endif
#ifndef COAP_DTLS_MAX_PSK_IDENTITY
#define COAP_DTLS_MAX_PSK_IDENTITY 64
#endif
#ifndef COAP_DTLS_MAX_PSK
#define COAP_DTLS_MAX_PSK 64
#endif
 
typedef enum coap_dtls_role_t {
  COAP_DTLS_ROLE_CLIENT, 
  COAP_DTLS_ROLE_SERVER  
} coap_dtls_role_t;
 
#define COAP_DTLS_RPK_CERT_CN "RPK"

int coap_tls_engine_configure(coap_str_const_t *conf_mem);

int coap_tls_engine_remove(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_WOLFSSL,   
  COAP_TLS_LIBRARY_OPENHITLS, 
} 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,
                                          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,
                                       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_DEFINE,         
} 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 enum {
  COAP_PKI_KEY_DEF_PEM = 0, 
  COAP_PKI_KEY_DEF_PEM_BUF, 
  COAP_PKI_KEY_DEF_RPK_BUF, 
  COAP_PKI_KEY_DEF_DER,     
  COAP_PKI_KEY_DEF_DER_BUF, 
  COAP_PKI_KEY_DEF_PKCS11,  
  COAP_PKI_KEY_DEF_PKCS11_RPK, 
  COAP_PKI_KEY_DEF_ENGINE,  
} coap_pki_define_t;

typedef struct coap_pki_key_define_t {
  coap_const_char_ptr_t ca;          
  coap_const_char_ptr_t public_cert; 
  coap_const_char_ptr_t private_key; 
  size_t ca_len;             
  size_t public_cert_len;    
  size_t private_key_len;    
  coap_pki_define_t ca_def;  
  coap_pki_define_t public_cert_def; 
  coap_pki_define_t private_key_def; 
  coap_asn1_privatekey_type_t private_key_type; 
  const char *user_pin;      
} coap_pki_key_define_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;    
    coap_pki_key_define_t define;    
  } 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 

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 use_cid;                 
  uint8_t allow_sni_cn_mismatch:1; 
  uint8_t reserved[1];             
  /* Size of 1 chosen to align to next
   * parameter, so if newly defined option
   * it can use one of the reserved slots so
   * no need to change
   * COAP_DTLS_PKI_SETUP_VERSION and just
   * decrement the reserved[] count.
   * [Now just adding 1 bit at a time].
   */

  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;  
};

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)(
    coap_str_const_t *hint,
    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 ec_jpake;        
  uint8_t use_cid;         
  uint8_t reserved[5];     
  /* Size of 5 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)(
    coap_bin_const_t *identity,
    coap_session_t *coap_session,
    void *arg);
typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
    const char *sni,
    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 ec_jpake;        
  uint8_t reserved[6];     
  /* 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_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;

 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_DTLS_H */