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 secure 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.
GSK_CIPHER_SESSION_RESET (807) - This is the callback to allow the application to detect when a renegotiation handshake happened over an already secure session.

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:
```
typedef void ( *pGSK_ENVIRONMENT_CLOSE_CALLBACK) (gsk_handle my_env_handle); 
```
GSK_CERT_VALIDATION_CALLBACK - The callBackAreaPtr must point to a validationCallBack structure. That structure is defined as:
```
typedef struct validationCallBack_struct
{
   pgsk_cert_validation_callback validation_callback;
   VALIDATE_REQUIRED validateRequired;
   CERT_NEEDED certificateNeeded;
} validationCallBack;
```
- 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 TLS will continue the handshake with this value.
  - GSK_ERROR_CERT_VALIDATION (8) - Application does not accept the certificate, and TLS handshake will terminate immediately with this value. If callback routine return other than GSK_OK, TLS 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 TLS 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 TLS when to call the certificate validation callback. The following values can be used :
  - GSK_NO_VALIDATION (900) - User application would like TLS 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 TLS 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, TLS 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, TLS will also reject the call with an error code GSK_CONFLICTING_VALIDATION_SETTING.
- validationCallBack.certificateNeeded - Provides certificate chain flag which informs TLS 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 TLS during certificate validation and authentication.
  - GSK_CERTIFICATE_CHAIN_SENT_VIA_SSL (950) - To pass the callback routine the complete certificate chain built by TLS 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, TLS will set it to GSK_CERTIFICATE_CHAIN_SENT_VIA_SSL.

GSK_CIPHER_SESSION_RESET - The callBackAreaPtr should be set to the address of a function with prototype pGSK_CIPHER_SESSION_RESET_CALLBACK. pGSK_CIPHER_SESSION_RESET_CALLBACK is defined as:
```
typedef void ( *pGSK_CIPHER_SESSION_RESET_CALLBACK) (gsk_handle my_soc_handle); 
```

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 TLS 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:

[EINTR]: Interrupted function call.
[EDEADLK]: Resource deadlock avoided.
[ETERM]: Operation terminated.

If an errno is returned that is not in this list, look in Errno Values for UNIX^®-Type Functions for a description of the errno.

Usage Notes

The following GSK_CALLBACK_ID values may be set in the secure 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
- GSK_CIPHER_SESSION_RESET
The following GSK_CALLBACK_ID values may be set in the secure session after gsk_secure_soc_open() and before gsk_secure_soc_init(). They are used as defaults for subsequent secure sessions:
- GSK_CIPHER_SESSION_RESET
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 environment.
gsk_attribute_set_buffer()--Set character string information for a secure session or environment.
gsk_attribute_set_numeric_value()--Set numeric information for a secure session or environment
gsk_environment_init()--Initialize a secure environment
gsk_environment_open()--Get a handle for a secure environment
gsk_secure_soc_init()--Negotiate a secure session
gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session
gsk_secure_soc_open()--Get a handle for a secure session
gsk_strerror()--Retrieve GSK runtime error message

API introduced: V5R3

[ Back to top | UNIX-Type APIs | APIs by category ]