gsk_attribute_set_callback()--Set callback pointers to routines in the user
application
Syntax
#include <gskssl.h>
int gsk_attribute_set_callback(gsk_handle my_gsk_handle,
GSK_CALLBACK_ID callBackID,
void *callBackAreaPtr);
Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_attribute_set_callback() function is used to set
callback pointers to routines in the user application. These routines may be
used for special purposes by the application.
Parameters
my_gsk_handle (Input)
Indicates one of the following handles:
The handle for the secure session. (my_session_handle)
The handle for the SSL environment. (my_env_handle)
callBackID (Input)
Indicates one of the following operations:
GSK_ENVIRONMENT_CLOSE_CALLBACK (804) - This is the
callback to have a user routine be called when the last secure session is
closed that was created based on secure environment that already has been
closed.
GSK_CERT_VALIDATION_CALLBACK (805) This is the callback
that is required to do additional certificate validation
callBackAreaPtr (Input)
Address of a callback routine or address of a structure containing pointers
to callback routines appropriate to the callBackID. The following
indicate what should be pointed to by the callBackAreaPtr
based on the value of the callBackID.
GSK_ENVIRONMENT_CLOSE_CALLBACK - The
callBackAreaPtr should be set to the address of a function with
prototype pGSK_ENVIRONMENT_CLOSE_CALLBACK. pGSK_ENVIRONMENT_CLOSE_CALLBACK is
defined as:
validationCallBack.validation_callback should be set to
a value of type pgsk_cert_validation_callback. This is the pgsk_cert_validation_callback
typedef:
typedef int (*pgsk_cert_validation_callback)(const unsigned char * my_CertificateChain,
int my_validation_status)
Do not use pgsk_cert_validation_callback as a variable type when you create your
prototype and function though. The following prototype should be used in
the code for the function whose address will be assigned to
validationCallBack.validation_callback:
int foo(const unsigned char * my_CertificateChain,
int my_validation_status);
The return value from this function will be one of following:
GSK_OK (0) - Application accepts the certificate, and SSL will continue the
handshake with this value.
GSK_ERROR_CERT_VALIDATION (8) - Application does not accept the
certificate, and SSL handshake will terminate immediately with this value. If
callback routine return other than GSK_OK, SSL will consider it as
GSK_ERROR_CERT_VALIDATION and terminate the handshake.
Parameters
my_CertificateChain (Input)
A pointer to a copy of buffer which contains the data of certificate
chain.
my_validation_status (Input)
Results from SSL certificate validation:
GSK_VALIDATION_SUCCESSFUL (0) - Validation is successful.
GSK_OS400_ERROR_NOT_TRUSTED_ROOT (6000) - The certificate is not signed by
a trusted certificate authority
GSK_KEYFILE_CERT_EXPIRED (107) - The validity time period of the
certificate has expired.
validationCallBack.validateRequired - This is the flag to inform
SSL when to call the certificate validation callback. The following values can
be used :
GSK_NO_VALIDATION (900) - User application would like SSL to validate and
authenticate the certificate first before calling the certificate validation
callback. However, if validation fails because the certificate is expired or
does not have a trusted root the certificate validation callback will still be
called.
GSK_VALIDATION_REQUIRED (901) - User application would like SSL to validate
and authenticate the certificate first before calling the certificate
validation callback.
NOTE: If Authentication PassThru is set, and the application set the
certificate callback to GSK_VALIDATION_REQUIRED, SSL will reject the call with
an error code GSK_CONFLICTING_VALIDATION_SETTING. If a certificate validation
callback has been set to GSK_VALIDATION_REQUIRED, and application set
authentication to PassThru, SSL will also reject the call with an error code
GSK_CONFLICTING_VALIDATION_SETTING.
validationCallBack.certificateNeeded - Provides certificate chain
flag which informs SSL what certificate chain should be passed to the
certificate validation callback. The following values can be used:
GSK_COMPLETED_CERTIFICATE_CHAIN (951) - To pass the callback routine the
complete certificate chain built by SSL during certificate validation and
authentication.
GSK_CERTIFICATE_CHAIN_SENT_VIA_SSL (950) - To pass the callback routine the
complete certificate chain built by SSL during certificate validation and
authentication.
GSK_END_ENTITY_CERTIFICATE (952) - To pass the callback routine the EE
certificate only. Note: This value will be ignored when the user set
certificate validation flag to GSK_NO_VALIDATION. In other words, SSL will set
it to GSK_CERTIFICATE_CHAIN_SENT_VIA_SSL.
Authorities
No authorization is required.
Return Value
gsk_attribute_set_callback() returns an integer. Possible
values are:
[GSK_OK]
gsk_attribute_set_callback() was successful.
[GSK_ATTRIBUTE_INVALID_ID]
The callBackID specified was not valid.
[GSK_ATTRIBUTE_INVALID_ENUMERATION]
An enumeration referenced by the callBackAreaPtr was
not valid.
[GSK_CONFLICTING_VALIDATION_SETTING]
The value for the validationCallBack.validateRequired
field for GSK_CERT_VALIDATION_CALLBACK conflicts with
the setting for either GSK_SERVER_AUTH_TYPE or GSK_CLIENT_AUTH_TYPE
set by gsk_attribute_set_enum().
[GSK_INVALID_STATE]
The callBackID cannot be set after a
gsk_environment_init() has been issued.
[GSK_INVALID_HANDLE]
The handle specified was not valid.
[GSK_ERROR_UNSUPPORTED]
The callBackID is currently not supported.
[GSK_ERROR_IO]
An error occurred in SSL processing, check the errno value.
Error Conditions
When the gsk_attribute_set_callback() API fails with return
code [GSK_ERROR_IO], errno can be set to:
The following GSK_CALLBACK_ID values may be set in the SSL
environment after gsk_environment_open() and before
gsk_environment_init(). They are used as defaults for subsequent
secure sessions:
GSK_ENVIRONMENT_CLOSE_CALLBACK
GSK_CERT_VALIDATION_CALLBACK
The following GSK_CALLBACK_ID values currently are not supported
in the IBM® i implementation:
GSK_IO_CALLBACK
GSK_SID_CACHE_CALLBACK
GSK_CLIENT_CERT_CALLBACK
GSK_PKCS11_CALLBACK
Related Information
gsk_attribute_set_enum()--Set
enumerated information for a secure session or an SSL environment.
gsk_attribute_set_buffer()--Set
character string information for a secure session or an SSL environment.