mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
279 lines
8.6 KiB
C
279 lines
8.6 KiB
C
/*
|
|
* Copyright (C) 2019 HAW Hamburg
|
|
*
|
|
* This file is subject to the terms and conditions of the GNU Lesser
|
|
* General Public License v2.1. See the file LICENSE in the top level
|
|
* directory for more details.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup net_credman (D)TLS Credential Manager
|
|
* @ingroup net net_dtls
|
|
* @brief Credentials management module for (D)TLS
|
|
*
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief (D)TLS credentials management module definitions
|
|
*
|
|
* @note This module DOES NOT copy the credentials into the system. It
|
|
* just holds the pointers to the credentials given by the user.
|
|
* The user must make sure that these pointers are valid during the
|
|
* lifetime of the application.
|
|
*
|
|
* @author Aiman Ismail <muhammadaimanbin.ismail@haw-hamburg.de>
|
|
*/
|
|
|
|
#ifndef NET_CREDMAN_H
|
|
#define NET_CREDMAN_H
|
|
|
|
#include <unistd.h>
|
|
#include <stdint.h>
|
|
#include "modules.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup net_credman_conf (D)TLS Credential Manager compile configurations
|
|
* @ingroup config
|
|
* @{
|
|
*/
|
|
/**
|
|
* @brief Maximum number of credentials in credential pool
|
|
*/
|
|
#ifndef CONFIG_CREDMAN_MAX_CREDENTIALS
|
|
#define CONFIG_CREDMAN_MAX_CREDENTIALS (2)
|
|
#endif
|
|
|
|
/**
|
|
* @brief Maximum number of ASN.1 objects when decoding keys.
|
|
*/
|
|
#ifndef CONFIG_CREDMAN_MAX_ASN1_OBJ
|
|
#define CONFIG_CREDMAN_MAX_ASN1_OBJ (8)
|
|
#endif
|
|
/** @} */
|
|
|
|
/**
|
|
* @brief Buffer of the credential
|
|
*/
|
|
typedef struct {
|
|
const void *s; /**< Pointer to the buffer */
|
|
size_t len; /**< Length of credman_buffer_t::s */
|
|
} credman_buffer_t;
|
|
|
|
/**
|
|
* @brief PSK parameters
|
|
*/
|
|
typedef struct {
|
|
credman_buffer_t key; /**< Key buffer */
|
|
credman_buffer_t id; /**< ID buffer */
|
|
credman_buffer_t hint; /**< Hint buffer */
|
|
} psk_params_t;
|
|
|
|
/**
|
|
* @brief ECDSA public keys
|
|
*/
|
|
typedef struct {
|
|
const void *x; /**< X part of the public key */
|
|
const void *y; /**< Y part of the public key */
|
|
} ecdsa_public_key_t;
|
|
|
|
/**
|
|
* @brief ECDSA parameters
|
|
*/
|
|
typedef struct {
|
|
const void *private_key; /**< Pointer to the private key */
|
|
ecdsa_public_key_t public_key; /**< Public key */
|
|
ecdsa_public_key_t *client_keys; /**< Array of clients public keys */
|
|
size_t client_keys_size; /**< Size of ecdsa_params_t::clients_keys */
|
|
} ecdsa_params_t;
|
|
|
|
/**
|
|
* @brief Tag of the credential.
|
|
*/
|
|
typedef uint16_t credman_tag_t;
|
|
|
|
/**
|
|
* @brief Used to signal empty/no tag
|
|
*/
|
|
#define CREDMAN_TAG_EMPTY (0)
|
|
|
|
/**
|
|
* @brief Credential types
|
|
*/
|
|
typedef enum {
|
|
/**
|
|
* @brief Empty type
|
|
*
|
|
* Used to detect uninitialized @ref credman_credential_t internally.
|
|
*/
|
|
CREDMAN_TYPE_EMPTY = 0,
|
|
CREDMAN_TYPE_PSK = 1, /**< PSK credential type */
|
|
CREDMAN_TYPE_ECDSA = 2, /**< ECDSA credential type */
|
|
} credman_type_t;
|
|
|
|
/**
|
|
* @brief Credential information
|
|
*/
|
|
typedef struct {
|
|
credman_type_t type; /**< Type of the credential */
|
|
credman_tag_t tag; /**< Tag of the credential */
|
|
union {
|
|
psk_params_t psk; /**< PSK credential parameters */
|
|
ecdsa_params_t ecdsa; /**< ECDSA credential parameters */
|
|
} params; /**< Credential parameters */
|
|
} credman_credential_t;
|
|
|
|
/**
|
|
* @brief Return values
|
|
*/
|
|
enum {
|
|
CREDMAN_OK = 0, /**< No error */
|
|
CREDMAN_EXIST = -1, /**< Credential already exist in system pool */
|
|
CREDMAN_NO_SPACE = -2, /**< No space in system pool for new credential */
|
|
CREDMAN_NOT_FOUND = -3, /**< Credential not found in the system pool */
|
|
CREDMAN_INVALID = -4, /**< Invalid input parameter(s) */
|
|
CREDMAN_TYPE_UNKNOWN = -5, /**< Unknown credential type */
|
|
CREDMAN_ERROR = -6, /**< Other errors */
|
|
};
|
|
|
|
/**
|
|
* @brief Adds a credential to the credential pool
|
|
*
|
|
* @param[in] credential Credential to add.
|
|
*
|
|
* @return CREDMAN_OK on success
|
|
* @return CREDMAN_EXIST if credential of @p tag and @p type already exist
|
|
* @return CREDMAN_NO_SPACE if credential pool is full
|
|
* @return CREDMAN_TYPE_UNKNOWN if @p credential has unknown
|
|
* credman_credential_t::type
|
|
* @return CREDMAN_INVALID if @p credential has
|
|
* @return CREDMAN_INVALID credman_credential_t::tag with the value of
|
|
* CREDMAN_TAG_EMPTY
|
|
* @return CREDMAN_INVALID credman_credential_t::type with the value of
|
|
* CREDMAN_TYPE_EMPTY
|
|
* @return CREDMAN_INVALID credman_credential_t::params with invalid credential
|
|
* parameters i.e. the key points to NULL or has a length of 0
|
|
* @return CREDMAN_ERROR on other errors
|
|
*/
|
|
int credman_add(const credman_credential_t *credential);
|
|
|
|
/**
|
|
* @brief Gets a credential from credential pool
|
|
*
|
|
* @param[out] credential Found credential
|
|
* @param[in] tag Tag of credential to get
|
|
* @param[in] type Type of credential to get
|
|
*
|
|
* @return CREDMAN_OK on success
|
|
* @return CREDMAN_NOT_FOUND if no credential with @p tag and @p type found
|
|
* @return CREDMAN_ERROR on other errors
|
|
*/
|
|
int credman_get(credman_credential_t *credential, credman_tag_t tag,
|
|
credman_type_t type);
|
|
|
|
/**
|
|
* @brief Delete a credential from the credential pool. Does nothing if
|
|
* credential with credman_credential_t::tag @p tag and
|
|
* credman_credential_t::type @p type is not found.
|
|
*
|
|
* @param[in] tag Tag of the credential
|
|
* @param[in] type Type of the credential
|
|
*/
|
|
void credman_delete(credman_tag_t tag, credman_type_t type);
|
|
|
|
/**
|
|
* @brief Gets the number of credentials currently in the credential pool
|
|
*
|
|
* Maximum number of allowed credentials is defined by CONFIG_CREDMAN_MAX_CREDENTIALS
|
|
*
|
|
* @return number of credentials currently in the credential pool
|
|
*/
|
|
int credman_get_used_count(void);
|
|
|
|
#if IS_USED(MODULE_CREDMAN_LOAD) || DOXYGEN
|
|
/**
|
|
* @brief Load a public key from a buffer, as a `SubjectPublicKeyInfo` sequence, according to
|
|
* RFC5280. The key should be encoded in DER format.
|
|
*
|
|
* @pre `buf != NULL && out != NULL`.
|
|
*
|
|
* @note To use this functionality include the module `credman_load`. Credman only supports ECDSA
|
|
* for now, so [RFC5480](https://tools.ietf.org/html/rfc5480) applies.
|
|
*
|
|
* @experimental This API is considered experimental and will probably change without notice!
|
|
*
|
|
* @see https://tools.ietf.org/html/rfc5280#section-4.1
|
|
*
|
|
* @param[in] buf Buffer holding the encoded public key
|
|
* @param[in] buf_len Length of @p buf
|
|
* @param[out] out ECDSA public key to populate
|
|
*
|
|
* @retval CREDMAN_OK on success
|
|
* @retval CREDMAN_INVALID if the key is not valid
|
|
*/
|
|
int credman_load_public_key(const void *buf, size_t buf_len, ecdsa_public_key_t *out);
|
|
|
|
/**
|
|
* @brief Load a private key from a buffer, as a `OneAsymmetricKey` sequence, according to RFC5958.
|
|
* This is compatible with the previous version PKCS#8 (defined in RFC5208). If the optional
|
|
* respective public key is present, it will be loaded as well. The key should be encoded in
|
|
* DER format.
|
|
*
|
|
* @pre `buf != NULL && cred != NULL`
|
|
*
|
|
* @note To use this functionality include the module `credman_load`. Credman only supports ECDSA
|
|
* for now.
|
|
*
|
|
* @experimental This API is considered experimental and will probably change without notice!
|
|
*
|
|
* @see https://tools.ietf.org/html/rfc5958#section-2
|
|
*
|
|
* @param[in] buf Buffer holding the encoded private key
|
|
* @param[in] buf_len Length of @p buf
|
|
* @param[out] cred Credential to populate
|
|
*
|
|
* @retval CREDMAN_OK on success
|
|
* @retval CREDMAN_INVALID if the key is not valid
|
|
*/
|
|
int credman_load_private_key(const void *buf, size_t buf_len, credman_credential_t *cred);
|
|
|
|
/**
|
|
* @brief Load an ECC private key from a buffer, as an `ECPrivateKey` sequence, according to RFC5915.
|
|
* If the optional respective public key is present, it will be loaded as well. The key
|
|
* should be encoded in DER format.
|
|
*
|
|
* @pre `buf != NULL && cred != NULL`
|
|
*
|
|
* @note To use this functionality include the module `credman_load`.
|
|
*
|
|
* @experimental This API is considered experimental and will probably change without notice!
|
|
*
|
|
* @see https://tools.ietf.org/html/rfc5915#section-3
|
|
*
|
|
* @param[in] buf Buffer holding the encoded private key
|
|
* @param[in] buf_len Length of @p buf
|
|
* @param[out] cred Credential to populate
|
|
*
|
|
* @retval CREDMAN_OK on success
|
|
* @retval CREDMAN_INVALID if the key is not valid
|
|
*/
|
|
int credman_load_private_ecc_key(const void *buf, size_t buf_len, credman_credential_t *cred);
|
|
#endif /* MODULE_CREDMAN_LOAD || DOXYGEN */
|
|
|
|
#ifdef TEST_SUITES
|
|
/**
|
|
* @brief Empties the credential pool
|
|
*/
|
|
void credman_reset(void);
|
|
#endif /*TEST_SUITES */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* NET_CREDMAN_H */
|
|
/** @} */
|