From 5b340adfb8ce35e4dc2c9804beaafe21ce377a58 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Sun, 11 Feb 2018 19:32:15 +0000 Subject: [PATCH] coap_dtls.h: Add support for setting up PKI Define coap_dtls_pki_t coap_dtls_security_setup_t Functions coap_new_client_session_pki coap_dtls_context_set_psk coap_dtls_context_set_pki coap_dtls_context_check_keys_enabled --- include/coap/coap_dtls.h | 103 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/include/coap/coap_dtls.h b/include/coap/coap_dtls.h index 3e640eff..8a745de3 100644 --- a/include/coap/coap_dtls.h +++ b/include/coap/coap_dtls.h @@ -33,6 +33,63 @@ void coap_dtls_set_log_level(int level); /** Returns the current log level. */ int coap_dtls_get_log_level(void); +/** The structure used for defining the PKI setup data to be used */ +typedef struct coap_dtls_pki_t { + /* Alternative 1: Name of file on disk */ + const char *ca_file; + const char *public_cert; + const char *private_key; + /* Alternative 2: ASN1 version */ + const uint8_t *asn1_ca_file; + const uint8_t *asn1_public_cert; + const uint8_t *asn1_private_key; + int asn1_ca_file_len; + int asn1_public_cert_len; + int asn1_private_key_len; + int asn1_private_key_type; /* E.G. EVP_PKEY_RSA */ +} coap_dtls_pki_t; + +/** + * Security setup handler that is used as call-back in coap_context_set_pki() + * Typically, this will be calling additonal functions like + * SSL_CTX_set_tlsext_servername_callback() etc. + * + * @param context The security context definition - e.g. SSL_CTX * for OpenSSL. + * This will be dependent on the underlying TLS library + * - see coap_get_tls_library_version() + * @param setup_data A structure containing setup data passed into + * coap_context_set_pki() or coap_new_client_session_pki(). + * @return 1 if successful, else 0 + */ +typedef int (*coap_dtls_security_setup_t)(void *context, + coap_dtls_pki_t *setup_data); + +/** +* Creates a new client session to the designated server with PKI credentials +* @param ctx The CoAP context. +* @param local_if Address of local interface. It is recommended to use NULL to +* let the operating system choose a suitable local interface. +* If an address is specified, the port number should be zero, +* which means that a free port is automatically selected. +* @param server The server's address. If the port number is zero, the default +* port for the protocol will be used. +* @param proto CoAP Protocol. +* @param setup_callback The callback which is SSL support dependent. Can be +* NULL. +* @param setup_data PKI parameters. +* +* @return A new CoAP session or NULL if failed. Call coap_session_release() +* to free. +*/ +coap_session_t *coap_new_client_session_pki( + struct coap_context_t *ctx, + const coap_address_t *local_if, + const coap_address_t *server, + coap_proto_t proto, + coap_dtls_security_setup_t setup_callback, + coap_dtls_pki_t* setup_data +); + /** * Creates a new DTLS context for the given @p coap_context. This function * returns a pointer to a new DTLS context object or NULL on error. @@ -43,6 +100,49 @@ int coap_dtls_get_log_level(void); void * coap_dtls_new_context(struct coap_context_t *coap_context); +/** + * Set the dtls context's default server PSK hint and/or key. + * This does the PSK specifics for coap_dtls_new_context() + * + * @param ctx The CoAP context. + * @param hint The default PSK server hint sent to a client. If NULL, PSK + * authentication is disabled. Empty string is a valid hint. + * @param key The default PSK key. If NULL, PSK authentication will fail. + * @param key_len The default PSK key's lenght. If 0, PSK authentication will + * fail. + * + * @return 1 if successful, else 0 + */ + +int coap_dtls_context_set_psk(struct coap_context_t *ctx, const char *hint, + const uint8_t *key, size_t key_len ); + +/** + * Set the dtls context's default server PKI information. + * This does the PKI specifics for coap_dtls_new_context() + * The Callback is called to set up the appropriate information. + * + * @param ctx The CoAP context. + * @param setup_callback The callback which is TLS library support dependent + * @param setup_data If NULL, PKI authentication will fail. Certificate + * information required. + * + * @return 1 if successful, else 0 + */ + +int coap_dtls_context_set_pki(struct coap_context_t *ctx, + coap_dtls_security_setup_t setup_callback, + coap_dtls_pki_t* setup_data); + +/** + * Check whether one of the coap_dtls_context_set_*() functions have been + * called. + * + * @return 1 if coap_dtls_context_set_*() called, else 0 + */ + +int coap_dtls_context_check_keys_enabled(struct coap_context_t *ctx); + /** Releases the storage allocated for @p dtls_context. */ void coap_dtls_free_context(void *dtls_context); @@ -50,7 +150,8 @@ void coap_dtls_free_context(void *dtls_context); * Create a new client-side session. This should send a HELLO to the server. * * @param session The CoAP session - * @return Opaque handle to underlying TLS library object containing security parameters for the session. + * @return Opaque handle to underlying TLS library object containing security + * parameters for the session. */ void *coap_dtls_new_client_session(coap_session_t *session);