	RSA BSAFE SSL-C	Security protocol components for C
		Search

Certificate Store Functions

This section details the routines that can be used to manipulate the certificate store. The contents of the certificate store are investigated when performing peer certificate verification.

Functions
void	SSL_set_client_CA_list (SSL ssl, STACK sk)
	Sets the list of acceptable Certification Authorities (CAs) against the SSL connection reference for the server side of the connection. More...
void	SSL_CTX_set_client_CA_list (SSL_CTX ctx, STACK sk)
	Sets the list of acceptable Certification Authorities (CAs) against the SSL_CTX for the server side of the connection. More...
STACK*	SSL_get_client_CA_list (SSL *ssl)
	Returns the list of acceptable Certification Authorities (CAs) that the SSL on the server side passes to the client if a client certificate is requested. More...
int	SSL_add_client_CA (SSL ssl, SSLCERT x509)
	Adds a certificate to the list of acceptable Certification Authorities (CAs). More...
int	SSL_CTX_add_client_CA (SSL_CTX ctx, SSLCERT x509)
	Adds a certificate to the list of acceptable Certification Authorities (CAs). More...
int	SSLCERT_STORE_get_by_subject (SSLCERT_STORE_CTX csctx, int type, SSLCERT_NAME cn, void *ret)
	Examines the lists of certificates held by the SSLCERT_STORE_CTX for an object having the specified type and a subject equal to the specified name. More...
int	SSLCERT_STORE_get_by_SKI (SSLCERT_STORE_CTX csctx, int type, R_ITEM ck, void *ret)
	Examines the lists of certificates held by the SSLCERT_STORE_CTX for an object having the specified type and a Subject Key Identifier (SKI) key id equal to the specified key id. More...
int	SSLCERT_STORE_CTX_set_ex_data (SSLCERT_STORE_CTX cctx, int idx, char data)
	Sets the external data attached to the SSLCERT_STORE_CTX structure ctx. More...
char*	SSLCERT_STORE_CTX_get_ex_data (SSLCERT_STORE_CTX *cctx, int idx)
	Returns the external data attached to the structure. More...
int	SSLCERT_STORE_CTX_get_error (SSLCERT_STORE_CTX *cctx)
	Returns the current verification error for the SSLCERT_STORE_CTX ctx. More...
void	SSLCERT_STORE_CTX_set_error (SSLCERT_STORE_CTX *cctx, int s)
	Sets an error code in the SSLCERT_STORE_CTX structure typically during a callback used for verification of a single certificate. More...
int	SSLCERT_STORE_CTX_get_error_depth (SSLCERT_STORE_CTX *cctx)
	Returns the depth in the certificate chain where the verification error occurred. More...
void*	SSLCERT_STORE_CTX_get_current_cert (SSLCERT_STORE_CTX *cctx)
	Returns the certificate currently being verified. More...

Function Documentation

int SSL_add_client_CA ( SSL * ssl,

SSLCERT * x509

) ;

Adds a certificate to the list of acceptable Certification Authorities (CAs). Certificates signed by these CAs are deemed acceptable by the server side of the SSL protocol.
Parameters:

ssl [In, Out] The SSL connection reference that controls the CA list.

x509 [In] A reference to the X.509 certificate that is added to the list of CAs.

Returns:
1 indicates success.
0 indicates error.

int SSL_CTX_add_client_CA ( SSL_CTX * ctx,

SSLCERT * x509

) ;

Adds a certificate to the list of acceptable Certification Authorities (CAs). Certificates signed by these CAs are deemed acceptable by the server side of the SSL protocol. The certificates are sent to the client when the server makes a request for a client certificate.
Parameters:

ctx [In, Out] The SSL_CTX reference that controls the CA list.

x509 [In] A reference to the X.509 certificate that is added to the list of CAs.

Returns:
1 indicates success.
0 indicates error.

void SSL_CTX_set_client_CA_list ( SSL_CTX * ctx,

STACK * list

) ;

Sets the list of acceptable Certification Authorities (CAs) against the SSL_CTX for the server side of the connection. Certificates returned by the client side signed by these CAs are deemed acceptable by the server. The server sends a client CA list when requesting a client certificate. The client CA list set against the SSL_CTX becomes the default client CA list for all SSL structures made from the SSL_CTX.
Parameters:

ctx [In, Out] The SSL_CTX reference where the CA list is stored.

list [In] A list of acceptable CAs in the form of a stack of SSLCERT_NAME structures.

This function is applicable for SSLv3 and TLSv1 only.
See also:
SSL_set_client_CA_list().

STACK* SSL_get_client_CA_list ( SSL * ssl ) ;

Returns the list of acceptable Certification Authorities (CAs) that the SSL on the server side passes to the client if a client certificate is requested. The client side may also return a CA list which is the list passed by the server to the client during a client certificate request.
Parameters:

ssl [In] The SSL connection reference where the CA list is stored.

Returns:
A STACK reference containing the list of available CAs.
NULL indicates no CA list.

This function is only for use with SSLv3 and TLSv1.

The server returns the SSL_CTX client CA list if the SSL has no client CA list specifically associated with it.
See also:
SSL_set_client_CA_list(), SSL_get_client_CA_list_count() and SSL_get_client_CA_list_item().

void SSL_set_client_CA_list ( SSL * s,

STACK * list

) ;

Sets the list of acceptable Certification Authorities (CAs) against the SSL connection reference for the server side of the connection. Certificates returned by the client side signed by these CAs are deemed acceptable by the SSL protocol. The server sends a client CA list when requesting a client certificate.
Parameters:

s [In, Out] The SSL connection reference.

list [In] A list of acceptable CAs given a stack of SSLCERT_NAME structures.

This function is applicable for SSLv3 and TLSv1 only.
See also:
SSL_get_client_CA_list() and SSL_CTX_set_client_CA_list().

void* SSLCERT_STORE_CTX_get_current_cert ( SSLCERT_STORE_CTX * ctx ) ;

Returns the certificate currently being verified. Normally used in certificate callback verification routines.
Parameters:

ctx [In] The SSLCERT_STORE_CTX reference to the certificate store being used in the verification.

Returns:
An SSLCERT reference to the current X.509 certificate being verified.
NULL indicates error.

int SSLCERT_STORE_CTX_get_error ( SSLCERT_STORE_CTX * ctx ) ;

Returns the current verification error for the SSLCERT_STORE_CTX ctx.
Parameters:

ctx [In] The SSLCERT_STORE_CTX reference where the certificate verification has been attempted.

Returns:
The result of the X.509 certificate verification.
X509_V_OK indicates success.
See Certificate Verification States for valid values.
See also:
SSLCERT_STORE_CTX_set_error() and SSL_CTX_set_verify_cb().

int SSLCERT_STORE_CTX_get_error_depth ( SSLCERT_STORE_CTX * ctx ) ;

Returns the depth in the certificate chain where the verification error occurred.
Parameters:

ctx [In] The SSLCERT_STORE_CTX reference to the certificate store where the verification was being attempted.

Returns:
The depth in the certificate chain where the error occurred.

The certificate from the peer is at depth zero.

char* SSLCERT_STORE_CTX_get_ex_data ( SSLCERT_STORE_CTX * ctx,

int index

) ;

Returns the external data attached to the structure.
Parameters:

ctx [In] The SSLCERT_STORE_CTX reference where the extra data is stored.

index [In] The index of the extra data to retrieve.

Returns:
A reference to the extra data stored at index index.
NULL indicates error.
See also:
SSLCERT_STORE_CTX_set_ex_data() and SSL_get_ex_data_SSLCERT_STORE_CTX_idx().

void SSLCERT_STORE_CTX_set_error ( SSLCERT_STORE_CTX * ctx,

int index

) ;

Sets an error code in the SSLCERT_STORE_CTX structure typically during a callback used for verification of a single certificate.
Parameters:

ctx [In, Out] The SSLCERT_STORE_CTX reference where the certificate verification has been attempted.

index [In] The result of the certificate verification.
See Certificate Verification States for valid values.

See also:
SSL_CTX_set_verify_cb() and SSLCERT_STORE_CTX_get_error().

int SSLCERT_STORE_CTX_set_ex_data ( SSLCERT_STORE_CTX * ctx,

int idx,

char * data

) ;

Sets the external data attached to the SSLCERT_STORE_CTX structure ctx.
Parameters:

ctx [In, Out] The SSLCERT_STORE_CTX reference.

idx [In] An index that is used to retrieve the extra data.

data [In] User-specified information that can be accessed from inside the certificate verification callback.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SSLCERT_STORE_CTX_get_ex_data() and SSL_get_ex_data_SSLCERT_STORE_CTX_idx().

int SSLCERT_STORE_get_by_SKI ( SSLCERT_STORE_CTX * cs,

int type,

R_ITEM * keyid,

void * ret

) ;

Examines the lists of certificates held by the SSLCERT_STORE_CTX for an object having the specified type and a Subject Key Identifier (SKI) key id equal to the specified key id. If an object is found, it is returned as the value of ret.
Parameters:

cs [In] The SSLCERT_STORE_CTX reference to the certificate store.

type [In] The type. One of:

#1 - X.509 certificate.
#2 - Certificate Revocation List (CRL).

keyid [In] The R_ITEM reference to the SKI key id of the desired certificate.

ret [In, Out] If successful, a reference to an object containing the certificate or the CRL.

Returns:
1 indicates an object was found.
0 indicates no object was found.
-1 indicates a lookup error.

int SSLCERT_STORE_get_by_subject ( SSLCERT_STORE_CTX * cs,

int type,

SSLCERT_NAME * name,

void * ret

) ;

Examines the lists of certificates held by the SSLCERT_STORE_CTX for an object having the specified type and a subject equal to the specified name. If an object is found, it is returned as the value of ret.
Parameters:

cs [In] The SSLCERT_STORE_CTX reference to the certificate store.

type [In] The type. One of:

#1 - X.509 certificate.
#2 - Certificate Revocation List (CRL).

name [In] The SSLCERT_NAME reference to the subject name of the desired certificate.

ret [In, Out] If successful, a reference to an object containing the certificate or the CRL.

Returns:
1 indicates an object was found.
0 indicates no object was found.
-1 indicates a lookup error.