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             :  * @ingroup networking
      20             :  * @{
      21             :  */
      22             : 
      23             : #ifdef __cplusplus
      24             : extern "C" {
      25             : #endif
      26             : 
      27             : /** TLS credential types */
      28           1 : 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             :  * @note Negative values are reserved for internal use.
      71             :  */
      72           1 : typedef int sec_tag_t;
      73             : 
      74             : /**
      75             :  * @brief Add a TLS credential.
      76             :  *
      77             :  * @details This function adds a TLS credential, that can be used
      78             :  *          by TLS/DTLS for authentication.
      79             :  *
      80             :  * @param tag     A security tag that credential will be referenced with.
      81             :  * @param type    A TLS/DTLS credential type.
      82             :  * @param cred    A TLS/DTLS credential.
      83             :  * @param credlen A TLS/DTLS credential length.
      84             :  *
      85             :  * @retval 0 TLS credential successfully added.
      86             :  * @retval -EACCES Access to the TLS credential subsystem was denied.
      87             :  * @retval -ENOMEM Not enough memory to add new TLS credential.
      88             :  * @retval -EEXIST TLS credential of specific tag and type already exists.
      89             :  */
      90           1 : int tls_credential_add(sec_tag_t tag, enum tls_credential_type type,
      91             :                        const void *cred, size_t credlen);
      92             : 
      93             : /**
      94             :  * @brief Get a TLS credential.
      95             :  *
      96             :  * @details This function gets an already registered TLS credential,
      97             :  *          referenced by @p tag secure tag of @p type.
      98             :  *
      99             :  * @param tag     A security tag of requested credential.
     100             :  * @param type    A TLS/DTLS credential type of requested credential.
     101             :  * @param cred    A buffer for TLS/DTLS credential.
     102             :  * @param credlen A buffer size on input. TLS/DTLS credential length on output.
     103             :  *
     104             :  * @retval 0 TLS credential successfully obtained.
     105             :  * @retval -EACCES Access to the TLS credential subsystem was denied.
     106             :  * @retval -ENOENT Requested TLS credential was not found.
     107             :  * @retval -EFBIG Requested TLS credential does not fit in the buffer provided.
     108             :  */
     109           1 : int tls_credential_get(sec_tag_t tag, enum tls_credential_type type,
     110             :                        void *cred, size_t *credlen);
     111             : 
     112             : /**
     113             :  * @brief Delete a TLS credential.
     114             :  *
     115             :  * @details This function removes a TLS credential, referenced by @p tag
     116             :  *          secure tag of @p type.
     117             :  *
     118             :  * @param tag  A security tag corresponding to removed credential.
     119             :  * @param type A TLS/DTLS credential type of removed credential.
     120             :  *
     121             :  * @retval 0 TLS credential successfully deleted.
     122             :  * @retval -EACCES Access to the TLS credential subsystem was denied.
     123             :  * @retval -ENOENT Requested TLS credential was not found.
     124             :  */
     125           1 : int tls_credential_delete(sec_tag_t tag, enum tls_credential_type type);
     126             : 
     127             : #ifdef __cplusplus
     128             : }
     129             : #endif
     130             : 
     131             : /**
     132             :  * @}
     133             :  */
     134             : 
     135             : #endif /* ZEPHYR_INCLUDE_NET_TLS_CREDENTIALS_H_ */