Feedback
 
Did this article resolve your question/issue?

   

Your feedback is appreciated.

Please tell us how we can make this article more useful. Please provide us a way to contact you, should we need clarification on the feedback provided or if you need further assistance.

Characters Remaining: 1025

 


Article

How to configure and test a PASOE instance for secure communications?

« Go Back

Information

 
Article Number000074259
EnvironmentProduct: OpenEdge
Version: 11.6, 11.7
OS: All supported platforms
Other: Progress AppServer for OpenEdge, Secured Socket Layers communication
Question/Problem Description
How to configure and test a PASOE instance for secure communications?
How to create a certificate request and import a certificate into an PASOE instance?
Configuring PAS for OpenEdge for SSL/TLS
Configure PASOE for SSL.
Configuring PASOE for HTTPS.
 
Steps to Reproduce
Clarifying Information
Error Message
Defect/Enhancement Number
Cause
Resolution
To Configure PASOE for SSL:
  • Run the commands below in a ‘PROENV’ environment.
  • On windows replace <DLC> with %DLC%,
  • On Unix/Linux replace <DLC> with $DLC and back slashes with forward slashes.
  • Replace <CATALINA_BASE> with the path for the PASOE instance.
  • Use ‘pasman instances’ to list all PASOE instances and the path to their <CATALINA_BASE> on the system.
Access via HTTPS is dependent on having a SSL/TLS Server Certificate:
  • <CATALINA_BASE>/conf/tomcat-keystore.p12 - The default PASOE instance keystore file which uses a PKCS12 type storage format, it contains 2 aliases for testing and is maintained using the Java Keytool utility.
  • <CATALINA_BASE>/conf/tomcat-certstore.jks - The certificate trust store file for intermediate/root CA certificates, which uses the default JAVA distribution file format JKS. 
  • <CATALINA_BASE>/conf/server.xml - PASOE TLS/SSL is controlled by Tomcat connectors (catalina.properties)
  • To include subject alternative name (SAN) information in an SSL certificate, prior to performing the steps outlined in this article, refer to Article 000081912, How to create a SSL certificate that includes a SAN. 
PASOE SERVER 

Note: If the environment already has a signed certificate use Option B instead.

Option A | I need to acquire a new signed certificate for production

A1. Generate the private(.pk1) and public (.pk10) keys using the OpenEdge pkiutil utility:
               
pkiutil -keysize 2048 -newreq <chose an alias name>
NOTE:  The pkiutil tool included in 11.7 through 11.7.4 has a keysize limitation of 2048.  To make a private key with a keysize greater than 2048 use the $DLC/jdk/bin/keytool utility. 
Example:
keytool -genkey -alias <aliasnamehere> -keyalg RSA -keysize 4096 -keystore java-keystore-filename-here.jks

Choose a password/passphrase and take note of it. The pkutil utility will issue a prompt asking for specific information that will be incorporated into the certificate request. For example:
            -----
            Country Name (2 letter code) [US]:<Country>
            State or Province Name (full name) []:<State>
            Locality Name (eg, city) []:<City>
            Organization Name (eg, company) []: <Company name>
            Organizational Unit Name (eg, section) []:< Business unit>
            Server DNS name []:<Hostname>
 
Once the required information is provided, a file with a .pk10 extension will be created.
In this example, the file: <DLC>/keys/requests/<given name>.pk10 will be used to request a new digital certificate from the Certificate Authority (CA).
 
A2. Provide the (.pk10) file generated in the above steps to the CA when requesting the signed certificate.
 
A3. After the signed digital certificate (.cer or .crt). is received from the CA, use the pkiutil tool with the -import option to import the certificate into the OE keystore. For example: 
               
pkiutil -import <alias name> <DLC>\keys\requests\<cert name>.cer

    Output similar to the following will be displayed:
 
        Importing private key alias <name>:
        Importing certificate file <DLC>\keys\<cert name>.cer
 
    This will create a <cert name>.pem file under <DLC>\keys.
 
A4. (Windows Only) set the RANDFILE variable so the 'random state' file can be created: 
               
set RANDFILE=%DLC%\keys\.rnd
 
http://stackoverflow.com/questions/12507277/how-to-fix-unable-to-write-random-state-in-openssl
 
A5. Create a new keystore using the signed certificate (There will be a prompt to create an “export” password): 
               
sslc pkcs12 -export -in <DLC>/keys/<certificate-name>.pem -out tomcat-keystore.p12 -name <alias name>
 
Option B | I already have a signed certificate 

B1. If the certificate is not in a PEM format, convert it to PEM.
 
sslc x509 -in mycert.crt -out mycert.pem -outform PEM

B2. (Windows Only) set the RANDFILE variable so the 'random state' file can be created: 
 
set RANDFILE=%DLC%\keys\.rnd
 
http://stackoverflow.com/questions/12507277/how-to-fix-unable-to-write-random-state-in-openssl

B3. Generate the Java keystore by using the PEM and private key for the certificate.
 
sslc pkcs12 -export -inkey <private key>.key -in <file name>.pem -out tomcat-keystore.p12 -name <alias name>

Options A & B continuation:

1. Verify the content of the newly created keystore and that the required certificate and hierarchy is correct: 
               
<DLC>\jdk\bin\keytool -storetype PKCS12 -list -keystore .\tomcat-keystore.p12
            
sslc pkcs12 -info -in ./tomcat-keystore.p12
 
2. Rename the default PASOE instance keystore (<CATALINA_BASE>/conf/tomcat-keystore.p12) to tomcat-keystore.p12.og ( this keystore contains default test aliases).

3. Move the newly created keystore to <CATALINA_BASE>/conf

4. Configure the PASOE instance to use the new alias and keystore password by updating <CATALINA_BASE>/conf/catalina.properties
<CATALINA_BASE>\bin\tcman config psc.as.https.keyalias=<alias name>
<CATALINA_BASE>\bin\tcman config psc.as.https.keypass=<password>
5. Restart the PASOE instance.

CLIENT

1. The clients that will be connecting to the PASOE instance via HTTPS will require the root/intermediate CA's certificates in order to validate the signed certificate. If the client is an ABL client use certutil to import the certificate into the OE keystore:
 
certutil -import <path to certificate>

Third-party clients like browsers usually use the OS specific certificate keystore or their own keystore. Well-known CA certificates are usually already included in these keystores. 

2. Sample ABL code to test the connection:

Note: The PASOE instance must be running.
 
DEFINE VARIABLE hAppSrv AS HANDLE NO-UNDO.
DEFINE VARIABLE ret AS LOGICAL NO-UNDO.
 
CREATE SERVER hAppSrv.
 
// If using the ROOT webapp the URL would be https://<hostname>:<HTTPS port>/apsv instead
ret = hAppSrv:CONNECT("-URL https://<hostname>:<HTTPS port>/<Webapp name or blank if using ROOT>/apsv","","").
 
IF NOT ret THEN DO:
  DELETE OBJECT hAppSrv NO-ERROR.
  RETURN ERROR "Failed to connect to the PASOE instance via HTTPS " + RETURN-VALUE.
END.

ELSE DO:
   message "Connection successful" view-as alert-box.
END.

ret = hAppSrv:DISCONNECT().
 
DELETE OBJECT hAppSrv NO-ERROR.


For a third party client like a browser, access the application URL via HTTPS. 
https://<hostname>:<HTTPS port>
Workaround
Notes
References to Other Documentation:

Progress Application Server for OpenEdge, Administration Guide, Server security : Configuring PAS for OpenEdge for SSL/TLS : Configuring a PAS for OpenEdge instance for SSL/TLS
https://documentation.progress.com/output/ua/OpenEdge_latest/index.html#page/pasoe-admin%2Fconfiguring-a-pas-for-openedge-instance-for-ssl-2f.html

Technical Whitepaper: SSL/TLS Communication in Progress OpenEdge. Progress , 2017,
www.progress.com/papers/technical-whitepaper-ssl-tls-communications-in-progress-openedge  

Progress Article:

000091229, How to debug ABL SSL connection issues on Progress Application Server for OpenEdge (PAS for OE)  
Attachment 
Last Modified Date10/15/2019 12:07 PM