Onboard Self-Signed Certificate Generation

See On-board Cert Generation - Simple and other examples in the examples/SSL folder. More...

Classes
struct	CertGenData
	Used to store the information that is passed in when enabling onboard generated certificates, as well as the information needed to determine when they need to be regenerated. More...
class	CertData

Enumerations
enum	SslKeyType_t {   SSL_KEY_NONE = 0 , SSL_KEY_RSA_1024 = 1 , SSL_KEY_RSA_2048 , SSL_KEY_RSA_4096 ,   SSL_KEY_ECC_SECP192R1 = ECC_SECP192R1 , SSL_KEY_ECC_SECP224R1 = ECC_SECP224R1 , SSL_KEY_ECC_SECP256R1 = ECC_SECP256R1 , SSL_KEY_ECC_SECP384R1 = ECC_SECP384R1 ,   SSL_KEY_ECC_SECP521R1 = ECC_SECP521R1 }
	Certificate Generation Key Types. More...
enum	AltNameType_t : char { ALT_NAME_TYPE_NONE = 0 , ALT_NAME_TYPE_DNS = (char)0x82 , ALT_NAME_TYPE_IP = (char)0x87 }
	Certificate Generation Alternate Name Types. More...
enum	CertGenReturnCode : int {   CERT_GEN_RETURN_SUCCESS = 1 , CERT_GEN_RETURN_NOT_REQUIRED = 2 , CERT_GEN_RETURN_INVALID_RANDOM = -1 , CERT_GEN_RETURN_MALLOC_ERROR = -2 ,   CERT_GEN_RETURN_ECC_INIT_ERROR = -3 , CERT_GEN_RETURN_ECC_CREATE_ERROR = -4 , CERT_GEN_RETURN_RSA_INIT_ERROR = -5 , CERT_GEN_RETURN_RSA_CREATE_ERROR = -6 ,   CERT_GEN_RETURN_CERT_INIT_ERROR = -7 , CERT_GEN_RETURN_CERT_CREATE_ERROR = -8 , CERT_GEN_RETURN_CERT_SIGNING_ERROR = -9 , CERT_GEN_RETURN_CERT_SAVING_ERROR = -10 ,   CERT_GEN_RETURN_KEY_CONVERT_ERROR = -11 , CERT_GEN_RETURN_KEY_SAVING_ERROR = -12 , CERT_GEN_RETURN_SET_ISSUER_ERROR = -13 }
	Certificate Generation Function Return Codes. More...

Functions
CertGenReturnCode	SSL_CreateNewSelfSignedCert (CertGenData &pGenData)
	Generates a new self-signed certificate that will be stored on the device.
void	EnableOnboardCertificateCreation (CertGenReturnCode(*createCertFunc)(CertGenData &cGenData)=SSL_CreateNewSelfSignedCert)
	Enables the ability for the module to automatically generate self-signed certificates for use in SSL/TLS connections when acting as the server.
void	FillInAltNamesASN1 (Cert &TheCert, NBString &altNameString)
	Helper function used to build ASN1 representation of alt names.
CertGenReturnCode	CheckAndCreateHalCertAndKey ()
	Check for a valid SSL certificate and generate one if not found.
CertGenData *	GetDataForCertGen ()
	A function to be overridden to pass certificate details to the certificate generator.

Detailed Description

See On-board Cert Generation - Simple and other examples in the examples/SSL folder.

Enumeration Type Documentation

AltNameType_t

enum AltNameType_t : char

#include <certgen.h>

Certificate Generation Alternate Name Types.

Enumerator
ALT_NAME_TYPE_NONE	None.
ALT_NAME_TYPE_DNS	DNS Name.
ALT_NAME_TYPE_IP	IP Address.

CertGenReturnCode

enum CertGenReturnCode : int

#include <certgen.h>

Certificate Generation Function Return Codes.

Enumerator
CERT_GEN_RETURN_SUCCESS	Returned when the certificate was successfully generated.
CERT_GEN_RETURN_NOT_REQUIRED	Returned when the a new certificate was not required to be generated.
CERT_GEN_RETURN_INVALID_RANDOM	Returned when the device was unable to generate a valid random number.
CERT_GEN_RETURN_MALLOC_ERROR	Returned when the device is unable to malloc enough space to generate the certificate.
CERT_GEN_RETURN_ECC_INIT_ERROR	Returned when the device was unable to initialize the required ECC object.
CERT_GEN_RETURN_ECC_CREATE_ERROR	Returned when the device was unable to create the ECC key.
CERT_GEN_RETURN_RSA_INIT_ERROR	Returned when the device was unable to initialize the required RSA object.
CERT_GEN_RETURN_RSA_CREATE_ERROR	Returned when the device was unable to create the RSA key.
CERT_GEN_RETURN_CERT_INIT_ERROR	Returned when the device was unable to initialize the required certificate object.
CERT_GEN_RETURN_CERT_CREATE_ERROR	Returned when the device was unable to create the certificate.
CERT_GEN_RETURN_CERT_SIGNING_ERROR	Returned when the device was unable to sign the created certificate.
CERT_GEN_RETURN_CERT_SAVING_ERROR	Returned when the device was unable to properly save the certificate.
CERT_GEN_RETURN_KEY_CONVERT_ERROR	Returned when the device was unable to convert the certificate from PEM to DER format.
CERT_GEN_RETURN_KEY_SAVING_ERROR	Returned when the device was unable to save the key.
CERT_GEN_RETURN_SET_ISSUER_ERROR	Returned when the device was unable to set the issuer if a CA was used.

SslKeyType_t

enum SslKeyType_t

#include <certgen.h>

Certificate Generation Key Types.

Enumerator
SSL_KEY_NONE	None.
SSL_KEY_RSA_1024	RSA 1024.
SSL_KEY_RSA_2048	RSA 2048.
SSL_KEY_RSA_4096	RSA 4096.
SSL_KEY_ECC_SECP192R1	Defined in wolfssl/wolfcrypt/ecc.h.
SSL_KEY_ECC_SECP224R1	Defined in wolfssl/wolfcrypt/ecc.h.
SSL_KEY_ECC_SECP256R1	Defined in wolfssl/wolfcrypt/ecc.h.
SSL_KEY_ECC_SECP384R1	Defined in wolfssl/wolfcrypt/ecc.h.
SSL_KEY_ECC_SECP521R1	Defined in wolfssl/wolfcrypt/ecc.h.

Function Documentation

EnableOnboardCertificateCreation()

void EnableOnboardCertificateCreation

(

CertGenReturnCode(*)(CertGenData &cGenData)

createCertFunc = SSL_CreateNewSelfSignedCert

)

#include <certgen.h>

Enables the ability for the module to automatically generate self-signed certificates for use in SSL/TLS connections when acting as the server.

If a certificate is manually loaded on the module prior to the SSL server being intialized, that certificate will be use and nothing will be generated. If a certificate had been previously generated and a new certificate is manually loaded on the device, the newly loaded certificate will be used in place of the automatically generated one, though the automatically generated one will still be availabe on the module.

Parameters

createCertFunc

Optional parameter to specify a custom create certificate function.

FillInAltNamesASN1()

void FillInAltNamesASN1	(	Cert &	TheCert,
		NBString &	altNameString )

#include <certgen.h>

Helper function used to build ASN1 representation of alt names.

Parameters

TheCert	The WolfSSL Cert structure to put the altnames in/onto.
altNameString	a NBAString holding the comman seperated list of alt names. A single string, with possibly multiple altnames separated by a comma. You can either incude a tag telling the system what kind of AltName it is... So say you wanted : IP:192.168.1.36 and DNS:demo.netburner.com The following strings would both work: "IP:192.168.1.36,DNS:demo.netburner.com" "192.168.1.36,demo.netburner.com"

or dual interface IP's...

"192.168.1.36,10.1.1.35"

or both V4 and V6.... "IP:fe80::203:f4ff:fe0a:447f,192.168.1.36"

GetDataForCertGen()

CertGenData * GetDataForCertGen ( )

extern

#include <certgen.h>

A function to be overridden to pass certificate details to the certificate generator.

The library provides this function as a weak reference. The values returned by this weak reference are likely wrong for any real application and the user should provide their own function. Applicable for both self signed and ACME certificates generated onboard.

Returns

pointer to a CertGenData struct

SSL_CreateNewSelfSignedCert()

CertGenReturnCode SSL_CreateNewSelfSignedCert

(

CertGenData &

pGenData

)

#include <certgen.h>

Generates a new self-signed certificate that will be stored on the device.

The common name and alternative names used are taken from the parameters passed in.

By default, the certificate is generated using ECC with SECP384R1. This can be changed to an RSA key by undefining ENABLE_ECCKEY_CREATE in <nndk_install>\libraries\crypto\platform\<module name>\user_settings.h, and then rebuilding your application. To specify what curve or RSA key length is used in certificate generation, define DEFAULT_KEY_TYPE as one of the values defined by SslKeyType_t.

Parameters

pGenData

A pointer to structure used to hold data for certificate generation

Returns

CertGenReturnCode