%ZHSLIB.TLS.Utils

Configure TLS Access so that production web clients can know what TLS settings to use to connect to the web server via SSL/TLS. @Argument TLSConfig is a string, that can be: 1. String containing the JSON, e.g. "{""host"": ""USE999myname""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"host": "USE999myname"} 2.2 or {"TLSConfig": {"host": "USE999myname"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. TLSConfig: { host: Webserver host name. Default to be $$$HSNetworkHostName (unchanged). port: Webserver port. Default to be the port the IRIS web server is running on. webServerPrefix: Only necessary if you are configuring one web server to connect to multiple HealthShare instances. active: Boolean value indicating whether the SSL settings are active. Default to 1. normalizePort: Boolean value indicating whether to normalize the testing port. Default to be 1. secureConfig: IRIS SSL/TLS configuration used for accepting all incoming requests. Default to be $$$HSDemoSSLConfigName. }

////////////////////// Utils for configuring web server ////////////////////////////////////// Re-Configuring Small/Private Apache Web Server to Serve HTTPS Requires that the HealthShare instance's Apache web server to have SSL enabled, specifically: For Windows, check that httpd/modules directory exists and contains mod file (only need to check for the existance of one file inside) For Unix, mod_ssl is statically linked into httpd so no need to double check This method should be called after TLS certificate has being created Once webserver restarted, should be able to access SMP of the HS instance @Argument pWebServerConfig is a string, that can be: 1. String containing the JSON, e.g. "{""webServerPort"": """"}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"webServerPort": ""} 2.2 or {"WebServerConfig": {"webServerPort": ""}} We also support 2.2 in case user want to put multiple configs in a single JSON file. WebServerConfig: { "webServerPort": Numeric port that the web server should be running on. Default to be the port the IRIS web server is running on. "normalizePort": Boolean value indicating whether to normalize the port to be in registered port range. Default to be 1. "certFileName": (Required) Name of the certificate file WITH file type extension, such as filename.cer, filename.crt. Require full file name including extension to allow flexible and customized certificates. "certKeyFileName": (Required) Name of the certificate key file WITH file type extension, such as filename.key. }

////////////////////// Utils for creating TLS Certificates ////////////////////////////////////// Step 1 Create a demo certificate authority server to handle certificate signing request @Argument pCAServerConfig is a string, that can be: 1. String containing the JSON, e.g. "{""CAFileName"": ""HSDEMOCA""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"CAFileName": "HSDEMOCA"} 2.2 or {"CAServerConfig": {"CAFileName": "HSDEMOCA"}} We support 2.2 in case user want to put multiple configs in a single JSON file. CAServerConfig: { "CAFileName": (Required) String file name root of the CA certificate and private key files (without extension). "CAPath": Directory for CA certificate and private key files. Default to be manager directory. "serverPassword": (Required) Password to CA's Private Key file. "country", "stateProvince", "locality", "organization", "organizationalUnit": Attributes used in constructing this CA server's Subject Distinguished Name. "commonName": Attributes used in constructing this CA server's Subject Distinguished Name. Default to be CA "validDays": Numeric (days) validity period for CA certificate & certificate issued by CA. }

Step 3 Configure a local certificate authority client @Argument pCAClientConfig is a string, that can be: 1. String containing the JSON, e.g. "{""CAServerHostName"": ""USE999myname""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"CAServerHostName": "USE999myname"} 2.2 or {"CAClientConfig": {"CAServerHostName": "USE999myname"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. CAClientConfig: { "CAServerHostName": Defeault to $$$HSNetworkHostName "CAServerPort": CA webserver's port number. Default to be instance's web server port. "contactName": Default to be current username. }

////////////////////// Utils for establishing SSL/TLS Configuration ////////////////////////////////////// Create a new IRIS SSL/TLS configuration This should happen after getting signed certificates and getting HTTPS support for local instance Please refer to Security.SSLConfigs for further details on properties @Argument pIRISTLSConfig is a string, that can be: 1. String containing the JSON, e.g. "{""Name"":""""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"Name":""} 2.2 or {"IRISTLSConfig": {"Name":"your config name"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. Here are the default arguments we used to create a secure HS Demo in %ZHSLIB.TLS.API The properties should match the properties in Security.SSLConfigs IRISTLSConfig: { Name: Default to "HS.Secure.Demo" (macro $$$HSDemoSSLConfigName). Description: Optional description. Enabled: Default to true. CAFile: Filename (with extension) of file containing trusted Certificate Authority certificate. Type: Default to 0 (Client). VerifyPeer: Default to 1 (Require server certificate). CertificateFile: Filename (with extension) of file containing this client/server(depends on type)'s certificate. PrivateKeyType: Default to 2 (RSA). PrivateKeyFile: Filename (with extension) of this configuration's private key. PrivateKeyPassword: Password to CA's Private Key file. Protocols: Default to 24 (TLSv1.1 + TLSv1.2) } }

Step 6 Get Certificate(s) from Certificate Authority server @Argument pGetCertConfig is a string, that can be: 1. String containing the JSON, e.g. "{""fileNameRoot"": ""HSDEMOCAClient""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"fileNameRoot": "HSDEMOCAClient"} 2.2 or {"GetCertConfig": {"fileNameRoot": "HSDEMOCAClient"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. fileNameRoot: (Required) Name of the certificate file without file type extension.

Step 5 Process pending Certificate Signing Requests @Argument pCertReqProcessConfig is a string, that can be: 1. String containing the JSON, e.g. "{""fileNameRoot"": ""HSDEMOCAClient""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"fileNameRoot": "HSDEMOCAClient"} 2.2 or {"CertReqProcessConfig": {"fileNameRoot": "HSDEMOCAClient"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. CertReqProcessConfig: { "fileNameRoot": (Required) Name of the certificate file without file type extension. "password": (Required) Password for this CA server's Private Key file. "certificateType": (Required) Intended usage of the issued certificate. 1 = TLS/SSL, 2 = Intermediate CA server. }

Step 4 Submit Certificate Signing Request to Certificate Authority server @Argument pCertSignRequestConfig is a string, that can be: 1. String containing the JSON, e.g. "{""fileNameRoot"": ""HSDEMOCAClient""}" 2. File URI where the source can be read. "C:\testConfig.JSON", which contains: 2.1 {"fileNameRoot": "HSDEMOCAClient"} 2.2 or {"CertSignRequestConfig": {"fileNameRoot": "HSDEMOCAClient"}} We also support 2.2 in case user want to put multiple configs in a single JSON file. CertSignRequestConfig: { "fileNameRoot": (Required) Name of the certificate file without file type extension. "country", "stateProvince", "locality", "organization", "organizationalUnit": Attributes used in constructing this CA server's Subject Distinguished Name. "commonName": Attributes used in constructing this CA server's Subject Distinguished Name. Default to be Client "password": Optional password used to protect Private Key file. }

Step 2 Once demo CA server is configured and openssl.cnf exists, update it to have a DNS name (subject alternative name) which will be the hostname to access server via SSL. This should be the fully qualified host name of your server. In our case, $$$HSNetworkHostName e.g. USE999myname @Argument pUpdateSSLConfig is a string, that can be: 1. String of the path in JSON, e.g. "{""CAPath"": """"}" 2. File URI where the path can be read. "C:\testConfig.JSON", which contains: 2.1 {"CAPath": ""} 2.2 or {"UpdateSSLConfig": {"CAPath": ""}} UpdateSSLConfig: { CAPath: Directory for CA certificate and private key files. Default to be manager directory. }