OpenSSL API

Functions
int	wolfSSL_BN_mod_exp (WOLFSSL_BIGNUM *r, const WOLFSSL_BIGNUM *a, const WOLFSSL_BIGNUM *p, const WOLFSSL_BIGNUM *m, WOLFSSL_BN_CTX *ctx)
	This function performs the following math “r = (a^p) % m”. More...
const WOLFSSL_EVP_CIPHER *	wolfSSL_EVP_des_ede3_ecb (void)
	Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. wolfSSL_EVP_init() must be called once in the program first to populate these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ede3_ecb(). More...
const WOLFSSL_EVP_CIPHER *	wolfSSL_EVP_des_cbc (void)
	Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. wolfSSL_EVP_init() must be called once in the program first to populate these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ecb(). More...
int	wolfSSL_EVP_DigestInit_ex (WOLFSSL_EVP_MD_CTX *ctx, const WOLFSSL_EVP_MD *type, WOLFSSL_ENGINE *impl)
	Function for initializing WOLFSSL_EVP_MD_CTX. This function is a wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not use WOLFSSL_ENGINE. More...
int	wolfSSL_EVP_CipherInit_ex (WOLFSSL_EVP_CIPHER_CTX *ctx, const WOLFSSL_EVP_CIPHER *type, WOLFSSL_ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc)
	Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. More...
int	wolfSSL_EVP_EncryptInit_ex (WOLFSSL_EVP_CIPHER_CTX *ctx, const WOLFSSL_EVP_CIPHER *type, WOLFSSL_ENGINE *impl, const unsigned char *key, const unsigned char *iv)
	Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be encrypt. More...
int	wolfSSL_EVP_DecryptInit_ex (WOLFSSL_EVP_CIPHER_CTX *ctx, const WOLFSSL_EVP_CIPHER *type, WOLFSSL_ENGINE *impl, const unsigned char *key, const unsigned char *iv)
	Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be decrypt. More...
int	wolfSSL_EVP_CipherUpdate (WOLFSSL_EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl, const unsigned char *in, int inl)
	Function for encrypting/decrypting data. In buffer is added to be encrypted or decrypted and out buffer holds the results. outl will be the length of encrypted/decrypted information. More...
int	wolfSSL_EVP_CipherFinal (WOLFSSL_EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl)
	This function performs the final cipher operations adding in padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no encryption/decryption is done. If padding flag is seti padding is added and encrypted when ctx is set to encrypt, padding values are checked when set to decrypt. More...
int	wolfSSL_EVP_CIPHER_CTX_set_key_length (WOLFSSL_EVP_CIPHER_CTX *ctx, int keylen)
	Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length. More...
int	wolfSSL_EVP_CIPHER_CTX_block_size (const WOLFSSL_EVP_CIPHER_CTX *ctx)
	This is a getter function for the ctx block size. More...
int	wolfSSL_EVP_CIPHER_block_size (const WOLFSSL_EVP_CIPHER *cipher)
	This is a getter function for the block size of cipher. More...
void	wolfSSL_EVP_CIPHER_CTX_set_flags (WOLFSSL_EVP_CIPHER_CTX *ctx, int flags)
	Setter function for WOLFSSL_EVP_CIPHER_CTX structure. More...
void	wolfSSL_EVP_CIPHER_CTX_clear_flags (WOLFSSL_EVP_CIPHER_CTX *ctx, int flags)
	Clearing function for WOLFSSL_EVP_CIPHER_CTX structure. More...
int	wolfSSL_EVP_CIPHER_CTX_set_padding (WOLFSSL_EVP_CIPHER_CTX *c, int pad)
	Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding. More...
unsigned long	wolfSSL_EVP_CIPHER_CTX_flags (const WOLFSSL_EVP_CIPHER_CTX *ctx)
	Getter function for WOLFSSL_EVP_CIPHER_CTX structure. Deprecated v1.1.0. More...
int	wolfSSL_PEM_write_bio_PrivateKey (WOLFSSL_BIO *bio, WOLFSSL_EVP_PKEY *key, const WOLFSSL_EVP_CIPHER *cipher, unsigned char *passwd, int len, wc_pem_password_cb *cb, void *arg)
	This function writes a key into a WOLFSSL_BIO structure in PEM format. More...
int	wolfSSL_CTX_use_RSAPrivateKey_file (WOLFSSL_CTX *ctx, const char *file, int format)
	This function loads the private RSA key used in the SSL connection into the SSL context (WOLFSSL_CTX). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format. More...
int	wolfSSL_use_certificate_file (WOLFSSL *ssl, const char *file, int format)
	This function loads a certificate file into the SSL session (WOLFSSL structure). The certificate file is provided by the file argument. The format argument specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More...
int	wolfSSL_use_PrivateKey_file (WOLFSSL *ssl, const char *file, int format)
	This function loads a private key file into the SSL session (WOLFSSL structure). The key file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. More...
int	wolfSSL_use_certificate_chain_file (WOLFSSL *ssl, const char *file)
	This function loads a chain of certificates into the SSL session (WOLFSSL structure). The file containing the certificate chain is provided by the file argument, and must contain PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject certificate. More...
int	wolfSSL_use_RSAPrivateKey_file (WOLFSSL *ssl, const char *file, int format)
	This function loads the private RSA key used in the SSL connection into the SSL session (WOLFSSL structure). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format. More...
long	wolfSSL_set_tlsext_status_type (WOLFSSL *s, int type)
	This function is called when the client application request that a server send back an OCSP status response (also known as OCSP stapling).Currently, the only supported type is TLSEXT_STATUSTYPE_ocsp. More...
WOLFSSL_X509_CHAIN *	wolfSSL_get_peer_chain (WOLFSSL *ssl)
	Retrieves the peer’s certificate chain. More...
int	wolfSSL_get_chain_count (WOLFSSL_X509_CHAIN *chain)
	Retrieve's the peers certificate chain count. More...
int	wolfSSL_get_chain_length (WOLFSSL_X509_CHAIN *chain, int idx)
	Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx). More...
unsigned char *	wolfSSL_get_chain_cert (WOLFSSL_X509_CHAIN *chain, int idx)
	Retrieves the peer’s ASN1.DER certificate at index (idx). More...
int	wolfSSL_get_chain_cert_pem (WOLFSSL_X509_CHAIN *chain, int idx, unsigned char *buf, int inLen, int *outLen)
	Retrieves the peer’s PEM certificate at index (idx). More...
const unsigned char *	wolfSSL_get_sessionID (const WOLFSSL_SESSION *s)
	Retrieves the session’s ID. The session ID is always 32 bytes long. More...
int	wolfSSL_X509_get_serial_number (WOLFSSL_X509 *x509, unsigned char *in, int *inOutSz)
	Retrieves the peer’s certificate serial number. The serial number buffer (in) should be at least 32 bytes long and be provided as the *inOutSz argument as input. After calling the function *inOutSz will hold the actual length in bytes written to the in buffer. More...
WC_PKCS12 *	wolfSSL_d2i_PKCS12_bio (WOLFSSL_BIO *bio, WC_PKCS12 **pkcs12)
	wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 information from WOLFSSL_BIO to the structure WC_PKCS12. The information is divided up in the structure as a list of Content Infos along with a structure to hold optional MAC information. After the information has been divided into chunks (but not decrypted) in the structure WC_PKCS12, it can then be parsed and decrypted by calling. More...
WC_PKCS12 *	wolfSSL_i2d_PKCS12_bio (WOLFSSL_BIO *bio, WC_PKCS12 *pkcs12)
	wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert information from the structure WC_PKCS12 to WOLFSSL_BIO. More...
int	wolfSSL_PKCS12_parse (WC_PKCS12 *pkcs12, const char *psw, WOLFSSL_EVP_PKEY **pkey, WOLFSSL_X509 **cert, WOLF_STACK_OF(WOLFSSL_X509) **ca)
	PKCS12 can be enabled with adding –enable-opensslextra to the configure command. It can use triple DES and RC4 for decryption so would recommend also enabling these features when enabling opensslextra (–enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so decryption with RC2 is currently not available. This may be noticeable with default encryption schemes used by OpenSSL command line to create .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this function does is check the MAC is correct if present. If the MAC fails then the function returns and does not try to decrypt any of the stored Content Infos. This function then parses through each Content Info looking for a bag type, if the bag type is known it is decrypted as needed and either stored in the list of certificates being built or as a key found. After parsing through all bags the key found is then compared with the certificate list until a matching pair is found. This matching pair is then returned as the key and certificate, optionally the certificate list found is returned as a STACK_OF certificates. At the moment a CRL, Secret or SafeContents bag will be skipped over and not parsed. It can be seen if these or other “Unknown” bags are skipped over by viewing the debug print out. Additional attributes such as friendly name are skipped over when parsing a PKCS12 file. More...

Detailed Description

Function Documentation

wolfSSL_BN_mod_exp()

int wolfSSL_BN_mod_exp	(	WOLFSSL_BIGNUM *	r,
		const WOLFSSL_BIGNUM *	a,
		const WOLFSSL_BIGNUM *	p,
		const WOLFSSL_BIGNUM *	m,
		WOLFSSL_BN_CTX *	ctx
	)

This function performs the following math “r = (a^p) % m”.

Returns

SSL_SUCCESS On successfully performing math operation.

SSL_FAILURE If an error case was encountered.

Parameters

r	structure to hold result.
a	value to be raised by a power.
p	power to raise a by.
m	modulus to use.
ctx	currently not used with wolfSSL can be NULL.

Example

WOLFSSL_BIGNUM r,a,p,m;
int ret;
// set big number values
ret  = wolfSSL_BN_mod_exp(r, a, p, m, NULL);
// check ret value

See also

wolfSSL_BN_new

wolfSSL_BN_free

wolfSSL_CTX_use_RSAPrivateKey_file()

int wolfSSL_CTX_use_RSAPrivateKey_file	(	WOLFSSL_CTX *	ctx,
		const char *	file,
		int	format
	)

This function loads the private RSA key used in the SSL connection into the SSL context (WOLFSSL_CTX). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_CTX_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.

Returns

SSL_SUCCESS upon success.

SSL_FAILURE If the function call fails, possible causes might include: The input key file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs.

Parameters

ctx	a pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
file	a pointer to the name of the file containing the RSA private key to be loaded into the wolfSSL SSL context, with format as specified by format.
format	the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example

int ret = 0;
WOLFSSL_CTX* ctx;
...
ret = wolfSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”,
                                   SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading private key file
}
...

See also

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_use_RSAPrivateKey_file

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_PrivateKey_file

wolfSSL_d2i_PKCS12_bio()

WC_PKCS12* wolfSSL_d2i_PKCS12_bio	(	WOLFSSL_BIO *	bio,
		WC_PKCS12 **	pkcs12
	)

wolfSSL_d2i_PKCS12_bio (d2i_PKCS12_bio) copies in the PKCS12 information from WOLFSSL_BIO to the structure WC_PKCS12. The information is divided up in the structure as a list of Content Infos along with a structure to hold optional MAC information. After the information has been divided into chunks (but not decrypted) in the structure WC_PKCS12, it can then be parsed and decrypted by calling.

Returns

WC_PKCS12 pointer to a WC_PKCS12 structure.

Failure If function failed it will return NULL.

Parameters

bio	WOLFSSL_BIO structure to read PKCS12 buffer from.
pkcs12	WC_PKCS12 structure pointer for new PKCS12 structure created. Can be NULL

Example

WC_PKCS12* pkcs;
WOLFSSL_BIO* bio;
WOLFSSL_X509* cert;
WOLFSSL_EVP_PKEY* pkey;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
wc_PKCS12_free(pkcs)
//use cert, pkey, and optionally certs stack

See also

wolfSSL_PKCS12_parse

wc_PKCS12_free

wolfSSL_EVP_CIPHER_block_size()

int wolfSSL_EVP_CIPHER_block_size

(

const WOLFSSL_EVP_CIPHER *

cipher

)

This is a getter function for the block size of cipher.

Returns

size returns the block size.

Parameters

cipher

cipher to get block size of.

Example

printf(“block size = %d\n”,
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_aes_256_ecb()));

See also

wolfSSL_EVP_aes_256_ctr

wolfSSL_EVP_CIPHER_CTX_block_size()

int wolfSSL_EVP_CIPHER_CTX_block_size

(

const WOLFSSL_EVP_CIPHER_CTX *

ctx

)

This is a getter function for the ctx block size.

Returns

size Returns ctx->block_size.

Parameters

ctx	the cipher ctx to get block size of.

Example

const WOLFSSL_CVP_CIPHER_CTX* ctx;
//set up ctx
printf(“block size = %d\n”, wolfSSL_EVP_CIPHER_CTX_block_size(ctx));

See also

wolfSSL_EVP_CIPHER_block_size

wolfSSL_EVP_CIPHER_CTX_clear_flags()

void wolfSSL_EVP_CIPHER_CTX_clear_flags	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		int	flags
	)

Clearing function for WOLFSSL_EVP_CIPHER_CTX structure.

Returns

none No returns.

Parameters

ctx	structure to clear flag.
flag	flag value to clear in structure.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
int flag;
// create ctx
wolfSSL_EVP_CIPHER_CTX_clear_flags(ctx, flag);

See also

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_flags

wolfSSL_EVP_CIPHER_CTX_flags()

unsigned long wolfSSL_EVP_CIPHER_CTX_flags

(

const WOLFSSL_EVP_CIPHER_CTX *

ctx

)

Getter function for WOLFSSL_EVP_CIPHER_CTX structure. Deprecated v1.1.0.

Returns

unsigned long of flags/mode.

Parameters

ctx	structure to get flag.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
unsigned long flags;
ctx = wolfSSL_EVP_CIPHER_CTX_new()
flags = wolfSSL_EVP_CIPHER_CTX_flags(ctx);

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_set_flags()

void wolfSSL_EVP_CIPHER_CTX_set_flags	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		int	flags
	)

Setter function for WOLFSSL_EVP_CIPHER_CTX structure.

Returns

none No returns.

Parameters

ctx	structure to set flag.
flag	flag to set in structure.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
int flag;
// create ctx
wolfSSL_EVP_CIPHER_CTX_set_flags(ctx, flag);

See also

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_flags

wolfSSL_EVP_CIPHER_CTX_set_key_length()

int wolfSSL_EVP_CIPHER_CTX_set_key_length	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		int	keylen
	)

Setter function for WOLFSSL_EVP_CIPHER_CTX structure key length.

Returns

SSL_SUCCESS If successfully set.

SSL_FAILURE If failed to set key length.

Parameters

ctx	structure to set key length.
keylen	key length.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
int keylen;
// create ctx
wolfSSL_EVP_CIPHER_CTX_set_key_length(ctx, keylen);

See also

wolfSSL_EVP_CIPHER_flags

wolfSSL_EVP_CIPHER_CTX_set_padding()

int wolfSSL_EVP_CIPHER_CTX_set_padding	(	WOLFSSL_EVP_CIPHER_CTX *	c,
		int	pad
	)

Setter function for WOLFSSL_EVP_CIPHER_CTX structure to use padding.

Returns

SSL_SUCCESS If successfully set.

BAD_FUNC_ARG If null argument passed in.

Parameters

ctx	structure to set padding flag.
padding	0 for not setting padding, 1 for setting padding.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
// create ctx
wolfSSL_EVP_CIPHER_CTX_set_padding(ctx, 1);

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfSSL_EVP_CipherFinal()

int wolfSSL_EVP_CipherFinal	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		unsigned char *	out,
		int *	outl
	)

This function performs the final cipher operations adding in padding. If WOLFSSL_EVP_CIPH_NO_PADDING flag is set in WOLFSSL_EVP_CIPHER_CTX structure then 1 is returned and no encryption/decryption is done. If padding flag is seti padding is added and encrypted when ctx is set to encrypt, padding values are checked when set to decrypt.

Returns

1 Returned on success.

0 If encountering a failure.

Parameters

ctx	structure to decrypt/encrypt with.
out	buffer for final decrypt/encrypt.
out1	size of out buffer when data has been added by function.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx;
int out1;
unsigned char out[64];
// create ctx
wolfSSL_EVP_CipherFinal(ctx, out, &out1);

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfSSL_EVP_CipherInit_ex()

int wolfSSL_EVP_CipherInit_ex	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		const WOLFSSL_EVP_CIPHER *	type,
		WOLFSSL_ENGINE *	impl,
		const unsigned char *	key,
		const unsigned char *	iv,
		int	enc
	)

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE.

Returns

SSL_SUCCESS If successfully set.

SSL_FAILURE If not successful.

Parameters

ctx	structure to initialize.
type	type of encryption/decryption to do, for example AES.
impl	engine to use. N/A for wolfSSL, can be NULL.
key	key to set .
iv	iv if needed by algorithm.
enc	encryption (1) or decryption (0) flag.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
WOLFSSL_ENGINE* e = NULL;
unsigned char key[16];
unsigned char iv[12];
wolfCrypt_Init();
ctx = wolfSSL_EVP_CIPHER_CTX_new();
if (ctx == NULL) {
    printf("issue creating ctx\n");
    return -1;
}
 
printf("cipher init ex error ret = %d\n", wolfSSL_EVP_CipherInit_ex(NULL,
EVP_aes_128_    cbc(), e, key, iv, 1));
printf("cipher init ex success ret = %d\n", wolfSSL_EVP_CipherInit_ex(ctx,
EVP_aes_128_c    bc(), e, key, iv, 1));
// free resources

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfCrypt_Init

wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_CipherUpdate()

int wolfSSL_EVP_CipherUpdate	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		unsigned char *	out,
		int *	outl,
		const unsigned char *	in,
		int	inl
	)

Function for encrypting/decrypting data. In buffer is added to be encrypted or decrypted and out buffer holds the results. outl will be the length of encrypted/decrypted information.

Returns

SSL_SUCCESS If successful.

SSL_FAILURE If not successful.

Parameters

ctx	structure to get cipher type from.
out	buffer to hold output.
outl	adjusted to be size of output.
in	buffer to perform operation on.
inl	length of input buffer.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
unsigned char out[100];
int outl;
unsigned char in[100];
int inl = 100;
 
ctx = wolfSSL_EVP_CIPHER_CTX_new();
// set up ctx
ret = wolfSSL_EVP_CipherUpdate(ctx, out, outl, in, inl);
// check ret value
// buffer out holds outl bytes of data
// free resources

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfCrypt_Init

wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_DecryptInit_ex()

int wolfSSL_EVP_DecryptInit_ex	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		const WOLFSSL_EVP_CIPHER *	type,
		WOLFSSL_ENGINE *	impl,
		const unsigned char *	key,
		const unsigned char *	iv
	)

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be decrypt.

Returns

SSL_SUCCESS If successfully set.

SSL_FAILURE If not successful.

Parameters

ctx	structure to initialize.
type	type of encryption/decryption to do, for example AES.
impl	engine to use. N/A for wolfSSL, can be NULL.
key	key to set .
iv	iv if needed by algorithm.
enc	encryption (1) or decryption (0) flag.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
WOLFSSL_ENGINE* e = NULL;
unsigned char key[16];
unsigned char iv[12];
 
wolfCrypt_Init();
 
ctx = wolfSSL_EVP_CIPHER_CTX_new();
if (ctx == NULL) {
    printf("issue creating ctx\n");
    return -1;
}
 
printf("cipher init ex error ret = %d\n", wolfSSL_EVP_DecryptInit_ex(NULL,
EVP_aes_128_    cbc(), e, key, iv, 1));
printf("cipher init ex success ret = %d\n", wolfSSL_EVP_DecryptInit_ex(ctx,
EVP_aes_128_c    bc(), e, key, iv, 1));
// free resources

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfCrypt_Init

wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_EVP_des_cbc()

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_cbc

(

void

)

Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. wolfSSL_EVP_init() must be called once in the program first to populate these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ecb().

Returns

pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES operations.

Parameters

none	No parameters.

Example

WOLFSSL_EVP_CIPHER* cipher;
cipher = wolfSSL_EVP_des_cbc();
…

See also

wolfSSL_EVP_CIPHER_CTX_init

wolfSSL_EVP_des_ede3_ecb()

const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb

(

void

)

Getter functions for the respective WOLFSSL_EVP_CIPHER pointers. wolfSSL_EVP_init() must be called once in the program first to populate these cipher strings. WOLFSSL_DES_ECB macro must be defined for wolfSSL_EVP_des_ede3_ecb().

Returns

pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations.

Parameters

none	No parameters.

Example

printf("block size des ede3 cbc = %d\n",
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_cbc()));
printf("block size des ede3 ecb = %d\n",
wolfSSL_EVP_CIPHER_block_size(wolfSSL_EVP_des_ede3_ecb()));

See also

wolfSSL_EVP_CIPHER_CTX_init

wolfSSL_EVP_DigestInit_ex()

int wolfSSL_EVP_DigestInit_ex	(	WOLFSSL_EVP_MD_CTX *	ctx,
		const WOLFSSL_EVP_MD *	type,
		WOLFSSL_ENGINE *	impl
	)

Function for initializing WOLFSSL_EVP_MD_CTX. This function is a wrapper for wolfSSL_EVP_DigestInit() because wolfSSL does not use WOLFSSL_ENGINE.

Returns

SSL_SUCCESS If successfully set.

SSL_FAILURE If not successful.

Parameters

ctx	structure to initialize.
type	type of hash to do, for example SHA.
impl	engine to use. N/A for wolfSSL, can be NULL.

Example

WOLFSSL_EVP_MD_CTX* md = NULL;
wolfCrypt_Init();
md = wolfSSL_EVP_MD_CTX_new();
if (md == NULL) {
    printf("error setting md\n");
    return -1;
}
printf("cipher md init ret = %d\n", wolfSSL_EVP_DigestInit_ex(md,
wolfSSL_EVP_sha1(), e));
//free resources

See also

wolfSSL_EVP_MD_CTX_new

wolfCrypt_Init

wolfSSL_EVP_MD_CTX_free

wolfSSL_EVP_EncryptInit_ex()

int wolfSSL_EVP_EncryptInit_ex	(	WOLFSSL_EVP_CIPHER_CTX *	ctx,
		const WOLFSSL_EVP_CIPHER *	type,
		WOLFSSL_ENGINE *	impl,
		const unsigned char *	key,
		const unsigned char *	iv
	)

Function for initializing WOLFSSL_EVP_CIPHER_CTX. This function is a wrapper for wolfSSL_EVP_CipherInit() because wolfSSL does not use WOLFSSL_ENGINE. Sets encrypt flag to be encrypt.

Returns

SSL_SUCCESS If successfully set.

SSL_FAILURE If not successful.

Parameters

ctx	structure to initialize.
type	type of encryption to do, for example AES.
impl	engine to use. N/A for wolfSSL, can be NULL.
key	key to use.
iv	iv to use.

Example

WOLFSSL_EVP_CIPHER_CTX* ctx = NULL;
wolfCrypt_Init();
ctx = wolfSSL_EVP_CIPHER_CTX_new();
if (ctx == NULL) {
    printf("error setting ctx\n");
    return -1;
}
printf("cipher ctx init ret = %d\n", wolfSSL_EVP_EncryptInit_ex(ctx,
wolfSSL_EVP_aes_128_cbc(), e, key, iv));
//free resources

See also

wolfSSL_EVP_CIPHER_CTX_new

wolfCrypt_Init

wolfSSL_EVP_CIPHER_CTX_free

wolfSSL_get_chain_cert()

unsigned char* wolfSSL_get_chain_cert	(	WOLFSSL_X509_CHAIN *	chain,
		int	idx
	)

Retrieves the peer’s ASN1.DER certificate at index (idx).

Returns

Success If successful the call will return the peer’s certificate by index.

0 will be returned if an invalid chain pointer is passed to the function.

Parameters

chain	pointer to a valid WOLFSSL_X509_CHAIN structure.
idx	index to start of chain.

Example

none

See also

wolfSSL_get_peer_chain

wolfSSL_get_chain_count

wolfSSL_get_chain_length

wolfSSL_get_chain_cert_pem

wolfSSL_get_chain_cert_pem()

int wolfSSL_get_chain_cert_pem	(	WOLFSSL_X509_CHAIN *	chain,
		int	idx,
		unsigned char *	buf,
		int	inLen,
		int *	outLen
	)

Retrieves the peer’s PEM certificate at index (idx).

Returns

Success If successful the call will return the peer’s certificate by index.

0 will be returned if an invalid chain pointer is passed to the function.

Parameters

chain	pointer to a valid WOLFSSL_X509_CHAIN structure.
idx	indexto start of chain.

Example

none

See also

wolfSSL_get_peer_chain

wolfSSL_get_chain_count

wolfSSL_get_chain_length

wolfSSL_get_chain_cert

wolfSSL_get_chain_count()

int wolfSSL_get_chain_count

(

WOLFSSL_X509_CHAIN *

chain

)

Retrieve's the peers certificate chain count.

Returns

Success If successful the call will return the peer’s certificate chain count.

0 will be returned if an invalid chain pointer is passed to the function.

Parameters

chain

pointer to a valid WOLFSSL_X509_CHAIN structure.

Example

none

See also

wolfSSL_get_peer_chain

wolfSSL_get_chain_length

wolfSSL_get_chain_cert

wolfSSL_get_chain_cert_pem

wolfSSL_get_chain_length()

int wolfSSL_get_chain_length	(	WOLFSSL_X509_CHAIN *	chain,
		int	idx
	)

Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx).

Returns

Success If successful the call will return the peer’s certificate length in bytes by index.

0 will be returned if an invalid chain pointer is passed to the function.

Parameters

chain	pointer to a valid WOLFSSL_X509_CHAIN structure.
idx	index to start of chain.

Example

none

See also

wolfSSL_get_peer_chain

wolfSSL_get_chain_count

wolfSSL_get_chain_cert

wolfSSL_get_chain_cert_pem

wolfSSL_get_peer_chain()

WOLFSSL_X509_CHAIN* wolfSSL_get_peer_chain

(

WOLFSSL *

ssl

)

Retrieves the peer’s certificate chain.

Returns

chain If successful the call will return the peer’s certificate chain.

0 will be returned if an invalid WOLFSSL pointer is passed to the function.

Parameters

ssl	pointer to a valid WOLFSSL structure.

Example

none

See also

wolfSSL_get_chain_count

wolfSSL_get_chain_length

wolfSSL_get_chain_cert

wolfSSL_get_chain_cert_pem

wolfSSL_get_sessionID()

const unsigned char* wolfSSL_get_sessionID

(

const WOLFSSL_SESSION *

s

)

Retrieves the session’s ID. The session ID is always 32 bytes long.

Returns

id The session ID.

Parameters

session

pointer to a valid wolfssl session.

Example

none

See also

SSL_get_session

wolfSSL_i2d_PKCS12_bio()

WC_PKCS12* wolfSSL_i2d_PKCS12_bio	(	WOLFSSL_BIO *	bio,
		WC_PKCS12 *	pkcs12
	)

wolfSSL_i2d_PKCS12_bio (i2d_PKCS12_bio) copies in the cert information from the structure WC_PKCS12 to WOLFSSL_BIO.

Returns

1 for success.

Failure 0.

Parameters

bio	WOLFSSL_BIO structure to write PKCS12 buffer to.
pkcs12	WC_PKCS12 structure for PKCS12 structure as input.

Example

WC_PKCS12 pkcs12;
FILE *f;
byte buffer[5300];
char file[] = "./test.p12";
int bytes;
WOLFSSL_BIO* bio;
pkcs12 = wc_PKCS12_new();
f = fopen(file, "rb");
bytes = (int)fread(buffer, 1, sizeof(buffer), f);
fclose(f);
//convert the DER file into an internal structure
wc_d2i_PKCS12(buffer, bytes, pkcs12);
bio = wolfSSL_BIO_new(wolfSSL_BIO_s_mem());
//convert PKCS12 structure into bio
wolfSSL_i2d_PKCS12_bio(bio, pkcs12);
wc_PKCS12_free(pkcs)
//use bio

See also

wolfSSL_PKCS12_parse

wc_PKCS12_free

wolfSSL_PEM_write_bio_PrivateKey()

int wolfSSL_PEM_write_bio_PrivateKey	(	WOLFSSL_BIO *	bio,
		WOLFSSL_EVP_PKEY *	key,
		const WOLFSSL_EVP_CIPHER *	cipher,
		unsigned char *	passwd,
		int	len,
		wc_pem_password_cb *	cb,
		void *	arg
	)

This function writes a key into a WOLFSSL_BIO structure in PEM format.

Returns

SSL_SUCCESS upon success.

SSL_FAILURE upon failure.

Parameters

bio	WOLFSSL_BIO structure to get PEM buffer from.
key	key to convert to PEM format.
cipher	EVP cipher structure.
passwd	password.
len	length of password.
cb	password callback.
arg	optional argument.

Example

WOLFSSL_BIO* bio;
WOLFSSL_EVP_PKEY* key;
int ret;
// create bio and setup key
ret = wolfSSL_PEM_write_bio_PrivateKey(bio, key, NULL, NULL, 0, NULL, NULL);
//check ret value

See also

wolfSSL_PEM_read_bio_X509_AUX

wolfSSL_PKCS12_parse()

int wolfSSL_PKCS12_parse	(	WC_PKCS12 *	pkcs12,
		const char *	psw,
		WOLFSSL_EVP_PKEY **	pkey,
		WOLFSSL_X509 **	cert,
		WOLF_STACK_OF(WOLFSSL_X509) **	ca
	)

PKCS12 can be enabled with adding –enable-opensslextra to the configure command. It can use triple DES and RC4 for decryption so would recommend also enabling these features when enabling opensslextra (–enable-des3 –enable-arc4). wolfSSL does not currently support RC2 so decryption with RC2 is currently not available. This may be noticeable with default encryption schemes used by OpenSSL command line to create .p12 files. wolfSSL_PKCS12_parse (PKCS12_parse). The first thing this function does is check the MAC is correct if present. If the MAC fails then the function returns and does not try to decrypt any of the stored Content Infos. This function then parses through each Content Info looking for a bag type, if the bag type is known it is decrypted as needed and either stored in the list of certificates being built or as a key found. After parsing through all bags the key found is then compared with the certificate list until a matching pair is found. This matching pair is then returned as the key and certificate, optionally the certificate list found is returned as a STACK_OF certificates. At the moment a CRL, Secret or SafeContents bag will be skipped over and not parsed. It can be seen if these or other “Unknown” bags are skipped over by viewing the debug print out. Additional attributes such as friendly name are skipped over when parsing a PKCS12 file.

Returns

SSL_SUCCESS On successfully parsing PKCS12.

SSL_FAILURE If an error case was encountered.

Parameters

pkcs12	WC_PKCS12 structure to parse.
paswd	password for decrypting PKCS12.
pkey	structure to hold private key decoded from PKCS12.
cert	structure to hold certificate decoded from PKCS12.
stack	optional stack of extra certificates.

Example

WC_PKCS12* pkcs;
WOLFSSL_BIO* bio;
WOLFSSL_X509* cert;
WOLFSSL_EVP_PKEY* pkey;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
wolfSSL_d2i_PKCS12_bio(bio, &pkcs);
wolfSSL_PKCS12_parse(pkcs, “a password”, &pkey, &cert, &certs)
wc_PKCS12_free(pkcs)
//use cert, pkey, and optionally certs stack

See also

wolfSSL_d2i_PKCS12_bio

wc_PKCS12_free

wolfSSL_set_tlsext_status_type()

long wolfSSL_set_tlsext_status_type	(	WOLFSSL *	s,
		int	type
	)

This function is called when the client application request that a server send back an OCSP status response (also known as OCSP stapling).Currently, the only supported type is TLSEXT_STATUSTYPE_ocsp.

Returns

1 upon success.

0 upon error.

Parameters

s	pointer to WOLFSSL struct which is created by SSL_new() function
type	ssl extension type which TLSEXT_STATUSTYPE_ocsp is only supported.

Example

WOLFSSL *ssl;
WOLFSSL_CTX *ctx;
int ret;
ctx = wolfSSL_CTX_new(wolfSSLv23_server_method());
ssl = wolfSSL_new(ctx);
ret = WolfSSL_set_tlsext_status_type(ssl,TLSEXT_STATUSTYPE_ocsp);
wolfSSL_free(ssl);
wolfSSL_CTX_free(ctx);

See also

wolfSSL_new

wolfSSL_CTX_new

wolfSSL_free

wolfSSL_CTX_free

wolfSSL_use_certificate_chain_file()

int wolfSSL_use_certificate_chain_file	(	WOLFSSL *	ssl,
		const char *	file
	)

This function loads a chain of certificates into the SSL session (WOLFSSL structure). The file containing the certificate chain is provided by the file argument, and must contain PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject certificate.

Returns

SSL_SUCCESS upon success.

SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs

Parameters

ssl	a pointer to a WOLFSSL structure, created using wolfSSL_new()
file	a pointer to the name of the file containing the chain of certificates to be loaded into the wolfSSL SSL session. Certificates must be in PEM format.

Example

int ret = 0;
WOLFSSL* ctx;
...
ret = wolfSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

See also

wolfSSL_CTX_use_certificate_chain_file

wolfSSL_CTX_use_certificate_chain_buffer

wolfSSL_use_certificate_chain_buffer

wolfSSL_use_certificate_file()

int wolfSSL_use_certificate_file	(	WOLFSSL *	ssl,
		const char *	file,
		int	format
	)

This function loads a certificate file into the SSL session (WOLFSSL structure). The certificate file is provided by the file argument. The format argument specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

Returns

SSL_SUCCESS upon success

SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs, Base16 decoding fails on the file

Parameters

ssl	a pointer to a WOLFSSL structure, created with wolfSSL_new().
file	a pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL session, with format as specified by format.
format	the encoding type of the certificate specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_certificate_file(ssl, “./client-cert.pem”,
                             SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading cert file
}
...

See also

wolfSSL_CTX_use_certificate_buffer

wolfSSL_CTX_use_certificate_file

wolfSSL_use_certificate_buffer

wolfSSL_use_PrivateKey_file()

int wolfSSL_use_PrivateKey_file	(	WOLFSSL *	ssl,
		const char *	file,
		int	format
	)

This function loads a private key file into the SSL session (WOLFSSL structure). The key file is provided by the file argument. The format argument specifies the format type of the file - SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.

If using an external key store and do not have the private key you can instead provide the public key and register the crypro callback to handle the signing. For this you can build with either build with crypto callbacks or PK callbacks. To enable crypto callbacks use –enable-cryptocb or WOLF_CRYPTO_CB and register a crypto callback using wc_CryptoCb_RegisterDevice and set the associated devId using wolfSSL_SetDevId.

Returns

SSL_SUCCESS upon success.

SSL_FAILURE If the function call fails, possible causes might include: The file is in the wrong format, or the wrong format has been given using the “format” argument, The file doesn’t exist, can’t be read, or is corrupted, An out of memory condition occurs, Base16 decoding fails on the file, The key file is encrypted but no password is provided

Parameters

ssl	a pointer to a WOLFSSL structure, created with wolfSSL_new().
file	a pointer to the name of the file containing the key file to be loaded into the wolfSSL SSL session, with format as specified by format.
format	the encoding type of the key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_PrivateKey_file(ssl, “./server-key.pem”,
                            SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading key file
}
...

See also

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_use_PrivateKey_buffer

wc_CryptoCb_RegisterDevice

wolfSSL_SetDevId

wolfSSL_use_RSAPrivateKey_file()

int wolfSSL_use_RSAPrivateKey_file	(	WOLFSSL *	ssl,
		const char *	file,
		int	format
	)

This function loads the private RSA key used in the SSL connection into the SSL session (WOLFSSL structure). This function is only available when wolfSSL has been compiled with the OpenSSL compatibility layer enabled (–enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used wolfSSL_use_PrivateKey_file() function. The file argument contains a pointer to the RSA private key file, in the format specified by format.

Returns

SSL_SUCCESS upon success

SSL_FAILURE If the function call fails, possible causes might include: The input key file is in the wrong format, or the wrong format has been given using the “format” argument, file doesn’t exist, can’t be read, or is corrupted, an out of memory condition occurs

Parameters

ssl	a pointer to a WOLFSSL structure, created using wolfSSL_new()
file	a pointer to the name of the file containing the RSA private key to be loaded into the wolfSSL SSL session, with format as specified by format.
format	the encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example

int ret = 0;
WOLFSSL* ssl;
...
ret = wolfSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”,
                               SSL_FILETYPE_PEM);
if (ret != SSL_SUCCESS) {
    // error loading private key file
}
...

See also

wolfSSL_CTX_use_RSAPrivateKey_file

wolfSSL_CTX_use_PrivateKey_buffer

wolfSSL_CTX_use_PrivateKey_file

wolfSSL_use_PrivateKey_buffer

wolfSSL_use_PrivateKey_file

wolfSSL_X509_get_serial_number()

int wolfSSL_X509_get_serial_number	(	WOLFSSL_X509 *	x509,
		unsigned char *	in,
		int *	inOutSz
	)

Retrieves the peer’s certificate serial number. The serial number buffer (in) should be at least 32 bytes long and be provided as the *inOutSz argument as input. After calling the function *inOutSz will hold the actual length in bytes written to the in buffer.

Returns

SSL_SUCCESS upon success.

BAD_FUNC_ARG will be returned if a bad function argument was encountered.

Parameters

in	The serial number buffer and should be at least 32 bytes long
inOutSz	will hold the actual length in bytes written to the in buffer.

Example

none

See also

SSL_get_peer_certificate