OpenSSL API

Functions

	Name
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”.
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().
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().
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.
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.
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.
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.
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.
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.
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.
int	wolfSSL_EVP_CIPHER_CTX_block_size(const WOLFSSL_EVP_CIPHER_CTX * ctx) This is a getter function for the ctx block size.
int	wolfSSL_EVP_CIPHER_block_size(const WOLFSSL_EVP_CIPHER * cipher) This is a getter function for the block size of cipher.
void	wolfSSL_EVP_CIPHER_CTX_set_flags(WOLFSSL_EVP_CIPHER_CTX * ctx, int flags) Setter function for WOLFSSL_EVP_CIPHER_CTX structure.
void	wolfSSL_EVP_CIPHER_CTX_clear_flags(WOLFSSL_EVP_CIPHER_CTX * ctx, int flags) Clearing function for WOLFSSL_EVP_CIPHER_CTX structure.
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.
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.
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.
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.
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.
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.
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.
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.
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.
WOLFSSL_X509_CHAIN *	wolfSSL_get_peer_chain(WOLFSSL * ssl) Retrieves the peer’s certificate chain.
int	wolfSSL_get_chain_count(WOLFSSL_X509_CHAIN * chain) Retrieve's the peers certificate chain count.
int	wolfSSL_get_chain_length(WOLFSSL_X509_CHAIN * chain, int idx) Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx).
unsigned char *	wolfSSL_get_chain_cert(WOLFSSL_X509_CHAIN * chain, int idx) Retrieves the peer’s ASN1.DER certificate at index (idx).
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).
const unsigned char *	wolfSSL_get_sessionID(const WOLFSSL_SESSION * s) Retrieves the session’s ID. The session ID is always 32 bytes long.
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.
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.
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.
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.

Functions Documentation

function 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”.

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.

See:

wolfSSL_BN_new
wolfSSL_BN_free

Return:

SSL_SUCCESS On successfully performing math operation.
SSL_FAILURE If an error case was encountered.

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

function 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().

Parameters:

none No parameters.

See: wolfSSL_EVP_CIPHER_CTX_init

Return: pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES EDE3 operations.

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()));

function 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().

Parameters:

none No parameters.

See: wolfSSL_EVP_CIPHER_CTX_init

Return: pointer Returns a WOLFSSL_EVP_CIPHER pointer for DES operations.

Example

WOLFSSL_EVP_CIPHER* cipher;
cipher = wolfSSL_EVP_des_cbc();
…

function 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.

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.

See:

wolfSSL_EVP_MD_CTX_new
wolfCrypt_Init
wolfSSL_EVP_MD_CTX_free

Return:

SSL_SUCCESS If successfully set.
SSL_FAILURE If not successful.

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

function 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.

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.

See:

wolfSSL_EVP_CIPHER_CTX_new
wolfCrypt_Init
wolfSSL_EVP_CIPHER_CTX_free

Return:

SSL_SUCCESS If successfully set.
SSL_FAILURE If not successful.

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

function 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.

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.

See:

wolfSSL_EVP_CIPHER_CTX_new
wolfCrypt_Init
wolfSSL_EVP_CIPHER_CTX_free

Return:

SSL_SUCCESS If successfully set.
SSL_FAILURE If not successful.

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

function 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.

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.

See:

wolfSSL_EVP_CIPHER_CTX_new
wolfCrypt_Init
wolfSSL_EVP_CIPHER_CTX_free

Return:

SSL_SUCCESS If successfully set.
SSL_FAILURE If not successful.

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

function 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.

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.

See:

wolfSSL_EVP_CIPHER_CTX_new
wolfCrypt_Init
wolfSSL_EVP_CIPHER_CTX_free

Return:

SSL_SUCCESS If successful.
SSL_FAILURE If not successful.

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

function 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.

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.

See: wolfSSL_EVP_CIPHER_CTX_new

Return:

1 Returned on success.
0 If encountering a failure.

Example

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

function 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.

Parameters:

ctx structure to set key length.
keylen key length.

See: wolfSSL_EVP_CIPHER_flags

Return:

SSL_SUCCESS If successfully set.
SSL_FAILURE If failed to set key length.

Example

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

function 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.

Parameters:

ctx the cipher ctx to get block size of.

See: wolfSSL_EVP_CIPHER_block_size

Return: size Returns ctx->block_size.

Example

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

function 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.

Parameters:

cipher cipher to get block size of.

See: wolfSSL_EVP_aes_256_ctr

Return: size returns the block size.

Example

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

function 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.

Parameters:

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

See:

wolfSSL_EVP_CIPHER_flags
wolfSSL_EVP_CIPHER_CTX_flags

Return: none No returns.

Example

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

function 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.

Parameters:

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

See:

wolfSSL_EVP_CIPHER_flags
wolfSSL_EVP_CIPHER_CTX_flags

Return: none No returns.

Example

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

function 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.

Parameters:

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

See: wolfSSL_EVP_CIPHER_CTX_new

Return:

SSL_SUCCESS If successfully set.
BAD_FUNC_ARG If null argument passed in.

Example

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

function 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.

Parameters:

ctx structure to get flag.

See:

wolfSSL_EVP_CIPHER_CTX_new
wolfSSL_EVP_CIPHER_flags

Return: unsigned long of flags/mode.

Example

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

function 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.

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.

See: wolfSSL_PEM_read_bio_X509_AUX

Return:

SSL_SUCCESS upon success.
SSL_FAILURE upon failure.

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

function 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.

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.

See:

Return:

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.

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
}
...

function 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.

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.

See:

Return:

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

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
}
...

function 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.

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.

See:

Return:

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

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.

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
}
...

function 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.

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.

See:

Return:

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

Example

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

function 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.

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.

See:

Return:

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

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
}
...

function 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.

Parameters:

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

See:

Return:

1 upon success.
0 upon error.

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);

function wolfSSL_get_peer_chain

WOLFSSL_X509_CHAIN * wolfSSL_get_peer_chain(
    WOLFSSL * ssl
)

Retrieves the peer’s certificate chain.

Parameters:

ssl pointer to a valid WOLFSSL structure.

See:

Return:

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.

Example

none

function wolfSSL_get_chain_count

int wolfSSL_get_chain_count(
    WOLFSSL_X509_CHAIN * chain
)

Retrieve's the peers certificate chain count.

Parameters:

chain pointer to a valid WOLFSSL_X509_CHAIN structure.

See:

Return:

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.

Example

none

function 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).

Parameters:

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

See:

Return:

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.

Example

none

function 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).

Parameters:

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

See:

Return:

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.

Example

none

function 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).

Parameters:

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

See:

Return:

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.

Example

none

function 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.

Parameters:

session pointer to a valid wolfssl session.

See: SSL_get_session

Return: id The session ID.

Example

none

function 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.

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.

See: SSL_get_peer_certificate

Return:

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

Example

none

function 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.

Parameters:

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

See:

wolfSSL_PKCS12_parse
wc_PKCS12_free

Return:

WC_PKCS12 pointer to a WC_PKCS12 structure.
Failure If function failed it will return 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

function 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.

Parameters:

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

See:

wolfSSL_PKCS12_parse
wc_PKCS12_free

Return:

1 for success.
Failure 0.

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

function 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.

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.

See:

wolfSSL_d2i_PKCS12_bio
wc_PKCS12_free

Return:

SSL_SUCCESS On successfully parsing PKCS12.
SSL_FAILURE If an error case was encountered.

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

Updated on 2024-12-20 at 01:22:24 +0000