Line data Source code
1 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 1 : 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 client or server certificate. Use this to register your own
40 : * certificate. Should be registered together with a corresponding
41 : * private key. Used with certificate-based ciphersuites.
42 : */
43 : TLS_CREDENTIAL_PUBLIC_CERTIFICATE,
44 :
45 : /** @deprecated Use TLS_CREDENTIAL_PUBLIC_CERTIFICATE instead.
46 : */
47 : TLS_CREDENTIAL_SERVER_CERTIFICATE = TLS_CREDENTIAL_PUBLIC_CERTIFICATE,
48 :
49 : /** Private key. Should be registered together with a corresponding
50 : * public certificate. Used with certificate-based ciphersuites.
51 : */
52 : TLS_CREDENTIAL_PRIVATE_KEY,
53 :
54 : /** Pre-shared key. Should be registered together with a corresponding
55 : * PSK identity. Used with PSK-based ciphersuites.
56 : */
57 : TLS_CREDENTIAL_PSK,
58 :
59 : /** Pre-shared key identity. Should be registered together with a
60 : * corresponding PSK. Used with PSK-based ciphersuites.
61 : */
62 : TLS_CREDENTIAL_PSK_ID
63 : };
64 :
65 : /** Secure tag, a reference to TLS credential
66 : *
67 : * Secure tag can be used to reference credential after it was registered
68 : * in the system.
69 : *
70 : * @note Some TLS credentials come in pairs:
71 : * - TLS_CREDENTIAL_PUBLIC_CERTIFICATE with TLS_CREDENTIAL_PRIVATE_KEY,
72 : * - TLS_CREDENTIAL_PSK with TLS_CREDENTIAL_PSK_ID.
73 : * Such pairs of credentials should generally be assigned the same secure tag
74 : * when used with subsystems that support fetching multiple credentials per tag,
75 : * such as TLS sockets. However, note that certain subsystems or implementations
76 : * may expect only one credential per secure tag.
77 : *
78 : * @note Negative values are reserved for internal use.
79 : */
80 1 : typedef int sec_tag_t;
81 :
82 1 : #define SEC_TAG_TLS_INVALID (-1) /**< Invalid secure tag value. */
83 :
84 : /**
85 : * @brief Add a TLS credential.
86 : *
87 : * @details This function adds a TLS credential, that can be used
88 : * by TLS/DTLS for authentication.
89 : *
90 : * @param tag A security tag that credential will be referenced with.
91 : * @param type A TLS/DTLS credential type.
92 : * @param cred A TLS/DTLS credential.
93 : * @param credlen A TLS/DTLS credential length.
94 : *
95 : * @retval 0 TLS credential successfully added.
96 : * @retval -EACCES Access to the TLS credential subsystem was denied.
97 : * @retval -ENOMEM Not enough memory to add new TLS credential.
98 : * @retval -EEXIST TLS credential of specific tag and type already exists.
99 : */
100 1 : int tls_credential_add(sec_tag_t tag, enum tls_credential_type type,
101 : const void *cred, size_t credlen);
102 :
103 : /**
104 : * @brief Get a TLS credential.
105 : *
106 : * @details This function gets an already registered TLS credential,
107 : * referenced by @p tag secure tag of @p type.
108 : *
109 : * @param tag A security tag of requested credential.
110 : * @param type A TLS/DTLS credential type of requested credential.
111 : * @param cred A buffer for TLS/DTLS credential.
112 : * @param credlen A buffer size on input. TLS/DTLS credential length on output.
113 : *
114 : * @retval 0 TLS credential successfully obtained.
115 : * @retval -EACCES Access to the TLS credential subsystem was denied.
116 : * @retval -ENOENT Requested TLS credential was not found.
117 : * @retval -EFBIG Requested TLS credential does not fit in the buffer provided.
118 : * Check *credlen for size required.
119 : */
120 1 : int tls_credential_get(sec_tag_t tag, enum tls_credential_type type,
121 : void *cred, size_t *credlen);
122 :
123 : /**
124 : * @brief Delete a TLS credential.
125 : *
126 : * @details This function removes a TLS credential, referenced by @p tag
127 : * secure tag of @p type.
128 : *
129 : * @param tag A security tag corresponding to removed credential.
130 : * @param type A TLS/DTLS credential type of removed credential.
131 : *
132 : * @retval 0 TLS credential successfully deleted.
133 : * @retval -EACCES Access to the TLS credential subsystem was denied.
134 : * @retval -ENOENT Requested TLS credential was not found.
135 : */
136 1 : int tls_credential_delete(sec_tag_t tag, enum tls_credential_type type);
137 :
138 : #ifdef __cplusplus
139 : }
140 : #endif
141 :
142 : /**
143 : * @}
144 : */
145 :
146 : #endif /* ZEPHYR_INCLUDE_NET_TLS_CREDENTIALS_H_ */
|
