Every secure connection must have one end using the HandshakeRole Client, and the other end using the HandShakeRole Server or HandShakeRole ServerWithClientAuth.
In the SSL and TLS protocols, the client side sends a ClientHello handshake record and the server side responds with a ServerHello handshake record. If both sides send ClientHello records, the handshake fails. If both sides wait for a ClientHello, the handshake times out.
The role played in the handshake is independent of whether the application is used as the client, server, or peer. It is also independent of which application does the listen() and accept() and which does the connect(). The primary consideration for deciding which role an application should play is certificate management.
The partner application designated as HandshakeRole Client must have a key ring that contains the root certificates required to authenticate the server’s certificate. The client does not need access to the private keys of any certificate. Clients can share this key ring.
The partner application designated as HandshakeRole Client decides whether to present a user certificate when challenged. To present a user certificate, it must have a private key ring with that user certificate. It must have access to the private keys of the user certificate. The client key ring must also contain the root certificates required to authenticate the server’s certificate.
When the HandshakeRole parameter is set to ServerWithClientAuth, a certificate request is sent to the client during the handshake. The client can send its certificate to the server, which can then validate the certificate. The level of validation done by the server is controlled by the setting of the ClientAuthType parameter. The following chart summarizes the differences between the parameter settings:
| ClientAuthType | Client certificate required or optional | Certificate validation |
|---|---|---|
| PassThru | Optional | None |
| Full | Optional | Certificate is validated against keyring, if provided |
| Required | Required | Certificate is validated against keyring |
| SAFCheck | Required | Certificate is validated against keyring and must be associated with a user ID in the security product |
If the certificate fails validation, the secure connection does not initialize successfully. The default setting for ClientAuthType is Required. For applications that do not issue AT-TLS ioctl calls to obtain the certificate or user ID of the client, the Required setting ensures that any client that connects provides a valid client certificate. The ClientAuthType setting of PassThru should be used only for applications that will get the certificate from AT-TLS using the SIOCTTLSCTL ioctl call and implement their own security methods to validate the certificate. The ClientAuthType setting of Full can be used for applications that want to validate the client certificate if provided, but do not require a client certificate to establish a secure connection. The ClientAuthType setting of SAFCheck provides an additional level of security when using client authentication by requiring AT-TLS to derive a user ID associated with the certificate. An application can then get the user ID from AT-TLS using the SIOCTTLSCTL ioctl after the secure connection has been established. The user ID can be used to either verify the user ID presented by the client during the application's protocol flows or eliminate the need for a user ID to be sent by the client.