Get request

Use the Get request to obtain additional information about the AT-TLS connection.

Table 1. Get request structure
Identifier	Constant	Length	Format	Description
TTLSK_Host_Status	4000	1 byte	Binary	Validates the host name that is provided with the partner certificate. The host name must end with a null character. The TTLSQ_Offset field must be set to the value of the start of the host name that is in the buffer. The following values can be returned in the TTLSQ_Rcode field: 0 The host name has successfully validated against the partner certificate. 1 Partner certificate is not available. 2 Host name did not match the name in the partner certificate. 3 Host name validation failed with an unexpected gsk_validate_hostname value. 4 Host name validation failed with an unexpected gsk_decode_certificate value.
TTLSK_Certificate	4001	Unknown	Binary	Returns the partner certificate. The certificate length is not known until the secure connection is established. The value of the TTLSi_Cert_Len field in the SIOCTTLSCTL structure can be used to determine the certificate length when the secure connection is complete. The following values can be returned in TTLSQ_Rcode: 0 The request completed successfully.
TTLSK_TTLSRule_Name	4002	48 bytes, ending with a null character	EBCDIC	Returns the name of the TTLSRule field that is mapped to the connection. The following value can be returned in TTLSQ_Rcode: 0 The request completed successfully.
TTLSK_GroupAction_Name	4003	48 bytes, ending with a null character	EBCDIC	Returns the name of the TTLSGroupAction field that is mapped to the connection. The following value can be returned in TTLSQ_Rcode: 0 The request completed successfully.
TTLSK_EnvironmentAction_Name	4004	48 bytes, ending with a null character	EBCDIC	Returns the name of the TTLSEnvironmentAction field that is mapped to the connection. The following value can be returned in TTLSQ_Rcode: 0 The request completed successfully.
TTLSK_ConnectionAction_Name	4005	48 bytes, ending with a null character	EBCDIC	Returns the name of the TTLSConnectionAction field that is mapped to the connection. The following value can be returned in TTLSQ_Rcode: 0 The request completed successfully.

For example, assume that an application made a secure connection to a server. However, the application needs to verify that the certificate is from the server the application is connected to. The application has two known server host names, mvs.telnet.raleigh.ibm.com and mvs.prod.rtp.ibm.com. The application would use the following TTLSHeader structure, pointed to by the TTLSI_BufPtr pointer on the SIOCTTLSCTL ioctl request to validate the server's certificate against these host names:

Table 2. Example TTLSHeader structure
TTLSHeader
Field	Offset	Format	Value
TTLSHeaderIdent	0	EBCDIC	TTLSHDR
TTLSHdrRsvd1	8	Binary	00000000 00000000
TTLSHdr_BytesNeeded	16	Binary	00000000
TTLSHdr_SetCount	20	Binary	00000000
TTLSHdr_GetCount	24	Binary	00000002
TTLSHdrRsvd2	28	Binary	00000000 00000000 00000000 00000000
TTLSQuadruplet			Get Request buffer
TTLSQ_Key	48	Binary	00000FA0
TTLSQ_Offset	52	Binary	00000050
TTLSQ_Length	56	Binary	00000000
TTLSQ_Rcode	60	Binary	00000000
TTLSQuadruplet			Get Request buffer
TTLSQ_Key	64	Binary	00000FA0
TTLSQ_Offset	68	Binary	0000006B
TTLSQ_Length	72	Binary	00000000
TTLSQ_Rcode	76	Binary	00000000
			Buffer Data
Hostname	80	EBCDIC	mvs.telnet.raleigh.ibm.com
Null character	106	Binary	00
Hostname	107	EBCDIC	mvs.prod.rtp.ibm.com
Null Character	127	Binary	00

Assuming that the certificate listed mvs.prod.rtp.ibm.com as the hostname value, the following TTLSHeader structure would be returned to the application:

Table 3. Example returned TTLSHeader structure
TTLSHeader
Field	Offset	Format	Value
TTLSHeaderIdent	0	EBCDIC	TTLSHDR
TTLSHdrRsvd1	8	Binary	00000000 00000000
TTLSHdr_BytesNeeded	16	Binary	00000080
TTLSHdr_SetCount	20	Binary	00000000
TTLSHdr_GetCount	24	Binary	00000002
TTLSHdrRsvd2	28	Binary	00000000 00000000 00000000 00000000
TTLSQuadruplet			Get Request buffer
TTLSQ_Key	48	Binary	00000FA0
TTLSQ_Offset	52	Binary	00000050
TTLSQ_Length	56	Binary	00000000
TTLSQ_Rcode	60	Binary	00000001
TTLSQuadruplet			Get Request buffer
TTLSQ_Key	64	Binary	00000FA0
TTLSQ_Offset	68	Binary	0000006B
TTLSQ_Length	72	Binary	00000001
TTLSQ_Rcode	76	Binary	00000000
			Buffer Data
Hostname	80	EBCDIC	mvs.telnet.raleigh.ibm.com
Null character	106	Binary	00
Hostname	107	EBCDIC	mvs.prod.rtp.ibm.com
Null character	127	Binary	00