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 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           1 : 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           1 : 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           1 : 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           1 : 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_ */