1 /* 2 * Copyright (c) 2018 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** @file 8 * @brief TLS credentials management 9 * 10 * An API for applications to configure TLS credentials. 11 */ 12 13 #ifndef ZEPHYR_INCLUDE_NET_TLS_CREDENTIALS_H_ 14 #define ZEPHYR_INCLUDE_NET_TLS_CREDENTIALS_H_ 15 16 /** 17 * @brief TLS credentials management 18 * @defgroup tls_credentials TLS credentials management 19 * @ingroup networking 20 * @{ 21 */ 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** TLS credential types */ 28 enum tls_credential_type { 29 /** Unspecified credential. */ 30 TLS_CREDENTIAL_NONE, 31 32 /** A trusted CA certificate. Use this to authenticate remote servers. 33 * Used with certificate-based ciphersuites. 34 */ 35 TLS_CREDENTIAL_CA_CERTIFICATE, 36 37 /** A public server certificate. Use this to register your own server 38 * certificate. Should be registered together with a corresponding 39 * private key. Used with certificate-based ciphersuites. 40 */ 41 TLS_CREDENTIAL_SERVER_CERTIFICATE, 42 43 /** Private key. Should be registered together with a corresponding 44 * public certificate. Used with certificate-based ciphersuites. 45 */ 46 TLS_CREDENTIAL_PRIVATE_KEY, 47 48 /** Pre-shared key. Should be registered together with a corresponding 49 * PSK identity. Used with PSK-based ciphersuites. 50 */ 51 TLS_CREDENTIAL_PSK, 52 53 /** Pre-shared key identity. Should be registered together with a 54 * corresponding PSK. Used with PSK-based ciphersuites. 55 */ 56 TLS_CREDENTIAL_PSK_ID 57 }; 58 59 /** Secure tag, a reference to TLS credential 60 * 61 * Secure tag can be used to reference credential after it was registered 62 * in the system. 63 * 64 * @note Some TLS credentials come in pairs: 65 * - TLS_CREDENTIAL_SERVER_CERTIFICATE with TLS_CREDENTIAL_PRIVATE_KEY, 66 * - TLS_CREDENTIAL_PSK with TLS_CREDENTIAL_PSK_ID. 67 * Such pairs of credentials must be assigned the same secure tag to be 68 * correctly handled in the system. 69 */ 70 typedef int sec_tag_t; 71 72 /** 73 * @brief Add a TLS credential. 74 * 75 * @details This function adds a TLS credential, that can be used 76 * by TLS/DTLS for authentication. 77 * 78 * @param tag A security tag that credential will be referenced with. 79 * @param type A TLS/DTLS credential type. 80 * @param cred A TLS/DTLS credential. 81 * @param credlen A TLS/DTLS credential length. 82 * 83 * @retval 0 TLS credential successfully added. 84 * @retval -EACCES Access to the TLS credential subsystem was denied. 85 * @retval -ENOMEM Not enough memory to add new TLS credential. 86 * @retval -EEXIST TLS credential of specific tag and type already exists. 87 */ 88 int tls_credential_add(sec_tag_t tag, enum tls_credential_type type, 89 const void *cred, size_t credlen); 90 91 /** 92 * @brief Get a TLS credential. 93 * 94 * @details This function gets an already registered TLS credential, 95 * referenced by @p tag secure tag of @p type. 96 * 97 * @param tag A security tag of requested credential. 98 * @param type A TLS/DTLS credential type of requested credential. 99 * @param cred A buffer for TLS/DTLS credential. 100 * @param credlen A buffer size on input. TLS/DTLS credential length on output. 101 * 102 * @retval 0 TLS credential successfully obtained. 103 * @retval -EACCES Access to the TLS credential subsystem was denied. 104 * @retval -ENOENT Requested TLS credential was not found. 105 * @retval -EFBIG Requested TLS credential does not fit in the buffer provided. 106 */ 107 int tls_credential_get(sec_tag_t tag, enum tls_credential_type type, 108 void *cred, size_t *credlen); 109 110 /** 111 * @brief Delete a TLS credential. 112 * 113 * @details This function removes a TLS credential, referenced by @p tag 114 * secure tag of @p type. 115 * 116 * @param tag A security tag corresponding to removed credential. 117 * @param type A TLS/DTLS credential type of removed credential. 118 * 119 * @retval 0 TLS credential successfully deleted. 120 * @retval -EACCES Access to the TLS credential subsystem was denied. 121 * @retval -ENOENT Requested TLS credential was not found. 122 */ 123 int tls_credential_delete(sec_tag_t tag, enum tls_credential_type type); 124 125 #ifdef __cplusplus 126 } 127 #endif 128 129 /** 130 * @} 131 */ 132 133 #endif /* ZEPHYR_INCLUDE_NET_TLS_CREDENTIALS_H_ */ 134
