Obtain information from the client certificate received over
a TCP/IP service that specifed client authentication.

EXTRACT CERTIFICATE
>>-EXTRACT CERTIFICATE(ptr-ref)--+-------------------+---------->
'-LENGTH(data-area)-'
>--+--------------------+--+-------------------------+---------->
'-SERIALNUM(ptr-ref)-' '-SERIALNUMLEN(data-area)-'
.-OWNER--.
>--+-------------------+--+--------+--+---------------------+--->
'-USERID(data-area)-' '-ISSUER-' '-COMMONNAME(ptr-ref)-'
>--+-------------------------+--+------------------+------------>
'-COMMONNAMLEN(data-area)-' '-COUNTRY(ptr-ref)-'
>--+-----------------------+--+----------------+---------------->
'-COUNTRYLEN(data-area)-' '-STATE(ptr-ref)-'
>--+---------------------+--+-------------------+--------------->
'-STATELEN(data-area)-' '-LOCALITY(ptr-ref)-'
>--+------------------------+--+-----------------------+-------->
'-LOCALITYLEN(data-area)-' '-ORGANIZATION(ptr-ref)-'
>--+-------------------------+--+------------------+------------>
'-ORGANIZATLEN(data-area)-' '-ORGUNIT(ptr-ref)-'
>--+-----------------------+-----------------------------------><
'-ORGUNITLEN(data-area)-'
Conditions: INVREQ, LENGERR
Description
EXTRACT CERTIFICATE allows the application
to obtain information from the X.509 certificate that was received from a
client during a Secure Sockets Layer (SSL) handshake over a TCPIPSERVICE that
specified SSL(CLIENTAUTH). The certificate contains fields that identify the
owner (or subject) of the certificate, and fields that identify the Certificate
Authority that issued the certificate. You can select the fields that you
require by specifying the OWNER or ISSUER option. You cannot retrieve both
OWNER and ISSUER fields with one command.
Options
- CERTIFICATE(ptr-ref)
- specifies
a pointer reference to be set to the address of the full binary certificate
received from the client. The pointer reference is valid until the next CICS® command
or the end of task.
- COMMONNAME(ptr-ref)
- specifies
a pointer reference to be set to the common name from the client certificate.
The pointer reference is valid until the next CICS command or the end of task.
- COMMONNAMLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the common name from
the client certificate.
- COUNTRY(ptr-ref)
- specifies
a pointer reference to be set to the address of the country from the client
certificate. The pointer reference is valid until the next CICS command or
the end of task.
- COUNTRYLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the country from the
client certificate.
- ISSUER
- indicates
that the values returned by this command refer to the Certificate Authority
that issued this certificate.
- LENGTH(data-area)
- specifies
a fullword binary data area to be set to the length of the body of the client
certificate.
- LOCALITY(ptr-ref)
- specifies
a pointer reference to be set to the address of the locality from the client
certificate. The pointer reference is valid until the next CICS command or
the end of task.
- LOCALITYLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the locality from the
client certificate.
- ORGANIZATION(ptr-ref)
- specifies
a pointer reference to be set to the address of the organization from the
client certificate. The pointer reference is valid until the next CICS command
or the end of task.
- ORGANIZATLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the organization from
the client certificate.
- ORGUNIT(ptr-ref)
- specifies
a pointer reference to be set to the address of the organization unit from
the client certificate. The pointer reference is valid until the next CICS
command or the end of task.
- ORGUNITLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the organization unit
from the client certificate.
- OWNER
- indicates
that the values returned by this command refer to the owner of the certificate.
- SERIALNUM(ptr-ref)
- specifies
a pointer reference to be set to the address of the serial numberof the certificate
assigned by the certificate issuer. The pointer reference is valid until the
next CICS command or the end of task.
- SERIALNUMLEN(data-area)
- specifies
a fullword binary data area to be set to the length of the serial number.
- STATE(ptr-ref)
- specifies
a pointer reference to be set to the address of the state or province from
the client certificate. The pointer reference is valid until the next CICS
command or the end of task.
- STATELEN(data-area)
- specifies
a fullword binary data area to be set to the length of the state or province
from the client certificate.
USERID(data-area) 
specifies
an 8-byte field to be set to the user ID connected with the client certificate.
Conditions
- INVREQ
- occurs
for the following conditions:
- the command is being issued in a non-CICS Web Interface application.
- the command is being issued for a non-HTTP request.
- if an error occurs retrieving the certificate data from CICS intermediate
storage.
- LENGERR
- the
string being extracted is longer than the length specified for one of the
options.