Skip to content
CA Gen - 8.6
Documentation powered by DocOps

Preparing C GUI Client for a Secure Connection with CICS Server

Last update July 4, 2018

CA Gen provides a communication, protected by SSL encryption, between GUI Client and CICS Server. When preparing to establish a communication, you may go with your choice of security validation. You may want to validate the SSL Certificate with or without a host name, or you may proceed without any validation. An attempt to proceed without validation ensures that the data is encrypted but not trusted.

This article includes:

Configuring the C GUI Client at Runtime

Update commcfg.ini entry to include options for security and SSL validation. To do this, provide the secure option "S" and the SSL validation option "I", "Y", or "H" in the COMMCFG.INI file in the given format. 

<TRANCODE> TCP <host> <service/port> <connection_persistence> S <SSL_validation_option>

For example,

* TCP myhost1 443 N S I

or

* TCP myhost1 443 N S Y

or

* TCP myhost1 443 N S H

where,

S indicates a connection to the secure port

I indicates ignore server certificate validation

Y indicates server certificate validation

H indicates both server certificate and host name validation

Important: If "S" is not added to the entry, the connection would be treated as default (non-secure).

To learn more about the I, Y, and H options for validation, see Validation.

SSL Validation

During execution, C GUI runtime uses the cacert.pem file to validate server certificates. The cacert.pem file is a bundle of public certificates trusted by the Certificate Authority. 

By default, CA Gen installation directory has a sample ‘cacert.pem’ file. In windows operating system, C GUI runtime searches for this file in the following order.

  1. %COMMCFG_HOME% - The directory value contained within the environment variable %COMMCFG_HOME%
  2. %USERPROFILE%\AppData\Local\CA\Gen 8.6\cfg
  3. %ALLUSERSPROFILE%\CA\Gen 8.6\cfg
  4. %PATH% - Each path component within the environment variable %PATH%

Depending on your preferences, you can choose any of the following validation options:

Server Certificate Validation

Update the commcfg.ini file with the SSL validation option "Y" to enable server certificate validation.

For example,

* TCP myhost1 443 N S Y

where,

S indicates a connection to the secure port

Y indicates server certificate validation

Host Name and Server Certificate Validation

Update the commcfg.ini file with the validation option "H" to enable server certificate and host name validation.

For example, 

* TCP myhost1 443 N S H

where,

S indicates a connection to the secure port

H indicates server certificate and host name validation

Ignore Server Certificate Validation

Update the commcfg.ini file with the validation option "I" to proceed with encrypted data without verifying the server certificate.

For example, 

* TCP myhost1 443 N S I

where,

S indicates a connection to the secure port

I indicates ignore server certificate validation

Possible Errors

A secure socket connection may fail because of the following reasons.

  • Missing or incorrect cacert.pem file.
  • Trying to connect a non-secure server by giving a secure option.
  • The secure server is not available.

Connection Errors

A failed connection throws error codes, such as:

  • SSL_ERROR_ZERO_RETURN
  • SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
  • SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
  • SSL_ERROR_WANT_X509_LOOKUP
  • SSL_ERROR_SYSCALL
  • SSL_ERROR_SSL

For details about the error message, see https://www.openssl.org/docs/man1.1.1/man3/SSL_get_error.html.  

Validation Errors

A failed validation of the server certificate throws error codes, such as:

  • X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT
    Unable to find the certificate for one of the certificate authorities (CAs) in the signing hierarchy and that CA is not trusted by the local application.
  • X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE
    Unable to decrypt the signature of the certificate.
  • X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY
    The public key in the certificate could not be read.
  • X509_V_ERR_CERT_SIGNATURE_FAILURE
    The signature of the certificate is not valid.
  • X509_V_ERR_CERT_NOT_YET_VALID
    The certificate is not valid until a date in the future.
  • X509_V_ERR_CERT_HAS_EXPIRED
    The certificate has expired.
  • X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD
    There is a format error in the notBefore field of the certificate.
  • X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD
    There is a format error in the notAfter field of the certificate.
  • X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
    The passed certificate is self-signed and the same certificate cannot be found in the list of trusted certificates.
  • X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN
    A self-signed certificate exists in the certificate chain. The certificate chain could be built up using the untrusted certificates, but the root CA could not be found locally.
  • X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
    The issuer certificate of a locally looked up certificate could not be found. This normally means that the list of trusted certificates is not complete.
  • X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE
    No signatures could be verified because the certificate chain contains only one certificate, it is not self-signed, and the issuer is not trusted.
  • X509_V_ERR_INVALID_CA
    A CA certificate is not valid because it is not a CA or its extensions are not consistent with the intended purpose.
  • X509_V_ERR_PATH_LENGTH_EXCEEDED
    The basicConstraints pathlength parameter was exceeded.
  • X509_V_ERR_INVALID_PURPOSE
    The certificate that was provided cannot be used for its intended purpose.
  • X509_V_ERR_CERT_UNTRUSTED
    The root CA is not marked as trusted for its intended purpose.
  • X509_V_ERR_CERT_REJECTED
    The root CA is marked to reject the purpose specified.
  • X509_V_ERR_SUBJECT_ISSUER_MISMATCH
    The issuer certificate was rejected because its subject name did not match the issuer name of the current certificate.
  • X509_V_ERR_AKID_SKID_MISMATCH
    The issuer certificate was rejected because its subject key identifier was present and did not match the authority key identifier of the current certificate.
  • X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH
    The issuer certificate was rejected because its issuer name and serial number were present and did not match the authority key identifier of the current certificate.
  • X509_V_ERR_KEYUSAGE_NO_CERTSIGN
    The issuer certificate was rejected because its keyUsage extension does not permit certificate signing.
  • X509_V_ERR_CERT_REVOKED
    The certificate was revoked by the issuer.
Was this helpful?

Please log in to post comments.