1COAP_ENCRYPTION(3) libcoap Manual COAP_ENCRYPTION(3)
2
6 coap_encryption, coap_dtls_cpsk_t, coap_dtls_spsk_t, coap_dtls_pki_t -
7 Work with CoAP TLS/DTLS
8
10 #include <coap3/coap.h>
11 struct coap_dtls_cpsk_t;
13 struct coap_dtls_spsk_t;
15 struct coap_dtls_pki_t;
17 For specific (D)TLS library support, link with -lcoap-3-notls,
19 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
20 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
21 (D)TLS library support.
22
24 This man page focuses on setting up CoAP to use encryption.
25 When the libcoap library was built, it will have been compiled using a
27 specific underlying TLS implementation type (e.g. OpenSSL, GnuTLS, Mbed
28 TLS, TinyDTLS or noTLS). When the libcoap library is linked into an
29 application, it is possible that the application needs to dynamically
30 determine whether DTLS or TLS is supported, what type of TLS
31 implementation libcoap was compiled with, as well as detect what is the
32 version of the currently loaded TLS library.
33 NOTE: If OpenSSL is being used, then the minimum supported OpenSSL
35 library version is 1.1.0.
36 NOTE: If GnuTLS is being used, then the minimum GnuTLS library version
38 is 3.3.0.
39 NOTE: If Mbed TLS is being used, then the minimum Mbed TLS library
41 version is 2.7.10.
42 NOTE: If GnuTLS is going to interoperate with TinyDTLS, then a minimum
44 revision of GnuTLS 3.5.5 which supports CCM algorithms is required by
45 TinyDTLS as TinyDTLS currently only supports CCM.
46 NOTE: For Raw Public Key support, GnuTLS library version must be 3.6.6
48 or later. TinyDTLS only supports TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8,
49 curve secp256r1 and hash SHA-256. There currently is no OpenSSL or Mbed
50 TLS RPK support (respective library limitations).
51 Network traffic can be un-encrypted or encrypted with libcoap if there
53 is an underlying TLS library.
54 If TLS is going to be used for encrypting the network traffic, then the
56 TLS information for Pre-Shared Keys (PSK), Public Key Infrastructure
57 (PKI) or Raw Public Key (RPK) needs to be configured before any network
58 traffic starts to flow. For Servers, this has to be done before the
59 Endpoint is created, for Clients, this is done during the Client
60 Session set up.
61 For Servers, all the encryption information is held internally by the
63 TLS Context level and the CoAP Context level as the Server is listening
64 for new incoming traffic based on the Endpoint definition. The TLS and
65 CoAP session will not get built until the new traffic starts, which is
66 done by the libcoap library, with the session having a reference count
67 of 1.
68 For Clients, all the encryption information will be held internally by
70 the TLS Context and/or TLS Session level and internally by the CoAP
71 Session level.
72 In principle the set-up sequence for CoAP Servers looks like
74 coap_new_context()
76 coap_context_set_pki_root_cas() - if the root CAs need to be updated and PKI
77 coap_context_set_pki() and/or coap_context_set_psk2() - if encryption is required
78 coap_new_endpoint()
79 Multiple endpoints can be set up per Context, each listening for a new
81 traffic flow with different TCP/UDP protocols, TLS protocols, port
82 numbers etc. When a new traffic flow is started, then the CoAP library
83 will create and start a new server session.
84 In principle the set-up sequence for CoAP Clients looks like
86 coap_new_context()
88 coap_context_set_pki_root_cas() - if the root CAs need to be updated and PKI
89 coap_new_client_session(), coap_new_client_session_pki() or coap_new_client_session_psk2()
90 Multiple client sessions are supported per Context.
92 Due to the nature of TLS, there are Callbacks that are invoked as the
94 TLS session negotiates encryption algorithms, encryption keys etc.
95 Where possible, the CoAP layer handles all this automatically based on
96 different configuration options passed in by the
97 coap_context_set_pki(), coap_new_client_session_pki(),
98 coap_context_set_psk2() and coap_new_client_session_psk2() functions.
99
101 For Client PSK setup, the required information needs to be provided in
102 the setup calls with optional application callbacks defined to update
103 the Identity and PSK. Initially, the Client has to provide an Identity
104 and a Pre-Shared Key.
105 Libcoap will put the Identity and Pre-Shared Key as appropriate into
107 the TLS environment.
108 SECTION: PSK Client: coap_dtls_cpsk_t
110 typedef struct coap_dtls_cpsk_t {
112 uint8_t version; /** Set to COAP_DTLS_CPSK_SETUP_VERSION
113 to support the version of the struct */
114 /* Options to enable different TLS functionality in libcoap */
116 uint8_t reserved[7]; /* Reserved - must be set to 0 for
117 future compatibility */
118 /** Identity Hint check callback function.
120 * If not NULL, is called when the Identity Hint (TLS1.2 or earlier) is
121 * provided by the server.
122 * The appropriate Identity and Pre-Shared Key to use can then be returned.
123 */
124 coap_dtls_ih_callback_t validate_ih_call_back;
125 void *ih_call_back_arg; /* Passed in to the Identity Hint callback
126 function */
127 char* client_sni; /* If not NULL, SNI to use in client TLS setup.
129 Owned by the client app and must remain valid
130 during the call to coap_new_client_session_pki().
131 Note: Not supported by TinyDTLS. */
132 coap_dtls_cpsk_info_t psk_info; /* Client PSK definition */
134 } coap_dtls_cpsk_t;
135 More detailed explanation of the coap_dtls_cpsk_t structure follows.
137 WARNING: For all the parameter definitions that are pointers to other
139 locations, these locations must remain valid during the lifetime of all
140 the underlying TLS sessions that are, or will get created based on this
141 PSK definition.
142 SECTION: PSK Client: coap_dtls_cpsk_t: Version
144 #define COAP_DTLS_CPSK_SETUP_VERSION 1 /**< Latest CPSK setup version */
146 version is set to COAP_DTLS_CPSK_SETUP_VERSION. This will then allow
148 support for different versions of the coap_dtls_cpsk_t structure in the
149 future.
150 SECTION: PSK Client: coap_dtls_cpsk_t: Reserved
152 reserved All must be set to 0. Future functionality updates will make
154 use of these reserved definitions.
155 SECTION: PSK Client: coap_dtls_cpsk_t: Identity Hint Callback
157 /**
159 * Identity Hint Validation callback that can be set up by
160 * coap_new_client_session_psk2().
161 * Invoked when libcoap has done the validation checks at the TLS level,
162 * but the application needs to check that the Identity Hint is allowed, and
163 * needs to use the appropriate PSK information for the (D)TLS session.
164 * Note: Identity Hint is not supported in (D)TLS1.3.
165 *
166 * @param hint The server provided Identity Hint
167 * @param coap_session The CoAP session associated with the Identity Hint
168 * @param arg The same as was passed into coap_new_client_session_psk2()
169 * in setup_data->ih_call_back_arg
170 *
171 * @return New coap_dtls_cpsk_info_t object or @c NULL on error.
172 */
173 typedef const coap_dtls_cpsk_info_t *(*coap_dtls_ih_callback_t)(
174 coap_str_const_t *hint,
175 coap_session_t *coap_session,
176 void *arg);
177 validate_ih_call_back points to an application provided Identity Hint
179 callback function or NULL. The application can make use of this
180 Identity Hint information to decide what Identity and Pre-Shared Key
181 should be used for this session. The Callback returns the new
182 coap_dtls_cpsk_info_t on success, or NULL if the Identity Hint is
183 unacceptable.
184 NOTE: The Server may not provide a hint, or a zero length hint to
186 indicate there is no hint. In this case the initially provided Identity
187 and Pre-Shared Key should be used.
188 ih_call_back_arg points to a user defined set of data that will get
190 passed in to the validate_ih_call_back() function’s arg parameter and
191 can be used by that function. An example would be a set of Identity
192 Hints that map into new Identity / Pre-Shared Key to use.
193 SECTION: PSK Client: coap_dtls_cpsk_t: Subject Name Indicator (SNI)
195 Definition
196 client_sni points to the SNI name that will be added in as a TLS
198 extension, if not NULL. This typically is the DNS name of the server
199 that the client is trying to contact. The server is then able to
200 decide, based on the name in the SNI extension, whether, for example, a
201 different Hint and/or Pre-Shared Key is to be used.
202 Note: Not supported by TinyDTLS.
204 SECTION: PSK Client: coap_dtls_cpsk_t: PSK Client Definitions
206 typedef struct coap_dtls_cpsk_info_t {
208 coap_bin_const_t identity; /* The Identity */
209 coap_bin_const_t key; /* The Pre-Shared Key */
210 } coap_dtls_cpsk_info_t;
211 identity defines the Identity to use.
213 key defines the Pre-Shared Key to use
215
217 For PSK setup, the required information needs to be provided in the
218 setup calls with optional application Callbacks defined to update the
219 Identity Hint and Pre-SHared Key. Initially, the Server has to provided
220 with an (optional) Identity Hint and a (required) Pre-Shared Key.
221 Libcoap will put the Hint and Pre-Shared Key as appropriate into the
223 TLS environment.
224 SECTION: PSK Server: coap_dtls_spsk_t
226 typedef struct coap_dtls_spsk_t {
228 uint8_t version; /** Set to COAP_DTLS_SPSK_SETUP_VERSION
229 to support the version of the struct */
230 /* Options to enable different TLS functionality in libcoap */
232 uint8_t reserved[7]; /* Reserved - must be set to 0 for
233 future compatibility */
234 /** Identity check callback function.
236 * If not @p NULL, is called when the Identity is provided by the client.
237 * The appropriate Pre-Shared Key to use can then be returned.
238 */
239 coap_dtls_id_callback_t validate_id_call_back;
240 void *id_call_back_arg; /* Passed in to the Identity callback function */
241 /** SNI check callback function.
243 * If not @p NULL, called if the SNI is not previously seen and exexuted
244 * prior to sending an Identity Hint back to the client so that the
245 * appropriate PSK information can be used based on the requesting SNI.
246 */
247 coap_dtls_psk_sni_callback_t validate_sni_call_back;
248 void *sni_call_back_arg; /* Passed in to the SNI callback function */
249 coap_dtls_spsk_info_t psk_info; /* Server PSK definition */
251 } coap_dtls_spsk_t;
252 More detailed explanation of the coap_dtls_spsk_t structure follows.
254 WARNING: For all the parameter definitions that are pointers to other
256 locations, these locations must remain valid during the lifetime of all
257 the underlying TLS sessions that are, or will get created based on this
258 PSK definition.
259 SECTION: PSK Server: coap_dtls_spsk_t: Version
261 #define COAP_DTLS_SPSK_SETUP_VERSION 1 /**< Latest SPSK setup version */
263 version is set to COAP_DTLS_SPSK_SETUP_VERSION. This will then allow
265 support for different versions of the coap_dtls_spsk_t structure in the
266 future.
267 SECTION: PSK Server: coap_dtls_spsk_t: Reserved
269 reserved All must be set to 0. Future functionality updates will make
271 use of these reserved definitions.
272 SECTION: PSK Server: coap_dtls_spsk_t: Identity Validation Callback
274 /**
276 * Identity Validation callback that can be set up by
277 * coap_context_set_psk2().
278 * Invoked when libcoap has done the validation checks at the TLS level,
279 * but the application needs to check that the Identity is allowed, and
280 * needs to use the appropriate Pre-Shared Key for the (D)TLS session.
281 *
282 * @param identity The client provided Identity (should be NULL terminated)
283 * @param coap_session The CoAP session associated with the Identity Hint
284 * @param arg The same as was passed into coap_context_set_psk2()
285 * in setup_data->id_call_back_arg
286 *
287 * @return New coap_bin_const_t Pre-Shared Key object or @c NULL on error.
288 */
289 typedef const coap_bin_const_t *(*coap_dtls_id_callback_t)(
290 coap_bin_const_t *identity,
291 coap_session_t *coap_session,
292 void *arg);
293 WARNING: If both validate_id_call_back and validate_sni_call_back are
295 defined, validate_id_call_back() is invoked after
296 validate_sni_call_back(), and so if the Pre-Shared Key is changed in
297 validate_sni_call_back(), validate_id_call_back() needs to be sure that
298 the appropriate Pre-Shared Key is provided.
299 validate_id_call_back points to an application provided Identity
301 callback function or NULL. The application can make use of this
302 Identity information to decide what PSK should be used for this
303 session. The Callback returns the new coap_bin_const_t Pre-Shared Key
304 on success, or NULL if the Identity is unacceptable.
305 NOTE: The Client may be using a binary Identity that contains an
307 embedded zero. However OpenSSL and GnuTLS do not currently support
308 this.
309 id_call_back_arg points to a user defined set of data that will get
311 passed in to the validate_id_call_back() function and can be used by
312 that function. An example would be a set of Identities that map into
313 new Pre-Shared Keys to use.
314 SECTION: PSK Server: coap_dtls_spsk_t: Subject Name Identifier (SNI)
316 Callback
317 /**
319 * PSK SNI callback that can be set up by coap_context_set_psk2().
320 * Invoked when libcoap has done the validation checks at the TLS level,
321 * but the application needs to check that the SNI is allowed, and needs
322 * to use the appropriate PSK information for the (D)TLS session.
323 *
324 * @param sni The client provided SNI
325 * @param coap_session The CoAP session associated with the SNI
326 * @param arg The same as was passed into coap_new_client_session_psk2()
327 * in setup_data->sni_call_back_arg
328 *
329 * @return New coap_dtls_spsk_info_t object or @c NULL on error.
330 */
331 typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
332 const char *sni,
333 coap_session_t *coap_session,
334 void *arg);
335 validate_sni_call_back points to an application provided SNI callback
337 checking function or NULL. The application can make use of this SNI
338 information to decide whether the SNI is valid, and hence what new Hint
339 and Pre-Shared Key to use. Thus it is possible for the coap server to
340 host multiple domains with different Hints and PSKs allocated to each
341 SNI domain. The Callback returns a coap_dtls_spsk_info_t pointer to the
342 Hint and Pre-Shared Key to use for this SNI, or NULL if the connection
343 is to get rejected. Libcoap remembers the association between a
344 specific SNI and Hint Pre-Shared Key set and will only invoke this
345 callback if the SNI is unknown.
346 Note: Not supported by TinyDTLS.
348 sni_call_back_arg points to a user defined set of data that will get
350 passed in to the validate_sni_call_back() function and can be used by
351 that function. An example would be a set of SNIs that are allowed with
352 their matching Hint + Pre-Shared Key sets.
353 SECTION: PSK Server: coap_dtls_spsk_t: PSK Information Definitions
355 typedef struct coap_dtls_spsk_info_t {
357 coap_bin_const_t hint; /* The identity hint to use */
358 coap_bin_const_t key; /* The Pre-Shared Key to use */
359 } coap_dtls_spsk_info_t;
360 identity defines the Identity Hint to use.
362 key defines the Pre-Shared Key to use
364
366 For PKI or RPK setup, if the libcoap PKI/RPK configuration options do
367 not handle a specific requirement as defined by the available options,
368 then an application defined Callback can called to do the additional
369 specific checks.
370 The information passed to this Application Callback will be the TLS
372 session (as well the configuration information), but the structures
373 containing this information will be different as they will be based on
374 the underlying TLS library type. coap_get_tls_library_version() is
375 provided to help here.
376 Libcoap will add in the defined Certificate (or Public Key), Private
378 Key and CA Certificate into the TLS environment. The CA Certificate is
379 also added in to the list of valid CAs for Certificate checking.
380 The internal Callbacks (and optionally the Application Callback) will
382 then check the required information as defined in the coap_dtls_pki_t
383 described below.
384 SECTION: PKI/RPK: coap_dtls_pki_t
386 typedef struct coap_dtls_pki_t {
388 uint8_t version; /* COAP_DTLS_PKI_SETUP_VERSION */
389 /* Options to enable different TLS functionality in libcoap */
391 uint8_t verify_peer_cert; /* 1 if peer cert is to be verified */
392 uint8_t check_common_ca; /* 1 if peer cert is to be signed by
393 * the same CA as the local cert */
394 uint8_t allow_self_signed; /* 1 if self-signed certs are allowed */
395 uint8_t allow_self_signed; /* 1 if self-signed certs are allowed.
396 * Ignored if check_common_ca set */
397 uint8_t allow_expired_certs; /* 1 if expired certs are allowed */
398 uint8_t cert_chain_validation; /* 1 if to check cert_chain_verify_depth */
399 uint8_t cert_chain_verify_depth; /* recommended depth is 3 */
400 uint8_t check_cert_revocation; /* 1 if revocation checks wanted */
401 uint8_t allow_no_crl; /* 1 ignore if CRL not there */
402 uint8_t allow_expired_crl; /* 1 if expired crl is allowed */
403 uint8_t allow_bad_md_hash; /* 1 if unsupported MD hashes are allowed */
404 uint8_t allow_short_rsa_length; /* 1 if small RSA keysizes are allowed */
405 uint8_t is_rpk_not_cert; /* 1 is RPK instead of Public Certificate.
406 * If set, PKI key format type cannot be
407 * COAP_PKI_KEY_PEM */
408 uint8_t reserved[3]; /* Reserved - must be set to 0 for
409 future compatibility */
410 /** CN check callback function
412 * If not NULL, is called when the TLS connection has passed the configured
413 * TLS options above for the application to verify if the CN is valid.
414 */
415 coap_dtls_cn_callback_t validate_cn_call_back;
416 void *cn_call_back_arg; /* Passed in to the CN callback function */
417 /** SNI check callback function
419 * If not NULL, called if the SNI is not previously seen and prior to sending
420 * a certificate set back to the client so that the appropriate certificate
421 * set can be used based on the requesting SNI.
422 */
423 coap_dtls_sni_callback_t validate_sni_call_back;
424 void *sni_call_back_arg; /* Passed in to the SNI callback function */
425 /** Additional Security callback handler that is invoked when libcoap has
427 * done the standard, defined validation checks at the TLS level,
428 * If not NULL, called from within the TLS Client Hello connection
429 * setup.
430 */
431 coap_dtls_security_setup_t additional_tls_setup_call_back;
432 char* client_sni; /* If not NULL, SNI to use in client TLS setup.
434 Owned by the client app and must remain valid
435 during the call to coap_new_client_session_pki() */
436 coap_dtls_key_t pki_key; /* PKI key definition */
438 } coap_dtls_pki_t;
439 More detailed explanation of the coap_dtls_pki_t structure follows.
441 WARNING: For all the parameter definitions that are pointers to other
443 locations, these locations must remain valid during the lifetime of all
444 the underlying TLS sessions that are, or will get created based on this
445 PKI/RPK definition.
446 The first parameter in each subsection enables/disables the
448 functionality, the remaining parameter(s) control what happens when the
449 functionality is enabled.
450 SECTION: PKI/RPK: coap_dtls_pki_t: Version
452 #define COAP_DTLS_PKI_SETUP_VERSION 1
454 version is set to COAP_DTLS_PKI_SETUP_VERSION. This will then allow
456 support for different versions of the coap_dtls_pki_t structure in the
457 future.
458 SECTION: PKI/RPK: coap_dtls_pki_t: Peer Certificate Checking
460 verify_peer_cert Set to 1 to check that the peer’s certificate is valid
462 if provided, else 0. If not set, check_common_ca, allow_self_signed,
463 allow_expired_certs, cert_chain_validation, cert_chain_verify_depth,
464 check_cert_revocation, allow_no_crl, allow_expired_crl,
465 allow_bad_md_hash and allow_short_rsa_length settings are all ignored.
466 check_common_ca Set to 1 to check that the CA that signed the peer’s
468 certificate is the same CA that signed the local certificate else 0. If
469 set to 1 and verify_peer_cert is set to 1, then for the server, a list
470 of valid CAs are sent to client. For the client, the logic will check
471 that both the client and server certificates are signed by the same CA.
472 allow_self_signed Set to 1 to allow the peer (or any certificate in the
474 certificate chain) to be a self-signed certificate, else 0. If
475 check_common_ca is set, then a self-signed certificate will not be
476 allowed.
477 allow_expired_certs Set to 1 to allow certificates that have either
479 expired, or are not yet valid to be allowed, else 0.
480 SECTION: PKI/RPK: coap_dtls_pki_t: Certificate Chain Validation
482 cert_chain_validation Set to 1 to check that the certificate chain is
484 valid, else 0.
485 cert_chain_verify_depth Set to the chain depth that is to be checked.
487 This is the number of intermediate CAs in the chain. If set to 0, then
488 there can be no intermediate CA in the chain.
489 SECTION: PKI/RPK: coap_dtls_pki_t: Certificate Revocation
491 check_cert_revocation Set to 1 to check whether any certificate in the
493 chain has been revoked, else 0.
494 allow_no_crl Set to 1 to not check any certificate that does not have a
496 CRL, else 0.
497 allow_expired_crl Set to 1 to allow an certificate that has an expired
499 CRL definition to be valid, else 0.
500 SECTION: PKI/RPK: coap_dtls_pki_t: Other
502 allow_bad_md_hash Set to 1 if unsupported MD hashes are allowed, else
504 0.
505 allow_short_rsa_length Set to 1 if small RSA keysizes are allowed, else
507 0.
508 is_rpk_not_cert Set to 1 if the Certificate is actually a Raw Public
510 Key. If set, PKI key format type cannot be COAP_PKI_KEY_PEM. If set,
511 check_common_ca, allow_self_signed, allow_expired_certs,
512 cert_chain_validation, cert_chain_verify_depth, check_cert_revocation,
513 allow_no_crl, allow_expired_crl, allow_bad_md_hash and
514 allow_short_rsa_length settings are all ignored.
515 SECTION: PKI/RPK: coap_dtls_pki_t: Reserved
517 reserved All must be set to 0. Future functionality updates will make
519 use of these reserved definitions.
520 SECTION: PKI/RPK: coap_dtls_pki_t: Common Name (CN) Callback
522 #define COAP_DTLS_RPK_CERT_CN "RPK"
524 /**
526 * CN Validation callback that can be set up by coap_context_set_pki().
527 * Invoked when libcoap has done the validation checks at the TLS level,
528 * but the application needs to check that the CN is allowed.
529 * CN is the SubjectAltName in the cert, if not present, then the leftmost
530 * Common Name (CN) component of the subject name.
531 * NOTE: If using RPK, then the Public Key does not contain a CN, but the
532 * content of COAP_DTLS_RPK_CERT_CN is presented for the @p cn parameter.
533 *
534 * @param cn The determined CN from the certificate
535 * @param asn1_public_cert The ASN.1 encoded (DER) X.509 certificate
536 * @param asn1_length The ASN.1 length
537 * @param session The coap session associated with the certificate update
538 * @param depth Depth in cert chain. If 0, then client cert, else a CA
539 * @param validated TLS can find no issues if 1
540 * @param arg The same as was passed into coap_context_set_pki()
541 * in setup_data->cn_call_back_arg
542 *
543 * @return 1 if accepted, else 0 if to be rejected
544 */
545 typedef int (*coap_dtls_cn_callback_t)(const char *cn,
546 const uint8_t *asn1_public_cert,
547 size_t asn1_length,
548 coap_session_t *session,
549 unsigned int depth,
550 int validated,
551 void *arg);
552 validate_cn_call_back points to an application provided CN callback
554 checking function or NULL. The application can make use of this CN
555 information to decide, for example, that the CN is valid coming from a
556 particular peer. The Callback returns 1 on success, 0 if the TLS
557 connection is to be aborted.
558 cn_call_back_arg points to a user defined set of data that will get
560 passed in to the validate_cn_call_back() function and can be used by
561 that function. An example would be a set of CNs that are allowed.
562 SECTION: PKI/RPK: coap_dtls_pki_t: Subject Name Identifier (SNI)
564 Callback
565 typedef struct coap_dtls_key_t {
567 coap_pki_key_t key_type; /* key format type */
568 union {
569 coap_pki_key_pem_t pem; /* for PEM file keys */
570 coap_pki_key_pem_buf_t pem_buf; /* for PEM memory keys */
571 coap_pki_key_asn1_t asn1; /* for ASN.1 (DER) memory keys */
572 coap_pki_key_pkcs11_t pkcs11; /* for PKCS11 keys */
573 } key;
574 } coap_dtls_key_t;
575 /**
577 * SNI Validation callback that can be set up by coap_context_set_pki().
578 * Invoked if the SNI is not previously seen and prior to sending a certificate
579 * set back to the client so that the appropriate certificate set can be used
580 * based on the requesting SNI.
581 *
582 * @param sni The requested SNI
583 * @param arg The same as was passed into coap_context_set_pki()
584 * in setup_data->sni_call_back_arg
585 *
586 * @return new set of certificates to use, or NULL if SNI is to be rejected.
587 */
588 typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
589 void* arg);
590 validate_sni_call_back points to an application provided SNI callback
592 checking function or NULL. The application can make use of this SNI
593 information to decide whether the SNI is valid, and what set of
594 certificates to give to the client. Thus it is possible for the coap
595 server to host multiple domains with different certificates allocated
596 to each domain. The Callback returns a pointer to the certificates to
597 use for this SNI, or NULL if the connection it to get rejected. libcoap
598 remembers the association between the SNI and Certificate set and will
599 only invoke this callback if the SNI is unknown.
600 sni_call_back_arg points to a user defined set of data that will get
602 passed in to the validate_sni_call_back() function and can be used by
603 that function. An example would be a set of SNIs that are allowed with
604 their matching certificate sets.
605 SECTION: PKI/RPK: coap_dtls_pki_t: Application Additional Setup
607 Callback
608 /**
610 * Additional Security setup handler that can be set up by
611 * coap_context_set_pki().
612 * Invoked when libcoap has done the validation checks at the TLS level,
613 * but the application needs to do some additional checks/changes/updates.
614 *
615 * @param session The security session definition - e.g. SSL * for OpenSSL.
616 * This will be dependent on the underlying TLS library
617 * - see coap_get_tls_library_version()
618 * @param setup_data A structure containing setup data originally passed into
619 * coap_context_set_pki() or coap_new_client_session_pki().
620 * @return 1 if successful, else 0
621 */
622 typedef int (*coap_dtls_security_setup_t)(void *context, void* session,
623 coap_dtls_pki_t *setup_data);
624 additional_tls_setup_call_back points to an application provided
626 callback function that will do additional checking/changes/updates
627 after libcoap has done all of the configured TLS setup checking, or
628 NULL to do no additional checking.
629 SECTION: PKI/RPK: coap_dtls_pki_t: Subject Name Indicator (SNI)
631 Definition
632 client_sni points to the SNI name that will be added in as a TLS
634 extension, or set NULL. This typically is the DNS name of the server
635 that the client is trying to contact. This is only used by a client
636 application and the server is then able to decide, based on the name in
637 the SNI extension, whether, for example, a different certificate should
638 be provided.
639 SECTION: PKI/RPK: coap_dtls_pki_t: Key Type Definition
641 typedef enum coap_pki_key_t {
643 COAP_PKI_KEY_PEM, /* The PKI key type is PEM file */
644 COAP_PKI_KEY_ASN1, /* The PKI key type is ASN.1 (DER) buffer */
645 COAP_PKI_KEY_PEM_BUF, /* The PKI key type is PEM buffer */
646 COAP_PKI_KEY_PKCS11, /* The PKI key type is PKCS11 (DER) */
647 } coap_pki_key_t;
648 key_type defines the format that the certificates / keys are provided
650 in. This can be COAP_PKI_KEY_PEM, COAP_PKI_KEY_PEM_BUF,
651 COAP_PKI_KEY_ASN1 or COAP_PKI_KEY_PKCS11.
652 SECTION: PKI: coap_dtls_pki_t: PEM Key Definitions
654 typedef struct coap_pki_key_pem_t {
656 const char *ca_file; /* File location of Common CA in PEM format */
657 const char *public_cert; /* File location of Public Cert */
658 const char *private_key; /* File location of Private Key in PEM format */
659 } coap_pki_key_pem_t;
660 key.pem.ca_file points to the CA File location on disk which will be in
662 PEM format, or NULL. This file should only contain one CA (that has
663 signed the public certificate) as this is passed from the server to the
664 client when requesting the client’s certificate. This certificate is
665 also added into the valid root CAs list if not already present.
666 key.pem.public_cert points to the public certificate location on disk
668 which will be in PEM format.
669 key.pem.private_key points to the private key location on disk which
671 will be in PEM format. This file cannot be password protected.
672 SECTION: PKI/RPK: coap_dtls_pki_t: PEM Memory Key Definitions
674 typedef struct coap_pki_key_pem_buf_t {
676 const uint8_t *ca_cert; /* PEM buffer Common CA Cert */
677 const uint8_t *public_cert; /* PEM buffer Public Cert, or Public Key if RPK */
678 const uint8_t *private_key; /* PEM buffer Private Key */
679 If RPK and 'EC PRIVATE KEY' this can be used
680 for both the public_cert and private_key */
681 size_t ca_cert_len; /* PEM buffer CA Cert length */
682 size_t public_cert_len; /* PEM buffer Public Cert length */
683 size_t private_key_len; /* PEM buffer Private Key length */
684 } coap_pki_key_pem_buf_t;
685 key.pem_buf.ca_cert points to the CA location in memory which will be
687 in PEM format, or NULL. This file should only contain one CA (that has
688 signed the public certificate) as this is passed from the server to the
689 client when requesting the client’s certificate. This certificate is
690 also added into the valid root CAs list if not already present.
691 key.pem_buf.ca_cert_len is the length of the CA.
693 key.pem_buf.public_cert points to the public certificate (or public key
695 if RPK) location in memory which will be in PEM format.
696 key.pem_buf.public_cert_len is the length of the public certificate.
698 key.pem_buf.private_key points to the private key location in memory
700 which will be in PEM format. This data cannot be password protected. If
701 RPK and EC PRIVATE KEY this can be used for both the public_cert and
702 private_key.
703 key.pem_buf.private_key is the length of the private key.
705 • Note:* The PEM buffer Certs and Key should be be NULL terminated
707 strings for performance reasons (to save a potential buffer copy)
708 and the length include this NULL terminator. It is not a
709 requirement to have the NULL terminator though and the length must
710 then reflect the actual data size.
711 SECTION: PKI/RPK: coap_dtls_pki_t: ASN1 Key Definitions
713 typedef struct coap_pki_key_asn1_t {
715 const uint8_t *ca_cert; /* ASN1 Common CA Certificate */
716 const uint8_t *public_cert; /* ASN1 (DER) Public Cert, or Public Key if RPK */
717 const uint8_t *private_key; /* ASN1 Private Key */
718 int ca_cert_len; /* ASN1 CA Certificate length */
719 int public_cert_len; /* ASN1 Public Certificate length */
720 int private_key_len; /* ASN1 Private Key length */
721 coap_asn1_privatekey_type_t private_key_type; /* Private Key Type
722 COAP_ASN1_PKEY_* */
723 } coap_pki_key_asn1_t;
724 typedef enum coap_asn1_privatekey_type_t {
726 COAP_ASN1_PKEY_NONE,
727 COAP_ASN1_PKEY_RSA,
728 COAP_ASN1_PKEY_RSA2,
729 COAP_ASN1_PKEY_DSA,
730 COAP_ASN1_PKEY_DSA1,
731 COAP_ASN1_PKEY_DSA2,
732 COAP_ASN1_PKEY_DSA3,
733 COAP_ASN1_PKEY_DSA4,
734 COAP_ASN1_PKEY_DH,
735 COAP_ASN1_PKEY_DHX,
736 COAP_ASN1_PKEY_EC,
737 COAP_ASN1_PKEY_HMAC,
738 COAP_ASN1_PKEY_CMAC,
739 COAP_ASN1_PKEY_TLS1_PRF,
740 COAP_ASN1_PKEY_HKDF
741 } coap_asn1_privatekey_type_t;
742 key.asn1.ca_cert points to a DER encoded ASN.1 definition of the CA
744 Certificate, or NULL. This certificate is passed from the server to the
745 client when requesting the client’s certificate. This certificate is
746 also added into the valid root CAs list if not already present.
747 key.asn1.public_cert points to a DER encoded ASN.1 definition of the
749 public certificate (or public key if RPK).
750 key.asn1.private_key points to DER encoded ASN.1 definition of the
752 private key.
753 key.asn1.ca_cert_len is the length of the DER encoded ASN.1 definition
755 of the CA Certificate.
756 key.asn1.public_cert_len is the length of the DER encoded ASN.1
758 definition of the public certificate.
759 key.asn1.private_key_len is the length of the DER encoded ASN.1
761 definition of the private key.
762 key.asn1.private_key_type is the encoding type of the DER encoded ASN.1
764 definition of the private key. This will be one of the COAP_ASN1_PKEY_*
765 definitions.
766 SECTION: PKI: coap_dtls_pki_t: PKCS11 Key Definitions
768 typedef struct coap_pki_key_pkcs11_t {
770 const char *ca; /* pkcs11: URI for Common CA Certificate */
771 const char *public_cert; /* pkcs11: URI for Public Cert */
772 const char *private_key; /* pkcs11: URI for Private Key */
773 const char *pin; /* pin to access PKCS11. If NULL, then
774 pin-value= parameter must be set in
775 pkcs11: URI as a query. */
776 } coap_pki_key_pkcs11_t;
777 key.pkcs11.ca is a pkcs11: URI for the CA certificate or NULL. This is
779 for the CA (that has signed the public certificate) as this is passed
780 from the server to the client when requesting the client’s certificate.
781 This certificate is also added into the valid root CAs list if not
782 already present. An example URI is
783 pkcs11:pkcs11:token=My%20Token;id=%aa%bb%cc%dd which is for token My
784 Token and (hex) id of aabbccdd.
785 key.pkcs11.public_cert is a pkcs11: URI for the Public Certificate
787 which was signed by key.pkcs11.ca or NULL.
788 key.pkcs11.private_key is a pkcs11: URI for the Private Key for the
790 public certificate defined by key.pkcs11.public_cert or NULL.
791 key.pkcs11.user_pin is the user pin used to unlock the token or NULL.
793 If NULL, the pin can be defined on the other pkcs11: URI entries by
794 using pin-value=XXX as a query - e.g.
795 pkcs11:pkcs11:token=My%20Token;id=%aa%bb%cc%dd?pin-value=XXX where XXX
796 is the user pin.
797
799 CoAP Server DTLS PKI Setup
800 #include <coap3/coap.h>
802 typedef struct valid_cns_t {
804 int count;
805 char **cn_list;
806 } valid_cns_t;
807 /**
809 * CN Validation callback that can be set up by coap_context_set_pki().
810 * Invoked when libcoap has done the validation checks at the TLS level,
811 * but the application needs to check that the CN is allowed.
812 * CN is the SubjectAltName in the cert, if not present, then the leftmost
813 * Common Name (CN) component of the subject name.
814 * NOTE: If using RPK, then the Public Key does not contain a CN, but "RPK"
815 * is presented for the cn parameter.
816 *
817 * @param cn The determined CN from the certificate
818 * @param asn1_public_cert The ASN.1 encoded (DER) X.509 certificate
819 * @param asn1_length The ASN.1 length
820 * @param session The coap session associated with the certificate update
821 * @param depth Depth in cert chain. If 0, then client cert, else a CA
822 * @param validated TLS can find no issues if 1
823 * @param arg The same as was passed into coap_context_set_pki()
824 * in setup_data->cn_call_back_arg
825 *
826 * @return 1 if accepted, else 0 if to be rejected
827 */
828 static int
829 verify_cn_callback(const char *cn,
830 const uint8_t *asn1_public_cert,
831 size_t asn1_length,
832 coap_session_t *c_session,
833 unsigned depth,
834 int validated,
835 void *arg
836 ) {
837 valid_cns_t *valid_cn_list = (valid_cns_t*)arg;
838 int i;
839 /* Remove (void) definition if variable is used */
840 (void)asn1_public_cert;
841 (void)asn1_length;
842 (void)c_session;
843 (void)depth;
844 (void)validated;
845 /* Check that the CN is valid */
847 for (i = 0; i < valid_cn_list->count; i++) {
848 if (!strcasecmp(cn, valid_cn_list->cn_list[i])) {
849 return 1;
850 }
851 }
852 return 0;
853 }
854 typedef struct sni_def_t {
856 char* sni;
857 coap_dtls_key_t key;
858 } sni_def_t;
859 typedef struct valid_snis_t {
861 int count;
862 sni_def_t *sni_list;
863 } valid_snis_t;
864 /**
866 * SNI Validation callback that is set up by coap_context_set_pki().
867 * Invoked if the SNI is not previously seen and prior to sending a certificate
868 * set back to the client so that the appropriate certificate set can be used
869 * based on the requesting SNI.
870 *
871 * @param sni The requested SNI
872 * @param arg The same as was passed into coap_context_set_pki()
873 * in setup_data->sni_call_back_arg
874 *
875 * @return new set of certificates to use, or NULL if SNI is to be rejected.
876 */
877 static coap_dtls_key_t *
878 verify_pki_sni_callback(const char *sni,
879 void *arg
880 ) {
881 valid_snis_t *valid_sni_list = (valid_snis_t *)arg;
882 int i;
883 /* Check that the SNI is valid */
885 for (i = 0; i < valid_sni_list->count; i++) {
886 if (!strcasecmp(sni, valid_sni_list->sni_list[i].sni)) {
887 return &valid_sni_list->sni_list[i].key;
888 }
889 }
890 return NULL;
891 }
892 /*
894 * Set up PKI encryption information
895 */
896 static coap_context_t *
897 setup_server_context_pki (const char *public_cert_file,
898 const char *private_key_file,
899 const char *ca_file,
900 valid_cns_t *valid_cn_list,
901 valid_snis_t *valid_sni_list
902 ) {
903 coap_endpoint_t *endpoint;
904 coap_address_t listen_addr;
905 coap_dtls_pki_t dtls_pki;
906 coap_context_t *context;
907 /* See coap_tls_library(3) */
909 if (!coap_dtls_is_supported())
910 return NULL;
911 /* See coap_context(3) */
913 context = coap_new_context(NULL);
914 if (!context)
915 return NULL;
916 /* See coap_block(3) */
917 coap_context_set_block_mode(context,
918 COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);
919 memset (&dtls_pki, 0, sizeof (dtls_pki));
922 dtls_pki.version = COAP_DTLS_PKI_SETUP_VERSION;
924 dtls_pki.verify_peer_cert = 1;
925 dtls_pki.check_common_ca = 1;
926 dtls_pki.allow_self_signed = 1;
927 dtls_pki.allow_expired_certs = 1;
928 dtls_pki.cert_chain_validation = 1;
929 dtls_pki.cert_chain_verify_depth = 1;
930 dtls_pki.check_cert_revocation = 1;
931 dtls_pki.allow_no_crl = 1;
932 dtls_pki.allow_expired_crl = 1;
933 dtls_pki.allow_bad_md_hash = 0;
934 dtls_pki.allow_short_rsa_length = 0;
935 dtls_pki.is_rpk_not_cert = 0; /* Set to 1 if RPK */
936 dtls_pki.validate_cn_call_back = verify_cn_callback;
937 dtls_pki.cn_call_back_arg = valid_cn_list;
938 dtls_pki.validate_sni_call_back = verify_pki_sni_callback;
939 dtls_pki.sni_call_back_arg = valid_sni_list;
940 dtls_pki.additional_tls_setup_call_back = NULL;
941 dtls_pki.client_sni = NULL;
942 dtls_pki.pki_key.key_type = COAP_PKI_KEY_PEM;
943 dtls_pki.pki_key.key.pem.ca_file = ca_file;
944 dtls_pki.pki_key.key.pem.public_cert = public_cert_file;
945 dtls_pki.pki_key.key.pem.private_key = private_key_file;
946 /* See coap_context(3) */
948 if (coap_context_set_pki(context, &dtls_pki)) {
949 coap_free_context(context);
950 return NULL;
951 }
952 coap_address_init(&listen_addr);
954 listen_addr.addr.sa.sa_family = AF_INET;
955 listen_addr.addr.sin.sin_port = htons (5684);
956 /* See coap_context(3) */
958 endpoint = coap_new_endpoint(context, &listen_addr, COAP_PROTO_DTLS);
959 if (!endpoint) {
960 coap_free_context(context);
961 return NULL;
962 }
963 /* Initialize resources - See coap_resource(3) init_resources() example */
965 return context;
967 }
968 CoAP Server DTLS PSK Setup
970 #include <coap3/coap.h>
972 typedef struct id_def_t {
974 char *hint_match;
975 coap_bin_const_t id;
976 coap_bin_const_t key;
977 } id_def_t;
978 typedef struct valid_ids_t {
980 size_t count;
981 id_def_t *id_list;
982 } valid_ids_t;
983 /*
985 * PSK Identity Pre-Shared Key selection Callback function
986 */
987 static const coap_bin_const_t *
988 verify_id_callback(coap_bin_const_t *identity,
989 coap_session_t *c_session,
990 void *arg
991 ) {
992 valid_ids_t *valid_id_list = (valid_ids_t*)arg;
993 const coap_bin_const_t *s_psk_hint = coap_session_get_psk_hint(c_session);
994 size_t i;
995 /* Check that the Identity is valid */
997 for (i = 0; i < valid_id_list->count; i++) {
998 if (s_psk_hint &&
999 strcmp((const char *)s_psk_hint->s,
1000 valid_id_list->id_list[i].hint_match)) {
1001 continue;
1002 }
1003 if (coap_binary_equal(identity, &valid_id_list->id_list[i].id)) {
1004 return &valid_id_list->id_list[i].key;
1005 }
1006 }
1007 return NULL;
1008 }
1009 typedef struct sni_psk_def_t {
1011 char* sni;
1012 coap_dtls_spsk_info_t psk_info;
1013 } sni_psk_def_t;
1014 typedef struct valid_psk_snis_t {
1016 int count;
1017 sni_psk_def_t *sni_list;
1018 } valid_psk_snis_t;
1019 /*
1021 * PSK Subject Name Identifier (SNI) callback verifier
1022 */
1023 static const coap_dtls_spsk_info_t *
1024 verify_psk_sni_callback(const char *sni,
1025 coap_session_t *c_session,
1026 void *arg
1027 ) {
1028 valid_psk_snis_t *valid_sni_list = (valid_psk_snis_t *)arg;
1029 int i;
1030 /* Remove (void) definition if variable is used */
1031 (void)c_session;
1032 /* Check that the SNI is valid */
1034 for (i = 0; i < valid_sni_list->count; i++) {
1035 if (!strcasecmp(sni, valid_sni_list->sni_list[i].sni)) {
1036 return &valid_sni_list->sni_list[i].psk_info;
1037 }
1038 }
1039 return NULL;
1040 }
1041 static coap_context_t *
1043 setup_server_context_psk (const char *hint,
1044 const uint8_t *key,
1045 unsigned int key_len,
1046 valid_ids_t *valid_id_list,
1047 valid_psk_snis_t *valid_sni_list
1048 ) {
1049 coap_endpoint_t *endpoint;
1050 coap_address_t listen_addr;
1051 coap_context_t *context;
1052 coap_dtls_spsk_t dtls_psk;
1053 /* See coap_tls_library(3) */
1055 if (!coap_dtls_is_supported())
1056 return NULL;
1057 context = coap_new_context(NULL);
1059 if (!context)
1060 return NULL;
1061 /* See coap_block(3) */
1062 coap_context_set_block_mode(context,
1063 COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);
1064 memset (&dtls_psk, 0, sizeof (dtls_psk));
1067 /* see coap_encryption(3) */
1069 dtls_psk.version = COAP_DTLS_SPSK_SETUP_VERSION;
1070 dtls_psk.validate_id_call_back = verify_id_callback;
1071 dtls_psk.id_call_back_arg = valid_id_list;
1072 dtls_psk.validate_sni_call_back = verify_psk_sni_callback;
1073 dtls_psk.sni_call_back_arg = valid_sni_list;
1074 dtls_psk.psk_info.hint.s = (const uint8_t*)hint;
1075 dtls_psk.psk_info.hint.length = hint ? strlen(hint) : 0;
1076 dtls_psk.psk_info.key.s = key;
1077 dtls_psk.psk_info.key.length = key_len;
1078 if (coap_context_set_psk2(context, &dtls_psk)) {
1080 coap_free_context(context);
1081 return NULL;
1082 }
1083 coap_address_init(&listen_addr);
1085 listen_addr.addr.sa.sa_family = AF_INET;
1086 listen_addr.addr.sin.sin_port = htons (5684);
1087 endpoint = coap_new_endpoint(context, &listen_addr, COAP_PROTO_DTLS);
1089 if (!endpoint) {
1090 coap_free_context(context);
1091 return NULL;
1092 }
1093 /* Initialize resources - See coap_resource(3) init_resources() example */
1095 return context;
1097 }
1098 CoAP Client DTLS PSK Setup
1100 #include <coap3/coap.h>
1102 #include <stdio.h>
1104 #ifndef min
1106 #define min(a,b) ((a) < (b) ? (a) : (b))
1107 #endif
1108 static const coap_dtls_cpsk_info_t *
1110 verify_ih_callback(coap_str_const_t *hint,
1111 coap_session_t *c_session,
1112 void *arg
1113 ) {
1114 coap_dtls_cpsk_info_t *psk_info = (coap_dtls_cpsk_info_t *)arg;
1115 /* Remove (void) definition if variable is used */
1116 (void)c_session;
1117 coap_log(LOG_INFO, "Identity Hint '%.*s' provided\n", (int)hint->length, hint->s);
1119 /* Just use the defined information for now as passed in by arg */
1121 return psk_info;
1122 }
1123 static coap_dtls_cpsk_t dtls_psk;
1125 static char client_sni[256];
1126 static coap_session_t *
1128 setup_client_session_psk (const char *uri,
1129 struct in_addr ip_address,
1130 const uint8_t *identity,
1131 unsigned int identity_len,
1132 const uint8_t *key,
1133 unsigned int key_len
1134 ) {
1135 coap_session_t *session;
1136 coap_address_t server;
1137 /* See coap_context(3) */
1138 coap_context_t *context = coap_new_context(NULL);
1139 if (!context)
1141 return NULL;
1142 /* See coap_block(3) */
1143 coap_context_set_block_mode(context,
1144 COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);
1145 coap_address_init(&server);
1148 server.addr.sa.sa_family = AF_INET;
1149 server.addr.sin.sin_addr = ip_address;
1150 server.addr.sin.sin_port = htons (5684);
1151 /* See coap_encryption(3) */
1153 memset (&dtls_psk, 0, sizeof(dtls_psk));
1154 dtls_psk.version = COAP_DTLS_CPSK_SETUP_VERSION;
1155 dtls_psk.validate_ih_call_back = verify_ih_callback;
1156 dtls_psk.ih_call_back_arg = &dtls_psk.psk_info;
1157 if (uri)
1158 memcpy(client_sni, uri, min(strlen(uri), sizeof(client_sni)-1));
1159 else
1160 memcpy(client_sni, "localhost", 9);
1161 dtls_psk.client_sni = client_sni;
1162 dtls_psk.psk_info.identity.s = identity;
1163 dtls_psk.psk_info.identity.length = identity_len;
1164 dtls_psk.psk_info.key.s = key;
1165 dtls_psk.psk_info.key.length = key_len;
1166 session = coap_new_client_session_psk2(context, NULL, &server,
1167 COAP_PROTO_DTLS, &dtls_psk);
1168 if (!session) {
1169 coap_free_context(context);
1170 return NULL;
1171 }
1172 /* The context is in session->context */
1173 return session;
1174 }
1175
1177 coap_block(3), coap_context(3), coap_resource(3), coap_session(3) and
1178 coap_tls_library(3)
1179
1181 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
1182 information.
1183
1185 Please report bugs on the mailing list for libcoap:
1186 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
1187 https://github.com/obgm/libcoap/issues
1188
1190 The libcoap project <libcoap-developers@lists.sourceforge.net>
1191coap_encryption 4.3.1 11/24/2022 COAP_ENCRYPTION(3)