Setting up client-side SSL authentication for CWI

To set up your environment for client-side SSL environments, you will again need some knowledge of CWI and the CWI CICS APIs.
First, you need to set your server up for server authentication as described in Setting up server-side SSL authentication for CWI.
  1. Create a client certificate and sign it using the demo CA. Note that the generated keyfile should be renamed to have the same name as the certificate, with the characters _key appended, but retaining the file's original extension. For example, if the certificate and key files are clntcert.pem and clntkey.pem respectively, you should rename clntkey.pem to clntcert_key.pem.
  2. Either modify your existing TCPIPSERVICE or create a new one, and set SSL to Clientauth in the Security section.
  3. Set the value for the environment variable ES_DFLT_CERTIFICATE_NAME_CLIENT to the label of the client certificate that you wish to use as the default. For example, if your client certificate is called clntcert.pem, you would set the environment variable as follows:
    [ES-Environment]
    ES_DFLT_CERTIFICATE_NAME_CLIENT=clntcert
  4. Set the value for the environment variable ES_CERTIFICATES_LOCATION to be the location of your client certificates.
  5. Modify ESCERTPAS.CBL on the server machine to return the password for the server certificate's keyfile and the CA root file that contains the certificates(s) used to sign all client certificates that should be allowed to connect to the TCPIPSERVICE. For example:
    when function upper-case(lk-certificate-name) = 'SRVCERT'      *> Server certificate 	            
        move 'srvrootpwd'	to lk-passphrase-returned              *> Password for srvcert_key.pem 
        move ‘C:\my\path\CARootcert.pem’ to lk-CARoot-to-be-used   *> CA root used to sign client certificates
    ESCERTPAS.CBL can be found in $COBDIR
  6. If your client is a browser, convert your client certificate and private key into a suitable format and import it into the browser. For example, to convert a PEM certificate file and private key to PKCS#12:
    openssl pkcs12 -export -out clntcert.pfx -inkey clntcert_key.pem -in clntcert.pem
  7. If your client is a CICS program then modify ESCERTPAS.CBL on the client machine to return the passphrase for the client key file and the fully-qualified CA Root certificate file (containing the certificate used to sign the server certificate). For example:
    when function upper-case(lk-certificate-name) = 'CLNTCERT'              *> Client certificate
        move ‘myclientpwd’ to lk-passphrase-returned                        *> Password for clntcert_key.pem
        move ‘C:\my\path\CARootcert.pem’ to lk-CARoot-to-be-used            *> CA root used to sign server certificate
    
  8. Start your server region (and client region if using CICS as a client).
  9. From a browser enter: https://<host>:<port number in TCPIPSERVICE>/my/ssl/path Note that the host name should match the Common Name in the server certificate exactly. You should be prompted to choose a client certificate to use.
  10. If the client is a CICS program:
    • The WEB OPEN should specify:
      • SCHEME(HTTPS)
      • The port number specified in the TCPIPSERVICE.
      • CERTIFICATE(WS-CERT) where WS-CERT has a value of clntcert. If no certificate is specified, then the default client certificate is used. You can also specify a URIMAP on the WEB OPEN which specifies which certificate to use.
    • The WEB SEND should specify:
      • PATH(WS-PATH) where WS-PATH has a value of /my/ssl/path.