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