wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.11  Certificate Manager


The functions in this section are part of the wolfSSL Certificate Manager.  The Certificate Manager allows applications to load and verify certificates external to the SSL/TLS connection.






CyaSSL_CertManagerDisableCRL


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CertManagerDisableCRL(CYASSL_CERT_MANGER* cm);


Description:

Turns off Certificate Revocation List checking when verifying certificates with the Certificate Manager.  By default, CRL checking is off.  You can use this function to temporarily or permanently disable CRL checking with this Certificate Manager context that previously had CRL checking enabled.


Return Values:

If successful the call will return SSL_SUCCESS.


BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


Example:


int ret = 0;

CYASSL_CERT_MANAGER* cm;


...


ret = CyaSSL_CertManagerDisableCRL(cm);

if (ret != SSL_SUCCESS) {

// error disabling cert manager

}


...


See Also:

CyaSSL_CertManagerEnableCRL






CyaSSL_CertManagerEnableCRL


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CertManagerEnableCRL(CYASSL_CERT_MANGER* cm, int options);


Description:

Turns on Certificate Revocation List checking when verifying certificates with the Certificate Manager.  By default, CRL checking is off.  options include CYASSL_CRL_CHECKALL which performs CRL checking on each certificate in the chain versus the Leaf certificate only which is the default.


Return Values:

If successful the call will return SSL_SUCCESS.


NOT_COMPILED_IN will be returned if CyaSSL was not built with CRL enabled.


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


BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.


SSL_FAILURE will be returned if the CRL context cannot be initialized properly.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


options - options to use when enabling the Certification Manager, cm.


Example:


int ret = 0;

CYASSL_CERT_MANAGER* cm;

...


ret = CyaSSL_CertManagerEnableCRL(cm, 0);

if (ret != SSL_SUCCESS) {

// error enabling cert manager

}


...


See Also:

CyaSSL_CertManagerDisableCRL






CyaSSL_CertManagerFree


Synopsis:

#include <cyassl/ssl.h>


void CyaSSL_CertManagerFree(CYASSL_CERT_MANGER* cm);


Description:

Frees all resources associated with the Certificate Manager context.  Call this when you no longer need to use the Certificate Manager.


Return Values:

No return value is used.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


Example:


CYASSL_CERT_MANAGER* cm;

...


CyaSSL_CertManagerFree(cm);


See Also:

CyaSSL_CertManagerNew






CyaSSL_CertManagerLoadCA


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CertManagerLoadCA(CYASSL_CERT_MANGER* cm, const char* CAfile,

                                                             const  char* CApath);


Description:

Specifies the locations for CA certificate loading into the manager context.  The PEM certificate CAfile may contain several trusted CA certificates.  If CApath is not NULL it specifies a directory containing CA certificates in PEM format.


Return Values:

If successful the call will return SSL_SUCCESS.


SSL_BAD_FILETYPE will be returned if the file is the wrong format.


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.


ASN_INPUT_E will be returned if Base16 decoding fails on the file.


BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


CAfile - pointer to the name of the file containing CA certificates to load.


CApath - pointer to the name of a directory path containing CA certificates to load.  The NULL pointer may be used if no certificate directory is desired.


Example:


int ret = 0;

CYASSL_CERT_MANAGER* cm;

...


ret = CyaSSL_CertManagerLoadCA(cm, “path/to/cert-file.pem”, 0);

if (ret != SSL_SUCCESS) {

// error loading CA certs into cert manager

}


See Also:

CyaSSL_CertManagerVerify






CyaSSL_CertManagerNew


Synopsis:

#include <cyassl/ssl.h>


CYASSL_CERT_MANAGER* CyaSSL_CertManagerNew(void);


Description:

Allocates and initializes a new Certificate Manager context.  This context be used independent of SSL needs.  It may be used to load certificates, verify certificates, and check the revocation status.


Return Values:

If successful the call will return a valid CYASSL_CERT_MANAGER pointer.


NULL will be returned for an error state.


Parameters:


There are no parameters for this function.


Example:


CYASSL_CERT_MANAGER* cm;


cm = CyaSSL_CertManagerNew();

if (cm == NULL) {

// error creating new cert manager

}


See Also:

CyaSSL_CertManagerFree






CyaSSL_CertManagerVerify


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CertManagerVerify(CYASSL_CERT_MANGER* cm, const char* cert,

        int format);


Description:

Specifies the certificate to verify with the Certificate Manager context.  The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.


Return Values:

If successful the call will return SSL_SUCCESS.


ASN_SIG_CONFIRM_E will be returned if the signature could not be verified.


ASN_SIG_OID_E will be returned if the signature type is not supported.


CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked.


CRL_MISSING is an error that is returned if a current issuer CRL is not available.


ASN_BEFORE_DATE_E will be returned if the current date is before the before date.


ASN_AFTER_DATE_E will be returned if the current date is after the after date.


SSL_BAD_FILETYPE will be returned if the file is the wrong format.


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.


ASN_INPUT_E will be returned if Base16 decoding fails on the file.


BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


cert - pointer to the name of the file containing the certificates to verify.


format - format of the certificate to verify - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.


Example:


int ret = 0;

CYASSL_CERT_MANAGER* cm;

...


ret = CyaSSL_CertManagerVerify(cm, “path/to/cert-file.pem”, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error verifying certificate

}


See Also:

CyaSSL_CertManagerLoadCA

CyaSSL_CertManagerVerifyBuffer






CyaSSL_CertManagerVerifyBuffer


Synopsis:

#include <cyassl/ssl.h>


int CyaSSL_CertManagerVerify(CYASSL_CERT_MANGER* cm,

        const unsigned char* buff, int sz, int format);


Description:

Specifies the certificate buffer to verify with the Certificate Manager context.  The format can be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1.


Return Values:

If successful the call will return SSL_SUCCESS.


ASN_SIG_CONFIRM_E will be returned if the signature could not be verified.


ASN_SIG_OID_E will be returned if the signature type is not supported.


CRL_CERT_REVOKED is an error that is returned if this certificate has been revoked.


CRL_MISSING is an error that is returned if a current issuer CRL is not available.


ASN_BEFORE_DATE_E will be returned if the current date is before the before date.


ASN_AFTER_DATE_E will be returned if the current date is after the after date.


SSL_BAD_FILETYPE will be returned if the file is the wrong format.


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.


ASN_INPUT_E will be returned if Base16 decoding fails on the file.


BAD_FUNC_ARG is the error that will be returned if a pointer is not provided.


Parameters:


cm - a pointer to a CYASSL_CERT_MANAGER structure, created using CyaSSL_CertManagerNew().


buff - buffer containing the certificates to verify.


sz - size of the buffer, buf.


format - format of the certificate to verify, located in buf - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.


Example:


int ret = 0;

int sz = 0;

CYASSL_CERT_MANAGER* cm;

byte certBuff[...];

...


ret = CyaSSL_CertManagerVerifyBuffer(cm, certBuff, sz, SSL_FILETYPE_PEM);

if (ret != SSL_SUCCESS) {

// error verifying certificate

}


See Also:

CyaSSL_CertManagerLoadCA

CyaSSL_CertManagerVerify




 

Questions? +1 (425) 245-8247