Functions
OpenSSL API

Functions

WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API int wolfSSL_EVP_CIPHER_CTX_block_size (const WOLFSSL_EVP_CIPHER_CTX *ctx)
 This is a getter function for the ctx block size. More...
 
WOLFSSL_API int wolfSSL_EVP_CIPHER_block_size (const WOLFSSL_EVP_CIPHER *cipher)
 This is a getter function for the block size of cipher. More...
 
WOLFSSL_API void wolfSSL_EVP_CIPHER_CTX_set_flags (WOLFSSL_EVP_CIPHER_CTX *ctx, int flags)
 Setter function for WOLFSSL_EVP_CIPHER_CTX structure. More...
 
WOLFSSL_API void wolfSSL_EVP_CIPHER_CTX_clear_flags (WOLFSSL_EVP_CIPHER_CTX *ctx, int flags)
 Clearing function for WOLFSSL_EVP_CIPHER_CTX structure. More...
 
WOLFSSL_API 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...
 
WOLFSSL_API int wolfSSL_PEM_write_bio_PrivateKey (WOLFSSL_BIO *bio, WOLFSSL_EVP_PKEY *key, const WOLFSSL_EVP_CIPHER *cipher, unsigned char *passwd, int len, pem_password_cb *cb, void *arg)
 This function writes a key into a WOLFSSL_BIO structure in PEM format. More...
 
WOLFSSL_API int wolfSSL_CTX_use_RSAPrivateKey_file (WOLFSSL_CTX *, const char *, int)
 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...
 
WOLFSSL_API int wolfSSL_use_certificate_file (WOLFSSL *, const char *, int)
 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...
 
WOLFSSL_API int wolfSSL_use_PrivateKey_file (WOLFSSL *, const char *, int)
 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...
 
WOLFSSL_API int wolfSSL_use_certificate_chain_file (WOLFSSL *, 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...
 
WOLFSSL_API int wolfSSL_use_RSAPrivateKey_file (WOLFSSL *, const char *, int)
 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...
 
WOLFSSL_API 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_API WOLFSSL_X509_CHAINwolfSSL_get_peer_chain (WOLFSSL *ssl)
 Retrieves the peer’s certificate chain. More...
 
WOLFSSL_API int wolfSSL_get_chain_count (WOLFSSL_X509_CHAIN *chain)
 Retrieve's the peers certificate chain count. More...
 
WOLFSSL_API int wolfSSL_get_chain_length (WOLFSSL_X509_CHAIN *, int idx)
 Retrieves the peer’s ASN1.DER certificate length in bytes at index (idx). More...
 
WOLFSSL_API unsigned char * wolfSSL_get_chain_cert (WOLFSSL_X509_CHAIN *, int idx)
 Retrieves the peer’s ASN1.DER certificate at index (idx). More...
 
WOLFSSL_API int wolfSSL_get_chain_cert_pem (WOLFSSL_X509_CHAIN *, int idx, unsigned char *buf, int inLen, int *outLen)
 Retrieves the peer’s PEM certificate at index (idx). More...
 
WOLFSSL_API const unsigned char * wolfSSL_get_sessionID (const WOLFSSL_SESSION *s)
 Retrieves the session’s ID. The session ID is always 32 bytes long. More...
 
WOLFSSL_API int wolfSSL_X509_get_serial_number (WOLFSSL_X509 *, unsigned char *, int *)
 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...
 
WOLFSSL_API 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...
 
WOLFSSL_API 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()

WOLFSSL_API 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
rstructure to hold result.
avalue to be raised by a power.
ppower to raise a by.
mmodulus to use.
ctxcurrently 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()

WOLFSSL_API int wolfSSL_CTX_use_RSAPrivateKey_file ( WOLFSSL_CTX ,
const char *  ,
int   
)

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
ctxa pointer to a WOLFSSL_CTX structure, created using wolfSSL_CTX_new()
filea 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.
formatthe encoding type of the RSA private key specified by file. Possible values include SSL_FILETYPE_PEM and SSL_FILETYPE_ASN1.

Example

int ret = 0;
...
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()

WOLFSSL_API 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
bioWOLFSSL_BIO structure to read PKCS12 buffer from.
pkcs12WC_PKCS12 structure pointer for new PKCS12 structure created. Can be NULL

Example

WC_PKCS12* pkcs;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
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()

WOLFSSL_API 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
ciphercipher 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()

WOLFSSL_API 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
ctxthe 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()

WOLFSSL_API 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
ctxstructure to clear flag.
flagflag value to clear in structure.

Example

int flag;
// create ctx
See also
wolfSSL_EVP_CIPHER_flags

◆ wolfSSL_EVP_CIPHER_CTX_set_flags()

WOLFSSL_API 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
ctxstructure to set flag.
flagflag to set in structure.

Example

int flag;
// create ctx
See also
wolfSSL_EVP_CIPHER_flags

◆ wolfSSL_EVP_CIPHER_CTX_set_key_length()

WOLFSSL_API 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
ctxstructure to set key length.
keylenkey length.

Example

int keylen;
// create ctx
See also
wolfSSL_EVP_CIPHER_flags

◆ wolfSSL_EVP_CIPHER_CTX_set_padding()

WOLFSSL_API 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
ctxstructure to set padding flag.
padding0 for not setting padding, 1 for setting padding.

Example

See also
wolfSSL_EVP_CIPHER_flags

◆ wolfSSL_EVP_CipherFinal()

WOLFSSL_API 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
ctxstructure to decrypt/encrypt with.
outbuffer for final decrypt/encrypt.
out1size of out buffer when data has been added by function.

Example

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

WOLFSSL_API 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
ctxstructure to initialize.
typetype of encryption/decryption to do, for example AES.
implengine to use. N/A for wolfSSL, can be NULL.
keykey to set .
iviv if needed by algorithm.
encencryption (1) or decryption (0) flag.

Example

WOLFSSL_ENGINE* e = NULL;
unsigned char key[16];
unsigned char iv[12];
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()

WOLFSSL_API 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 successfull.
SSL_FAILURE If not successful.
Parameters
ctxstructure to get cipher type from.
outbuffer to hold output.
outladjusted to be size of output.
inbuffer to perform operation on.
inllength of input buffer.

Example

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

WOLFSSL_API 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
ctxstructure to initialize.
typetype of encryption/decryption to do, for example AES.
implengine to use. N/A for wolfSSL, can be NULL.
keykey to set .
iviv if needed by algorithm.
encencryption (1) or decryption (0) flag.
_Example_
WOLFSSL_ENGINE* e = NULL;
unsigned char key[16];
unsigned char iv[12];
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()

WOLFSSL_API 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
noneNo parameters.

Example

WOLFSSL_EVP_CIPHER* cipher;
See also
wolfSSL_EVP_CIPHER_CTX_init

◆ wolfSSL_EVP_des_ede3_ecb()

WOLFSSL_API 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
noneNo 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",
See also
wolfSSL_EVP_CIPHER_CTX_init

◆ wolfSSL_EVP_DigestInit_ex()

WOLFSSL_API 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
ctxstructure to initialize.
typetype of hash to do, for example SHA.
implengine to use. N/A for wolfSSL, can be NULL.

Example

WOLFSSL_EVP_MD_CTX* md = NULL;
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()

WOLFSSL_API 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
ctxstructure to initialize.
typetype of encryption to do, for example AES.
implengine to use. N/A for wolfSSL, can be NULL.
keykey to use.
iviv to use.

Example

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

WOLFSSL_API unsigned char* wolfSSL_get_chain_cert ( WOLFSSL_X509_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
chainpointer to a valid WOLFSSL_X509_CHAIN structure.
idxindex 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()

WOLFSSL_API int wolfSSL_get_chain_cert_pem ( WOLFSSL_X509_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
chainpointer to a valid WOLFSSL_X509_CHAIN structure.
idxindexto 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()

WOLFSSL_API 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
chainpointer 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()

WOLFSSL_API int wolfSSL_get_chain_length ( WOLFSSL_X509_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
chainpointer to a valid WOLFSSL_X509_CHAIN structure.
idxindex 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_API 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
sslpointer 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()

WOLFSSL_API 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
sessionpointer to a valid wolfssl session.

Example

none
See also
SSL_get_session

◆ wolfSSL_PEM_write_bio_PrivateKey()

WOLFSSL_API int wolfSSL_PEM_write_bio_PrivateKey ( WOLFSSL_BIO bio,
WOLFSSL_EVP_PKEY key,
const WOLFSSL_EVP_CIPHER *  cipher,
unsigned char *  passwd,
int  len,
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
bioWOLFSSL_BIO structure to get PEM buffer from.
keykey to convert to PEM format.
cipherEVP cipher structure.
passwdpassword.
lenlength of password.
cbpassword callback.
argoptional argument.

Example

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

WOLFSSL_API 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
pkcs12WC_PKCS12 structure to parse.
paswdpassword for decrypting PKCS12.
pkeystructure to hold private key decoded from PKCS12.
certstructure to hold certificate decoded from PKCS12.
stackoptional stack of extra certificates.

Example

WC_PKCS12* pkcs;
STACK_OF(X509) certs;
//bio loads in PKCS12 file
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()

WOLFSSL_API 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
spointer to WolfSSL struct which is created by SSL_new() function
typessl extension type which TLSEXT_STATUSTYPE_ocsp is only supported.

Example

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

◆ wolfSSL_use_certificate_chain_file()

WOLFSSL_API int wolfSSL_use_certificate_chain_file ( WOLFSSL ,
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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new()
filea 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()

WOLFSSL_API int wolfSSL_use_certificate_file ( WOLFSSL ,
const char *  ,
int   
)

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
ssla pointer to a WOLFSSL structure, created with wolfSSL_new().
filea pointer to the name of the file containing the certificate to be loaded into the wolfSSL SSL session, with format as specified by format.
formatthe 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()

WOLFSSL_API int wolfSSL_use_PrivateKey_file ( WOLFSSL ,
const char *  ,
int   
)

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.

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
ssla pointer to a WOLFSSL structure, created with wolfSSL_new().
filea 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.
formatthe 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

◆ wolfSSL_use_RSAPrivateKey_file()

WOLFSSL_API int wolfSSL_use_RSAPrivateKey_file ( WOLFSSL ,
const char *  ,
int   
)

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
ssla pointer to a WOLFSSL structure, created using wolfSSL_new()
filea 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()

WOLFSSL_API int wolfSSL_X509_get_serial_number ( WOLFSSL_X509 ,
unsigned char *  ,
int *   
)

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
inThe serial number buffer and should be at least 32 bytes long
inOutSzwill hold the actual length in bytes written to the in buffer.

Example

none
See also
SSL_get_peer_certificate