Developer

API Reference

ClientAuthentication WebOpts

Brew Release
Brew MP 1.0.2
See Also
Description

WEBOPT_SSL_CLIENT_CERTIFICATE: This WebOpt defines each individual certificate in the client public certificate chain. The first instance (index 0) of this multi-valued WebOpt is the client certificate in DER (ASN.1) format, Each subsequent certificate in the certificate chain, if provided, should certify the preceding certificate.
This WebOpt may be used in place of the more complicated structure requirements of WEBOPT_SSL_CLIENT_CERTIFICATES. Simply add one of these WebOpts for each certificate in the client certificate chain.
WEBOPT_SSL_CLIENT_CERTIFICATES: This webopt contains the client public certificate chain. Unlike the WEBOPT_SSL_CLIENT_CERTIFICATE, it uses a fairly complex structure to hold the entire certificate chain.
Except for the first 2 bytes which are required by IWebOpts to identify the length, the structure must match the SSL certificate message structure:
    opaque ASN.1Cert<1..2^24-1>;
    struct {
      ASN.1Cert certificate_list<0..2^24-1>;
    } Certificate

In other words, each cert must be pre-pended by three bytes giving its length. These cert structures are then concatenated into a sequence with each certificate certifying the one preceding it. The resulting sequence is prepended by the length of the sequence. This is finally pre-pended by the length of the bytes encoded so far as a two byte integer. The three byte integers are big endian and per the SSL spec. The two byte integer is the web opt var buffer formatting. Diagrammatically:
      The value X + Y + 2 * 3 + 3 encoded as a two byte native integer
      The value X + Y + 2 * 3 encoded as three bytes big endian
      X encoded as three bytes big endian
      Cert A of len X
      Y encoded as three bytes big endian
      Cert B of len Y
      
   where
      A is the client certificate
      X is the length of certificate A
      B is a certificate which certifies A
      Y is the length of certificate B

WEBOPT_SSL_CLIENT_CERT_RSA: Pointer to the IRSA interface initialized with the client private certificate information. It is used to perform the RSA signature operation asynchronously. The IRSA interface must implement specific functionality to access the client private key and to perform the signing operation. If the client certificate is on a WIM card, then the IRSA implementation must have the ability to access and perform needed functions on this card.
On receiving a client authentication request, and on not finding the relevant WebOpts, the ISSL_Negotiate() call fails with the error code SSL_RESULT_CLIENT_AUTH_ERR. When failed this way, the WEBOPT_SSL_CA_DN_LIST and associated WebOpts WEBOPT_SSL_CA_DN and WEBOPT_SSL_DN_CERT_TYPES are added to the ISSL interface.
To proceed further, the app needs to issue ISSL_Negotiate() again (or if using the NegotiateHandler, just resume the given AEECallback), after adding the WebOpts for the client certificate chain and the IRSA interface. As ISSL keeps a copy of these WebOpts by doing an AddRef, these interfaces are valid until the end of handshake or connection close.
The WEBOPT_SSL_CA_DN_LIST WebOpt contains the CA DN information as sent by the server in the SSL Certificate Request message. ISSL parses this message and provides the parsed information in the WEBOPT_SSL_DN_CERT_TYPES and WEBOPT_SSL_CA_DN WebOpts.
WEBOPT_SSL_DN_CERT_TYPES format: This WebOpt's value is a variable buffer where the 1st two bytes are the standard length of the array, followed by a byte array containing the types of certificates supported by the server. The array is sorted by the server's preference. Possible ClientCertificateType's:
   SSL_CERT_TYPE_RSA_SIGN        RSA certificate
   SSL_CERT_TYPE_DSS_SIGN        DSS certificate
   SSL_CERT_TYPE_RSA_FIXED_DH    RSA certificate with DH parameters
   SSL_CERT_TYPE_DSS_FIXED_DH    DSS certificate with DH parameters

WEBOPT_SSL_CA_DN format: This WebOpt's value is a Distinguished Name (DN) in X.509 (ASN.1) format. This WebOpt is multi-valued - one WebOpt for each DN.
WEBOPT_SSL_CA_DN_LIST format:
This WebOpt's value is a pointer to binary data. The first two bytes indicate the length of the rest of the data and encoded in little-endian format. The rest of the data is in the same format as CerficateRequest message (refer: TLS RFC 2246).
Structure of this message:
enum { 
   rsa_sign(1), 
   dss_sign(2), 
   rsa_fixed_dh(3), 
   dss_fixed_dh(4), 
   (255) 
} ClientCertificateType; 

opaque DistinguishedName<1..2^16-1>; 

struct { 
   ClientCertificateType certificate_types<1..2^8-1>; 
   DistinguishedName certificate_authorities<3..2^16-1>; 
} CertificateRequest; 

certificate_types: This field is a list of the types of certificates requested, sorted in order of the server's preference. See also SSL_CERT_TYPE_*
certificate_authorities: This is a list of the distinguished names of acceptable certificate authorities. These distinguished names may specify a desired distinguished name for a root CA or for a subordinate CA; thus, this message can be used both to describe known roots and a desired authorization space.

Parsing of WEBOPT_SSL_CA_DN_LIST:
To parse the CA DN list, first verify the total binary blob length (in Little Endian format) in the first two bytes.
The CerficateRequest message follows.
The first byte is the length of the enum types. rsa_sign must be one of the types given. Loop through the enum values and reach the end. Once ClientCertificateType is parsed this way, then the certificate_authorities should be parsed to get the DNs. The first two bytes after ClientCertificateType indicate the length of the rest of the binary blob (Big Endian order). Note that this length value may not be properly word aligned for the processor. It should NOT be accessed by directly casting a char * to an short *.
After this, the binary data contains DN encoded in the ASN.1 format and needs to be decoded in that way. Please refer X.509 specification regarding the DN format.
Example showing a sample WEBOPT_SSL_CA_DN_LIST value:
0xF5 0x01 -> 2 bytes - length of the following data in little-Endian byte order
0x02 -> 1 byte - length of the enums
0x01 -> 1 byte - rsa_sign
0x03 -> 1 byte - rsa_fixed_dh 

0x01 0xF0 -> 2 bytes - length of the following data

 etc
Definition
   N/A
Comment
None.
  • Follow