Obtain information from the client certificate received
over a TCP/IP service that specified 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
This command is threadsafe.
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.
If you attempt to extract a certificate
and there is no certificate to extract, low or zero values are returned
for the pointers.
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 number
of 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
- 16 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.
- 22 LENGERR
- The
string being extracted is longer than the length specified for one
of the options.