astarte_credentials.h File Reference

Astarte credentials functions. More...

#include "astarte.h"
#include <stdbool.h>
#include <string.h>

Include dependency graph for astarte_credentials.h:

Go to the source code of this file.

Data Structures
struct	astarte_credentials_storage_functions_t
struct	astarte_credentials_context_t

Macros
#define	CERT_LENGTH   4096
#define	CN_LENGTH   512
#define	ASTARTE_CREDENTIALS_DEFAULT_NVS_PARTITION   NULL

Typedefs
typedef enum credential_type_t	credential_type_t
typedef astarte_err_t(*	astarte_credentials_store_t) (void *opaque, credential_type_t cred_type, const void *credential, size_t length)
typedef astarte_err_t(*	astarte_credentials_fetch_t) (void *opaque, credential_type_t cred_type, char *out, size_t length)
typedef bool(*	astarte_credentials_exists_t) (void *opaque, credential_type_t cred_type)
typedef astarte_err_t(*	astarte_credentials_remove_t) (void *opaque, credential_type_t cred_type)

Enumerations
enum	credential_type_t

Functions
enum credential_type_t	__attribute__ ((deprecated("Please use the typedef credential_type_t")))
astarte_err_t	astarte_credentials_set_storage_context (astarte_credentials_context_t *creds_context)
	replace credentials context. More...
astarte_err_t	astarte_credentials_use_nvs_storage (const char *partition_label)
	use a NVS partition as credentials context. More...
astarte_err_t	astarte_credentials_init ()
	initialize Astarte credentials. More...
bool	astarte_credentials_is_initialized ()
	check if Astarte credentials are initialized. More...
astarte_err_t	astarte_credentials_create_key ()
	create Astarte private key. More...
astarte_err_t	astarte_credentials_create_csr ()
	create Astarte CSR to be sent to Pairing API. More...
astarte_err_t	astarte_credentials_save_certificate (const char *cert_pem)
	save the certificate to connect with the Astarte MQTT v1 protocol More...
astarte_err_t	astarte_credentials_delete_certificate ()
	delets the saved certificate used to connect with the Astarte MQTT v1 protocol More...
astarte_err_t	astarte_credentials_get_csr (char *out, size_t length)
	get the saved CSR More...
astarte_err_t	astarte_credentials_get_certificate (char *out, size_t length)
	get the certificate to connect with the Astarte MQTT v1 protocol More...
astarte_err_t	astarte_credentials_get_certificate_common_name (const char *cert_pem, char *out, size_t length)
	get the certificate Common Name More...
astarte_err_t	astarte_credentials_get_key (char *out, size_t length)
	get the private key to connect with the Astarte MQTT v1 protocol More...
astarte_err_t	astarte_credentials_get_stored_credentials_secret (char *out, size_t length)
	get the stored credentials_secret More...
astarte_err_t	astarte_credentials_set_stored_credentials_secret (const char *credentials_secret)
	save the credentials_secret in the NVS More...
astarte_err_t	astarte_credentials_erase_stored_credentials_secret ()
	delete the credentials_secret from the NVS More...
bool	astarte_credentials_has_certificate ()
	check if the certificate exists More...
bool	astarte_credentials_has_csr ()
	check if the CSR exists More...
bool	astarte_credentials_has_key ()
	check if the private key exists More...
astarte_err_t	astarte_credentials_store (void *opaque, credential_type_t cred_type, const void *credential, size_t length)
astarte_err_t	astarte_credentials_fetch (void *opaque, credential_type_t cred_type, char *out, size_t length)
bool	astarte_credentials_exists (void *opaque, credential_type_t cred_type)
astarte_err_t	astarte_credentials_remove (void *opaque, credential_type_t cred_type)
astarte_err_t	astarte_credentials_nvs_store (void *opaque, credential_type_t cred_type, const void *credential, size_t length)
astarte_err_t	astarte_credentials_nvs_fetch (void *opaque, credential_type_t cred_type, char *out, size_t length)
bool	astarte_credentials_nvs_exists (void *opaque, credential_type_t cred_type)
astarte_err_t	astarte_credentials_nvs_remove (void *opaque, credential_type_t cred_type)

Variables
typedef	__attribute__
	ASTARTE_CREDENTIALS_CSR = 1
	ASTARTE_CREDENTIALS_KEY
	ASTARTE_CREDENTIALS_CERTIFICATE

Detailed Description

Astarte credentials functions.

Function Documentation

astarte_credentials_create_csr()

astarte_err_t astarte_credentials_create_csr

(

)

create Astarte CSR to be sent to Pairing API.

This function creates the CSR to be signed by Pairing API and saves it on the FAT filesystem on the SPI flash. It requires a mounted FAT on the /spiflash mountpoint. This function is called from astarte_credentials_init() if the CSR doesn't exist, but can also be called manually to generate a new CSR.

Returns

The status code, ASTARTE_OK if successful, otherwise an error code is returned.

astarte_credentials_create_key()

astarte_err_t astarte_credentials_create_key

(

)

create Astarte private key.

This function creates the private key and saves it on the FAT filesystem on the SPI flash. It requires a mounted FAT on the /spiflash mountpoint. This function is called from astarte_credentials_init() if the key doesn't exist, but can also be called manually to generate a new key.

Returns

The status code, ASTARTE_OK if successful, otherwise an error code is returned.

astarte_credentials_delete_certificate()

astarte_err_t astarte_credentials_delete_certificate

(

)

delets the saved certificate used to connect with the Astarte MQTT v1 protocol

Delete the certificate from the credentials folder. This requires a mounted FAT on the /spiflash mountpoint

Returns

The status code, ASTARTE_OK if the certificate was correctly deleted, otherwise an error code is returned.

astarte_credentials_erase_stored_credentials_secret()

astarte_err_t astarte_credentials_erase_stored_credentials_secret

(

)

delete the credentials_secret from the NVS

Delete the credentials_secret from the NVS. Keep in mind that if you lose access to the credentials_secret of a device, you have to unregister it from Astarte before being able to make it register again.

Returns

The status code, ASTARTE_OK if the credentials_secret was found, ASTARTE_ERR_NOT_FOUND if the credentials secret is not present in the NVS, another astarte_err_t if an error occurs.

astarte_credentials_get_certificate()

astarte_err_t astarte_credentials_get_certificate	(	char *	out,
		size_t	length
	)

get the certificate to connect with the Astarte MQTT v1 protocol

Get the certificate, writing it to the out buffer, if it is present.

Parameters

out	A pointer to an allocated buffer where the certificate will be written.
length	The length of the out buffer.

Returns

The status code, ASTARTE_OK if the certificate was correctly written, otherwise an error code is returned.

astarte_credentials_get_certificate_common_name()

astarte_err_t astarte_credentials_get_certificate_common_name	(	const char *	cert_pem,
		char *	out,
		size_t	length
	)

get the certificate Common Name

Get the certificate Common Name, writing it to the out buffer.

Parameters

cert_pem	A pointer to buffer containing the PEM encoded certificate.
out	A pointer to an allocated buffer where the CN will be written.
length	The length of the out buffer.

Returns

The status code, ASTARTE_OK if the certificate was correctly written, otherwise an error code is returned.

astarte_credentials_get_csr()

astarte_err_t astarte_credentials_get_csr	(	char *	out,
		size_t	length
	)

get the saved CSR

Get the CSR, writing it to the out buffer, if it is present.

Parameters

out	A pointer to an allocated buffer where the CSR will be written.
length	The length of the out buffer.

Returns

The status code, ASTARTE_OK if the certificate was correctly written, otherwise an error code is returned.

astarte_credentials_get_key()

astarte_err_t astarte_credentials_get_key	(	char *	out,
		size_t	length
	)

get the private key to connect with the Astarte MQTT v1 protocol

Get the private key, writing it to the out buffer, if it is present.

Parameters

out	A pointer to an allocated buffer where the key will be written.
length	The length of the out buffer.

Returns

The status code, ASTARTE_OK if the certificate was correctly written, otherwise an error code is returned.

astarte_credentials_get_stored_credentials_secret()

astarte_err_t astarte_credentials_get_stored_credentials_secret	(	char *	out,
		size_t	length
	)

get the stored credentials_secret

Get the credentials_secret stored in the NVS, writing it to the out buffer, if it is present.

Parameters

out	A pointer to an allocated buffer where the credentials_secret will be written.
length	The length of the out buffer.

Returns

The status code, ASTARTE_OK if the credentials_secret was found, ASTARTE_ERR_NOT_FOUND if the credentials secret is not present in the NVS, another astarte_err_t if an error occurs.

astarte_credentials_has_certificate()

bool astarte_credentials_has_certificate

(

)

check if the certificate exists

Check if the file containing the certificate exists and is readable.

Returns

true if the file exists and is readable, false otherwise.

astarte_credentials_has_csr()

bool astarte_credentials_has_csr

(

)

check if the CSR exists

Check if the file containing the CSR exists and is readable.

Returns

true if the file exists and is readable, false otherwise.

astarte_credentials_has_key()

bool astarte_credentials_has_key

(

)

check if the private key exists

Check if the file containing the private key exists and is readable.

Returns

true if the file exists and is readable, false otherwise.

astarte_credentials_init()

astarte_err_t astarte_credentials_init

(

)

initialize Astarte credentials.

This function has to be called to initialize the private key and CSR needed for the MQTT transport.

Returns

The status code, ASTARTE_OK if successful, otherwise an error code is returned.

astarte_credentials_is_initialized()

bool astarte_credentials_is_initialized

(

)

check if Astarte credentials are initialized.

Returns

true if the private key and CSR exist, false otherwise.

astarte_credentials_save_certificate()

astarte_err_t astarte_credentials_save_certificate

(

const char *

cert_pem

)

save the certificate to connect with the Astarte MQTT v1 protocol

Save the certificate in the credentials folder. This requires a mounted FAT on the /spiflash mountpoint

Parameters

cert_pem

The buffer containing a NULL-terminated certificate in PEM form.

Returns

The status code, ASTARTE_OK if the certificate was correctly saved, otherwise an error code is returned.

astarte_credentials_set_storage_context()

astarte_err_t astarte_credentials_set_storage_context

(

astarte_credentials_context_t *

creds_context

)

replace credentials context.

This function has to be called before initialize when a storage different than internal flash has to be used.

Returns

The status code, ASTARTE_OK if successful, otherwise an error code is returned.

astarte_credentials_set_stored_credentials_secret()

astarte_err_t astarte_credentials_set_stored_credentials_secret

(

const char *

credentials_secret

)

save the credentials_secret in the NVS

Save the credentials_secret in the NVS, where it can be used internally by Astarte Pairing to obtain Astarte MQTT v1 credentials.

Parameters

credentials_secret

A pointer to the buffer that contains the credentials_secret.

Returns

The status code, ASTARTE_OK if the credentials_secret was correctly written, otherwise an error code is returned.

astarte_credentials_use_nvs_storage()

astarte_err_t astarte_credentials_use_nvs_storage

(

const char *

partition_label

)

use a NVS partition as credentials context.

This function has to be called before any other astarte_credentials function when NVS storage is required as credentials storage. This function will also change the partition used for storing credential secret.

Parameters

partition_label

the NVS partion label. Use ASTARTE_CREDENTIALS_DEFAULT_NVS_PARTITION when default must be used.

Returns

The status code, ASTARTE_OK if successful, otherwise an error code is returned.