	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Certificate Verification Functions

This section describes the functions which customize the SSL protocol's certificate verification functionality.

Typedefs
typedef int R_CDECL	SSL_CTX_CERT_VERIFY_CB_T (SSLCERT_STORE_CTX store_ctx, char arg)
	The prototype for a user-defined verification routine. More...
typedef int R_CDECL	SSL_CTX_APP_VERIFY_CB_T (SSL ssl, SSLCERT certs, int num, char arg, long *verify_result)
	The prototype for a user-defined verification callback function. More...
Functions
void R_CDECL	SSL_CTX_set_verify_depth (SSL_CTX *ssl_ctx, int depth)
	Sets the verification depth for the SSL_CTX. More...
int R_CDECL	SSL_CTX_get_verify_depth (SSL_CTX *ssl_ctx)
	Returns the certificate verification depth and limits the number of certificates in a chain. More...
int R_CDECL	SSL_CTX_get_verify_mode (SSL_CTX *ctx)
	Returns the certificate verification mode for the SSL_CTX ctx. More...
void R_CDECL	SSL_CTX_set_verify_mode (SSL_CTX *ctx, int mode)
	Sets the mode for the verification of peer certificates. More...
void R_CDECL	SSL_CTX_set_app_verify_cb (SSL_CTX ctx, SSL_CTX_APP_VERIFY_CB_T cb, char *arg)
	Sets the application verification callback for the SSL_CTX ctx. More...
SSL_CTX_APP_VERIFY_CB_T* R_CDECL	SSL_CTX_get_app_verify_cb (SSL_CTX *ctx)
	Returns the application-supplied verification callback associated with the SSL_CTX. More...
char* R_CDECL	SSL_CTX_get_app_verify_cb_arg (SSL_CTX *ctx)
	Returns the address of the user-defined application verification callback argument for the SSL_CTX ctx. More...
int	SSL_get_verify_mode (SSL *ssl)
	Returns the certificate verification mode by directly accessing the SSL structure. More...
int	SSL_set_verify_mode (SSL *ssl, int mode)
	Sets the certificate verification mode value for the SSL structure by directly accessing the SSL structure. More...
int	SSL_get_verify_depth (SSL *ssl)
	Returns the verify depth value from the SSL structure by directly accessing this field in the SSL structure. More...
void	SSL_set_verify_depth (SSL *ssl, int depth)
	Sets the value of the verify depth in the SSL structure by directly accessing the structure. More...
void	SSL_set_verify_result (SSL *ssl, long verify)
	Sets the certificate verification result value for the SSL structure by directly accessing the `verify_result` field of the SSL structure. More...
long	SSL_get_verify_result (SSL *ssl)
	Returns the certificate verification result value from the SSL structure by directly accessing the `verify_result` field of the SSL structure. More...

Typedef Documentation

typedef int R_CDECL SSL_CTX_APP_VERIFY_CB_T(SSL *ssl, SSLCERT **certs, int num, char *arg, long *verify_result)

The prototype for a user-defined verification callback function.
Parameters:

ssl [In] An SSL reference.

certs [In] The array of certificate pointers.

num [In] The number of certificate pointers.

arg [In] A caller-defined pointer argument.

verify_result [Out] The result of the verification.
One of Certificate Verification States.

Returns:
1 indicates success.
0 indicates error.
See also:
SSL_CTX_set_app_verify_cb(), SSL_CTX_get_app_verify_cb() and SSL_CTX_get_app_verify_cb_arg().

typedef int R_CDECL SSL_CTX_CERT_VERIFY_CB_T(SSLCERT_STORE_CTX *store_ctx, char *arg)

The prototype for a user-defined verification routine. This callback has access to the full SSLCERT_STORE Application Programming Interface (API).
Parameters:

store_ctx [In] The SSLCERT_STORE_CTX reference where the peer certificate chain is stored.

arg [In] A caller-defined pointer argument.

See also:
SSL_CTX_set_cert_verify_cb().

Function Documentation

SSL_CTX_APP_VERIFY_CB_T* R_CDECL SSL_CTX_get_app_verify_cb ( SSL_CTX * ctx ) ;

Returns the application-supplied verification callback associated with the SSL_CTX.
Parameters:

ctx [In] The SSL_CTX reference from which to retrieve the default callback reference.

Returns:
The verification callback.
NULL indicates no callbacks have been set.
See also:
SSL_CTX_set_app_verify_cb().

char* R_CDECL SSL_CTX_get_app_verify_cb_arg ( SSL_CTX * ctx ) ;

Returns the address of the user-defined application verification callback argument for the SSL_CTX ctx. This argument is passed to the application verification callback by SSL_CTX_set_app_verify_cb().
Parameters:

ctx [In] The SSL_CTX reference from which to retrieve the default callback argument.

Returns:
The callback argument.
NULL indicates the argument is not set.
See also:
SSL_CTX_set_app_verify_cb() and SSL_CTX_get_app_verify_cb().

int R_CDECL SSL_CTX_get_verify_depth ( SSL_CTX * ctx ) ;

Returns the certificate verification depth and limits the number of certificates in a chain.
Parameters:

ctx [In] The SSL_CTX reference where the depth is set. Cannot be NULL.

Returns:
-1 indicates the depth was not set.
Otherwise indicates depth.

int R_CDECL SSL_CTX_get_verify_mode ( SSL_CTX * ctx ) ;

Returns the certificate verification mode for the SSL_CTX ctx.
Parameters:

ctx [In] The SSL_CTX reference from which to retrieve the default verify mode.

Returns:
The verification mode.
See Verification Modes for valid values.
See also:
SSL_CTX_set_verify_mode().

void R_CDECL SSL_CTX_set_app_verify_cb ( SSL_CTX * ctx,

SSL_CTX_APP_VERIFY_CB_T * cb,

char * arg

) ;

Sets the application verification callback for the SSL_CTX ctx.
Parameters:

ctx [In] The SSL_CTX reference against which to set the default callback.

cb [In] The verify callback.

arg [In] The callback data.

See also:
SSL_CTX_get_app_verify_cb().
Samples:
nbio_client.c, and simple.c.

void R_CDECL SSL_CTX_set_verify_depth ( SSL_CTX * ctx,

int depth

) ;

Sets the verification depth for the SSL_CTX. This function is used to determine the maximum length of the certificate's chain set from the peer.
Parameters:

ctx [In, Out] The SSL_CTX reference where the depth is to be set.
Cannot be NULL.

depth [In] The verification depth.

void R_CDECL SSL_CTX_set_verify_mode ( SSL_CTX * ctx,

int mode

) ;

Sets the mode for the verification of peer certificates. The verification mode applies to all SSL structures derived from the SSL_CTX passed to this function. See Verification Modes for valid values.
Parameters:

ctx [In] The SSL_CTX that holds the verification parameters.

mode [In] The new verification mode.

Samples:
nbio_client.c, and simple.c.

int SSL_get_verify_depth ( SSL * ssl ) ;

Returns the verify depth value from the SSL structure by directly accessing this field in the SSL structure. Verification depth is used to determine the maximum acceptable number of certificates in a chain during peer verification.
Parameters:

ssl [In] The SSL structure.

Returns:
-1 indicates depth was not set.
Other values indicate verify depth.

ssl is not NULL.

int SSL_get_verify_mode ( SSL * ssl ) ;

Returns the certificate verification mode by directly accessing the SSL structure.
Parameters:

ssl [In] The SSL connection reference from which to retrieve the verifying mode.

Returns:
The integer indicating the verify mode. See Verification Modes for a range of valid values.

This mode is only used by SSLv2 and SSLv3.
ssl is not NULL.
See also:
SSL_set_verify_mode().

long SSL_get_verify_result ( SSL * ssl ) ;

Returns the certificate verification result value from the SSL structure by directly accessing the verify_result field of the SSL structure. This result is set inside the certificate verification callback based on the success/reason for failure of the verification.
Parameters:

ssl [In] The SSL connection reference from which to retrieve the verify result.

Returns:
A long value indicates the result of the verification callback.
See Certificate Verification States for valid values.

ssl is not NULL.

void SSL_set_verify_depth ( SSL * ssl,

int depth

) ;

Sets the value of the verify depth in the SSL structure by directly accessing the structure. The verification depth determines the maximum number of certificates in a peer chain considered during verification.
Parameters:

ssl [In, Out] The SSL structure.

depth [In] The verification depth.

ssl is not NULL.

int SSL_set_verify_mode ( SSL * ssl,

int mode

) ;

Sets the certificate verification mode value for the SSL structure by directly accessing the SSL structure.
Parameters:

ssl [In, Out] The SSL structure.

mode [In] The verify mode. See Verification Modes for valid values.

ssl is not NULL.

void SSL_set_verify_result ( SSL * ssl,

long verify

) ;

Sets the certificate verification result value for the SSL structure by directly accessing the verify_result field of the SSL structure. This result is set inside the certificate verification callback based on the success/reason for failure of the verification.
Parameters:

ssl [In, Out] The SSL connection reference against which to set the verify result.

verify [In] The long value defining success or otherwise of the verification callback.
See Certificate Verification States for valid values.

The verification result is normally set as part of the SSL handshake processing when certificate verification is required.
See also:
SSL_get_verify_result().

Certificate Verification Functions

Typedefs

Functions

Typedef Documentation

Function Documentation