Returns
certificate information following an SSL handshake.
Format
#include <gskssl.h>
gsk_status gsk_attribute_get_cert_info (
gsk_handle soc_handle,
GSK_CERT_ID cert_id,
gsk_cert_data_elem ** cert_data,
int * elem_count)
Parameters
- soc_handle
- Specifies the connection handle returned by the gsk_secure_socket_open() routine.
- cert_id
- Specifies the certificate identifier.
- cert_data
- Returns the certificate data array. The gsk_free_cert_data() routine
should be called to release the array when the certificate information
is no longer needed. A NULL address will be returned if no certificate
information is available.
- elem_count
- Returns the number of elements in the array of gsk_cert_data_elem
structures.
Results
The function return value will be
0 (
GSK_OK) if no error is detected. Otherwise, it will be one
of the return codes listed in the
gskssl.h include file. These
are some possible errors:
- [GSK_ATTRIBUTE_INVALID_ID]
- The certificate identifier is not valid.
- [GSK_ERR_ASN]
- Unable to decode certificate.
- [GSK_INSUFFICIENT_STORAGE]
- Insufficient storage is available.
- [GSK_INVALID_HANDLE]
- The connection handle is not valid.
- [GSK_INVALID_STATE]
- The connection is not initialized.
Usage
The gsk_attribute_get_cert_info() routine
returns information about certificates used in an SSL handshake.
The connection must be in the initialized state. The certificate data
address will be NULL if there is no certificate information available.
These
certificate identifiers are supported:
- GSK_LOCAL_CERT_INFO
- Returns information about the local certificate.
- GSK_PARTNER_CERT_INFO
- Returns information about the partner certificate.
Each element of the certificate data array has
an element identifier. The element identifiers used for a particular
certificate depend upon the contents of the certificate. These element
identifiers are currently provided:
- CERT_BODY_BASE64
- Certificate body in Base64-encoded format
- CERT_BODY_DER
- Certificate body in binary ASN.1 DER-encoded format
- CERT_COMMON_NAME
- Subject common name (CN)
- CERT_COUNTRY
- Subject country (C)
- CERT_DN_DER
- Subject distinguished name in binary ASN.1 DER-encoded format
- CERT_DN_PRINTABLE
- Subject distinguished name as a printable character string
These
DN attribute names are recognized by the System SSL run time.
- C - Country
- CN - Common name
- DC - Domain component
- DNQUALIFIER - Distinguished name qualifier
- EMAIL - email address
- GENERATIONQUALIFIER - Generation qualifier
- GIVENNAME - Given name
- INITIALS - Initials
- L - Locality
- MAIL - RFC 822 style address
- NAME - Name
- O - Organization name
- OU - Organizational unit name
- PC - Postal code
- SERIALNUMBER - Serial number
- SN - Surname
- ST - State or province
- STREET - Street
- T - Title
- CERT_DNQUALIFIER
- Subject distinguished name qualifier (DNQUALIFIER)
- CERT_DOMAIN_COMPONENT
- Subject domain component (DC)
- CERT_EMAIL
- Subject email address (EMAIL)
- CERT_GENERATIONQUALIFIER
- Subject generation qualifier (GENERATIONQUALIFIER)
- CERT_GIVENNAME
- Subject given name (GIVENNAME)
- CERT_INITIALS
- Subject initials (INITIALS)
- CERT_ISSUER_COMMON_NAME
- Issuer common name (CN)
- CERT_ISSUER_COUNTRY
- Issuer country (C)
- CERT_ISSUER_DN_DER
- Issuer distinguished name in binary ASN.1 DER-encoded format
- CERT_ISSUER_DN_PRINTABLE
- Issuer distinguished name as a printable character string
These
DN attribute names are recognized by the System SSL run time.
- C - Country
- CN - Common name
- DC - Domain component
- DNQUALIFIER - Distinguished name qualifier
- EMAIL - email address
- GENERATIONQUALIFIER - Generation qualifier
- GIVENNAME - Given name
- INITIALS - Initials
- L - Locality
- MAIL - RFC 822 style address
- NAME - Name
- O - Organization name
- OU - Organizational unit name
- PC - Postal code
- SERIALNUMBER - Serial number
- SN - Surname
- ST - State or province
- STREET - Street
- T - Title
- CERT_ISSUER_DNQUALIFIER
- Issuer distinguished name qualifier (DNQUALIFIER)
- CERT_ISSUER_DOMAIN_COMPONENT
- Issuer domain component (DC)
- CERT_ISSUER_EMAIL
- Issuer email address (EMAIL)
- CERT_ISSUER_GENERATIONQUALIFIER
- Issuer generation qualifier (GENERATIONQUALIFIER)
- CERT_ISSUER_GIVENNAME
- Issuer given name (GIVENNAME)
- CERT_ISSUER_INITIALS
- Issuer initials (INITIALS)
- CERT_ISSUER_LOCALITY
- Issuer locality (L)
- CERT_ISSUER_MAIL
- Issuer RFC 822 style address (MAIL)
- CERT_ISSUER_NAME
- Issuer name (NAME)
- CERT_ISSUER_ORG
- Issuer organization (O)
- CERT_ISSUER_ORG_UNIT
- Issuer organizational unit (OU)
- CERT_ISSUER_POSTAL_CODE
- Issuer postal code (PC)
- CERT_ISSUER_SERIALNUMBER
- Issuer serial number (SERIALNUMBER)
- CERT_ISSUER_STATE_OR_PROVINCE
- Issuer state or province (ST)
- CERT_ISSUER_STREET
- Issuer street (STREET)
- CERT_ISSUER_SURNAME
- Issuer surname (SN)
- CERT_ISSUER_TITLE
- Issuer title (T)
- CERT_LOCALITY
- Subject locality (L)
- CERT_MAIL
- Subject RFC 822 style address (MAIL)
- CERT_NAME
- Subject name (NAME)
- CERT_ORG
- Subject organization (O)
- CERT_ORG_UNIT
- Subject organizational unit (OU)
- CERT_POSTAL_CODE
- Subject postal code (PC)
- CERT_SERIAL_NUMBER
- Certificate serial number
- CERT_SERIALNUMBER
- Subject serial number (SERIALNUMBER)
- CERT_STATE_OR_PROVINCE
- Subject state or province (ST)
- CERT_STREET
- Subject street (STREET)
- CERT_SURNAME
- Subject surname (SN)
- CERT_TITLE
- Subject title (T)
The CERT_BODY_DER, CERT_DN_DER, and CERT_ISSUER_DN_DER
elements are not null-terminated and the 'cert_data' field must be
used to get the element length. All of the other elements are null-terminated
character strings and the 'cert_data' field is the length of the string
excluding the end-of-string delimiter.