wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.12  OpenSSL Compatibility Layer


The functions in this section are part of wolfSSL’s OpenSSL Compatibility Layer.  These functions are only available when wolfSSL has been compiled with the OPENSSL_EXTRA define.






CyaSSL_X509_get_serial_number


Synopsis:

#include <cyassl/ssl.h>


int  CyaSSL_X509_get_serial_number(CYASSL_X509* x509, unsigned char* in,

         int* inOutSz);


Description:

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.


Return Values:

If successful the call will return SSL_SUCCESS.


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


See Also:

SSL_get_peer_certificate






CyaSSL_get_sessionID


Synopsis:

#include <cyassl/ssl.h>


const unsigned char* CyaSSL_get_sessionID(const CYASSL_SESSION* session);


Description:

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


Return Values:

The session ID.


See Also:

SSL_get_session()






CyaSSL_get_peer_chain


Synopsis:

#include <cyassl/ssl.h>


X509_CHAIN* CyaSSL_get_peer_chain(CYASSL* ssl);


Description:

Retrieves the peer’s certificate chain.  


Return Values:

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


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


See Also:

CyaSSL_get_chain_count

CyaSSL_get_chain_length

CyaSSL_get_chain_cert

CyaSSL_get_chain_cert_pem






CyaSSL_get_peer_count


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_get_chain_count(CYASSL_X509_CHAIN* chain);


Description:

Retrieves the peer’s certificate chain count.


Return Values:

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.


See Also:

CyaSSL_get_peer_chain

CyaSSL_get_chain_length

CyaSSL_get_chain_cert

CyaSSL_get_chain_cert_pem






CyaSSL_get_peer_length


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_get_chain_length(CYASSL_X509_CHAIN* chain, int idx);


Description:

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


Return Values:

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.


See Also:

CyaSSL_get_peer_chain

CyaSSL_get_chain_count

CyaSSL_get_chain_cert

CyaSSL_get_chain_cert_pem






CyaSSL_get_chain_cert


Synopsis:

#include <cyassl/ssl.h>


unsigned char* CyaSSL_get_chain_cert(CYASSL_X509_CHAIN* chain, int idx);


Description:

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


Return Values:

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.


See Also:

CyaSSL_get_peer_chain

CyaSSL_get_chain_count

CyaSSL_get_chain_length

CyaSSL_get_chain_cert_pem






CyaSSL_get_chain_cert_pem


Synopsis:

#include <cyassl/ssl.h>


unsigned char* CyaSSL_get_chain_cert_pem(CYASSL_X509_CHAIN* chain, int idx);


Description:

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


Return Values:

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.


See Also:

CyaSSL_get_peer_chain

CyaSSL_get_chain_count

CyaSSL_get_chain_length

CyaSSL_get_chain_cert






CyaSSL_PemCertToDer


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_PemCertToDer(const char* fileName, unsigned char* derBuffer, int derSz);


Description:

Loads the PEM certificate from fileName and converts it into DER format, placing the result into derBuffer which is of size derSz.  


Return Values:

If successful the call will return the number of bytes written to derBuffer.


SSL_BAD_FILE will be returned if the file doesn’t exist, can’t be read, or is corrupted.


MEMORY_E will be returned if an out of memory condition occurs.


SSL_NO_PEM_HEADER will be returned if the PEM certificate header can’t be found.


BUFFER_E will be returned if a chain buffer is bigger than the receiving buffer.


Parameters:


filename - pointer to the name of the PEM-formatted certificate for conversion.


derBuffer - the buffer for which the converted PEM certificate will be placed in DER format.


derSz - size of derBuffer.


Example:


int derSz;

byte derBuf[...];


derSz = CyaSSL_PemCertToDer(“./cert.pem”, derBuf, sizeof(derBuf));


See Also:

SSL_get_peer_certificate






CyaSSL_CTX_use_RSAPrivateKey_file


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CTX_use_RSAPrivateKey_file(CYASSL_CTX* ctx,const char* file,

                                                                              int format);


Description:

This function loads the private RSA key used in the SSL connection into the SSL context (CYASSL_CTX).  This function is only available when CyaSSL has been compiled with the OpenSSL compatibility layer enabled (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used CyaSSL_CTX_use_PrivateKey_file() function.


The file argument contains a pointer to the RSA private key file, in the format specified by format.


Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be returned.  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 CYASSL_CTX structure, created using CyaSSL_CTX_new()


file - a pointer to the name of the file containing the RSA private key to be loaded into the CyaSSL 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;

CYASSL_CTX* ctx;


...


ret = CyaSSL_CTX_use_RSAPrivateKey_file(ctx, “./server-key.pem”,

                                       SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error loading private key file

}


...


See Also:

CyaSSL_CTX_use_PrivateKey_buffer

CyaSSL_CTX_use_PrivateKey_file

CyaSSL_use_RSAPrivateKey_file

CyaSSL_use_PrivateKey_buffer

CyaSSL_use_PrivateKey_file






CyaSSL_use_certificate_file


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_use_certificate_file(CYASSL* ssl, const char* file, int format);


Description:

This function loads a certificate file into the SSL session (CYASSL 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.


Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be returned.  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 CYASSL structure, created with CyaSSL_new().


file - a pointer to the name of the file containing the certificate to be loaded into the CyaSSL 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;

CYASSL* ssl;


...


ret = CyaSSL_use_certificate_file(ssl, “./client-cert.pem”,

                                 SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error loading cert file

}


...


See Also:

CyaSSL_CTX_use_certificate_buffer

CyaSSL_CTX_use_certificate_file

CyaSSL_use_certificate_buffer






CyaSSL_use_PrivateKey_file


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_use_PrivateKey_file(CYASSL* ssl, const char* file, int format);


Description:

This function loads a private key file into the SSL session (CYASSL 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.


Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be returned.  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 CYASSL structure, created with CyaSSL_new().


file - a pointer to the name of the file containing the key file to be loaded into the CyaSSL 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;

CYASSL* ssl;


...


ret = CyaSSL_use_PrivateKey_file(ssl, “./server-key.pem”,

                                SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error loading key file

}


...


See Also:

CyaSSL_CTX_use_PrivateKey_buffer

CyaSSL_CTX_use_PrivateKey_file

CyaSSL_use_PrivateKey_buffer






CyaSSL_use_certificate_chain_file


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_use_certificate_chain_file(CYASSL* ssl, const char* file);


Description:

This function loads a chain of certificates into the SSL session (CYASSL 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.


Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be returned.  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 CYASSL structure, created using CyaSSL_new()


file - a pointer to the name of the file containing the chain of certificates to be loaded into the CyaSSL SSL session.  Certificates must be in PEM format.


Example:


int ret = 0;

CYASSL* ctx;


...


ret = CyaSSL_use_certificate_chain_file(ssl, “./cert-chain.pem”);

if (ret != SSL_SUCCESS) {

// error loading cert file

}


...


See Also:

CyaSSL_CTX_use_certificate_chain_file

CyaSSL_CTX_use_certificate_chain_buffer

CyaSSL_use_certificate_chain_buffer






CyaSSL_use_RSAPrivateKey_file


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_use_RSAPrivateKey_file(CYASSL* ssl,const char* file, int format);


Description:

This function loads the private RSA key used in the SSL connection into the SSL session (CYASSL structure).  This function is only available when CyaSSL has been compiled with the OpenSSL compatibility layer enabled (--enable-opensslExtra, #define OPENSSL_EXTRA), and is identical to the more-typically used CyaSSL_use_PrivateKey_file() function.


The file argument contains a pointer to the RSA private key file, in the format specified by format.


Return Values:

If successful the call will return SSL_SUCCESS, otherwise SSL_FAILURE will be returned.  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 CYASSL structure, created using CyaSSL_new()


file - a pointer to the name of the file containing the RSA private key to be loaded into the CyaSSL 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;

CYASSL* ssl;


...


ret = CyaSSL_use_RSAPrivateKey_file(ssl, “./server-key.pem”,

                                   SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error loading private key file

}


See Also:

CyaSSL_CTX_use_RSAPrivateKey_file

CyaSSL_CTX_use_PrivateKey_buffer

CyaSSL_CTX_use_PrivateKey_file

CyaSSL_use_PrivateKey_buffer

CyaSSL_use_PrivateKey_file




 

Questions? +1 (425) 245-8247