gsk_attribute_get_cert_info()--Get information about a local or partner certificate

Syntax

 #include <gskssl.h>

 int gsk_attribute_get_cert_info(gsk_handle my_gsk_handle,
                                 GSK_CERT_ID certID,
                                 const gsk_cert_data_elem **certDataElem,
                                 int *certDataElemCount);

  Service Program Name: QSYS/QSOSSLSR

  Default Public Authority: *USE

  Threadsafe: Yes

The gsk_attribute_get_cert_info() function is used to obtain specific information about either the server or client certificate for a secure session or an SSL environment.

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)

certID (Input)

Indicates one of the following:

GSK_LOCAL_CERT_INFO (701) - Retrieve certificate data information for the local certificate that may be sent to the remote connection. This can be retrieved using the SSL environment handle or the secure session handle.
GSK_PARTNER_CERT_INFO (700) - Retrieve certificate data information for the partner certificate that may have been received during the SSL handshake. This can only be retrieved using the secure session handle.

certDataElem (Output)

The address of a pointer to the certificate information returned from this function call. On output, certDataElem will contain the pointer to the information. The storage for this information was allocated by the system from user heap storage and will be freed by the gsk_secure_soc_close() API or the gsk_environment_close() API.

certDataElemCount (Output)

A pointer to an integer that will contain the number of certificate data elements returned from this function call.

Authorities

No authorization is required.

Return Value

gsk_attribute_get_cert_info() returns an integer. Possible values are:

[GSK_OK]

gsk_attribute_get_cert_info() was successful.

[GSK_ATTRIBUTE_INVALID_ID]

The specified certID was not valid.

[GSK_INVALID_HANDLE]

The handle passed in to this function was not valid.

[GSK_INVALID_STATE]

One of the following occurred:

A SSL environment handle was specified with a certID of GSK_LOCAL_CERT_INFO before a gsk_environment_init() has been issued.
A secure session handle was specified before a gsk_secure_soc_init() has been issued.

[GSK_IBMI_ERROR_INVALID_POINTER]

The certDataElem or certDataElemCount pointer is not valid.

[GSK_INSUFFICIENT_STORAGE]

Not able to allocate storage for the requested operation.

[GSK_ERROR_IO]

An error occurred in SSL processing, check the errno value.

Error Conditions

When the gsk_attribute_get_cert_info() 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

After gsk_attribute_get_cert_info() returns with a GSK_OK return value, certDataElem points to an array of structures of type gsk_cert_data_elem. The following structure is the gsk_cert_data_elem structure:
```
typedef struct gsk_cert_data_elem_t
{
  GSK_CERT_DATA_ID cert_data_id;
  char *cert_data_p;
  int cert_data_l;

} gsk_cert_data_elem;
```
Each element consists of the following fields:
- cert_data_id is the identifier for each element of the certificate. The following are the valid identifiers:
  - CERT_BODY_DER (600)
  - CERT_BODY_BASE64 (601)
  - CERT_SERIAL_NUMBER (602)
  - CERT_COMMON_NAME (610)
  - CERT_LOCALITY (611)
  - CERT_STATE_OR_PROVINCE (612)
  - CERT_COUNTRY (613)
  - CERT_ORG (614)
  - CERT_ORG_UNIT (615)
  - CERT_DN_PRINTABLE (616)
  - CERT_DN_DER (617)
  - CERT_POSTAL_CODE (618)
  - CERT_EMAIL (619)
  - CERT_ISSUER_COMMON_NAME (650)
  - CERT_ISSUER_LOCALITY (651)
  - CERT_ISSUER_STATE_OR_PROVINCE (652)
  - CERT_ISSUER_COUNTRY (653)
  - CERT_ISSUER_ORG (654)
  - CERT_ISSUER_ORG_UNIT (655)
  - CERT_ISSUER_DN_PRINTABLE (656)
  - CERT_ISSUER_DN_DER (657)
  - CERT_ISSUER_POSTAL_CODE (658)
  - CERT_ISSUER_EMAIL (659)
  - CERT_VERSION (660)
  - CERT_SIGNATURE_ALGORITHM (661)
  - CERT_VALID_FROM (662)
  - CERT_VALID_TO (663)
  - CERT_PUBLIC_KEY_ALGORITHM (664)
  - CERT_PUBLIC_KEY (665)
  - CERT_PUBLIC_KEY_SIZE (666)
  - CERT_FINGERPRINT_ALGORITHM (667)
  - CERT_FINGERPRINT (668)
  - CERT_ISSUER_UNIQUEID (669)
  - CERT_SUBJECT_UNIQUEID (670)
  - CERT_KEY_USAGE (671)
  - CERT_SUBJECT_ALTERNATIVE_NAME_RFC822NAME (672)
  - CERT_SUBJECT_ALTERNATIVE_NAME_DNSNAME (673)
  - CERT_SUBJECT_ALTERNATIVE_NAME_DIRECTORYNAME (674)
  - CERT_SUBJECT_ALTERNATIVE_NAME_URI (675)
  - CERT_SUBJECT_ALTERNATIVE_NAME_IPADDRESS (676)
  - CERT_CERTIFICATE_POLICY_POLICYIDENTIFIER (677)
  - CERT_BASIC_CONSTRAINTS_CA (678)
  - CERT_BASIC_CONSTRAINTS_PATH_LENGTH_CONSTRAINT (679)
  - CERT_CRL_DISTRIBUTION_POINTS_DISTRIBUTIONPOINTNAME (680)
  - CERT_VALID_FROM_EX (681)
  - CERT_VALID_TO_EX (682)
  - CERT_FINGERPRINT_SHA1 (683)
  - CERT_FINGERPRINT_SHA256 (684)
  - CERT_EXTENDEDKEYUSAGE_IDENTIFIER (685)
- cert_data_p points to the specific certificate data.
- cert_data_l contains the length of the data element.
Many fields are character strings and are terminated with a trailing null. The length does not include the null.
Other fields (CERT_BODY_DER, CERT_DN_DER, and so on) may have imbedded nulls and therefore must use the integer length for processing.
Not all certificates contain all fields, so the number of fields returned depends on the certificate being processed. This open-ended approach means new fields can be added from time to time without disrupting existing usage.
All certificate data is returned in ASCII CCSID 850.
You can reference the certDataElem pointers as long as the handle for the secure session or SSL environment is open.
Retrieving GSK_LOCAL_CERT_INFO on a SSL environment handle will always return the first certificate when multiple certificates are configured. To determine which local certificate was used for a secure session, GSK_LOCAL_CERT_INFO must be called on the secure session handle.

There are two ways to configure multiple certificates for a secure environment:
- When GSK_KEYRING_LABEL_EX contains multiple certificates.
- When GSK_IBMI_APPLICATION_ID is set and the configured application ID description has multiple certificates assigned.

Related Information

gsk_attribute_get_buffer()--Get character information about a secure session or a SSL environment
gsk_attribute_get_enum()--Get enumerated information about a secure session or an SSL environment.
gsk_attribute_get_numeric_value()--Get numeric information about a secure session or an SSL environment
gsk_environment_close()--Close the SSL environment
gsk_environment_init()--Initialize an SSL environment
gsk_environment_open()--Get a handle for an SSL environment
gsk_secure_soc_close()--Close a secure session
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: V5R1

Top | UNIX-Type APIs | APIs by category