This documentation site is for previous versions.

Visit our new documentation site for current releases.

How to configure the application server to support SSL/TLS in PRPC

Updated on March 8, 2017

Prerequisites

This article provides a roadmap for configuring SSL on application servers hosting PRPC. It assumes that security specialists administering application servers for the enterprise have prerequisite knowledge about SSL/TLS, keystores and trust stores, Certificate Authorities, and digitally signed certificates.

Avoid SSL errors
What PRPC features use SSL/TLS?
Obtaining digital certificates for SSL/TLS
Locating the trust store for SSL/TLS
Importing a new certificate
Additional Information
References

Avoid SSL errors

Digital certificates installed on the application server are a prerequisite for establishing secure connections between clients and servers using Secure Sockets Layer (SSL), now known as Transport Layer Security (TLS), for trusted interactions that circumvent snooping and other security breaches. SSL certificates contain the name of the issuer, the name of the entities that the certificate applies to, dates for which the certificate is valid, and the public key to be used for establishing encryption.

Missing or improperly installed digital certificates for secure email correspondence and secure web services connections (HTTP, REST, etc.) can cause connectivity failure, indicated by error messages. The only way to resolve the issue is to install digital certificates in the correct locations for PRPC. Each application server has different procedures for installing and managing digital certificates for SSL/TLS. This article provides general information and references.

SSL failure in email

javax.mail.MessagingException: Can't send command to SMTP host;

nested exception is:

javax.net.ssl.SSLHandshakeException

sun.security.validator.ValidatorException: PKIX path building failed:

sun.security.provider.certpath.SunCertPathBuilderException:

unable to find valid certification path to requested target

SSL failure in web service connectors (HTTP, REST, others)

com.pega.pegarules.pub.services.ConnectorException:

Caught unhandled exception: javax.net.ssl.SSLPeerUnverifiedException:

peer not authenticated

at com.pegarules.generated.activity.ra_action_invokehttpconnector...

Caused by: javax.net.ssl.SSLPeerUnverifiedException:

peer not authenticated

at sun.security.ssl.SSLSessionImpl.getPeerCertificates(Unknown Source)

What PRPC features use SSL/TLS?

Web browsers, Java applications, Web service connections, email correspondence, and PRPC applications themselves use SSL/TLS.

Web browsers

Web browsers are SSL clients that prompt you to accept (trust) or reject a bad or suspicious certificate. Web browsers typically use the operating system's built-in trust store of certificates with default support for many web sites. The operating system trust store may be maintained automatically, for example, by applying Microsoft Windows updates.

Java applications

Java applications, like PRPC, are SSL clients that do not use the operating system's built-in trust store. Instead, they rely on many libraries that provide SSL support. As such, Java applications might not be able to mitigate all SSL errors.

SSL/TLS in PRPC: Web service connections and Email correspondence

PRPC uses Java Secure Socket Extension (JSSE) for SSL/TLS in Web services for HTTP, REST, and other connectors and services and in Email Correspondence. PRPC HTTP and REST connectors and services use Apache HTTP Components Client. Legacy PRPC versions use Apache Commons. PRPC Email uses JavaMail.

As an SSL client, a PRPC application must tell the server what kinds of encryption it understands and must possess a trust store of certificates that it accepts. Certificates in the PRPC trust store can be issued to a set of one or more servers or even entire domains. Connection to the remote resource is not established if any of the following conditions exist to interfere with the SSL client-server handshake:

Client and server SSL capabilities do not match.
The certificate was not issued to the server that provided it.
The client determines that the certificate has expired, using the operating system’s current date and time.

If two-way SSL is required, the client must provide its own certificate to the server, and the server must have a corresponding certificate in its trust store.

PRPC applications as SSL clients

PRPC applications act as SSL clients when web service connectors for integration with external repositories require secure interactions and when inbound and outbound email correspondence must be secure.

Secure authentication and log-in

Secure log-in – The HTML rule Web-Login-SecuredBasic provides the default log-in form for applications secured by SSL.
Secure authentication – In the Authentication Service form, under the Custom tab, you check Use SSL to require that users be authenticated through a Secure Sockets Layer secure port, which requires using an HTTPS URL for authentication. The servlet PRServletProtected supports HTTP Basic Authentication over Secure Sockets Layer (SSL).

Web service connectors

In PRPC applications, SSL-protected web services can include HTTP Connectors, REST Connectors, and other connectors (EJB, Java, .NET, SOAP, and SQL). For example, to secure HTTP and REST connectors, you specify https in the Endpoint URL (for HTTP) or Resource Path (for REST) in the Connector rule. The URL may also be an https endpoint when specified in a rule that uses a Connector, or, when chosen at runtime, when set indirectly by a global resource setting or dynamic system setting.

In the SOAP Connector form, you specify the Web Services Policy or Security Profile for SSL-enabled SOAP services.
The Data-Admin-System-Targets class holds System Targets data instances. You specify a secure connection to System Targets using SSL by checking the option Https?

Email correspondence

Secure email correspondence (inbound and outbound) uses the SSL/TLS protocol. The port numbers and security settings must match those configured by the email provider.

You set the port number on the Email Account record (the Email Server record in legacy versions of Pega) as prescribed by the email provider. Then you check or uncheck the Use SSL? option, depending on the security scheme in use.

Check Use SSL? to enable traditional SSL, which does not include STARTTLS.
Uncheck Use SSL? for plain (unsecured) connections or connections secured with STARTTLS.

PRPC will always use STARTTLS when advertised by the email provider. If you need to disable STARTTLS in a development or test environment, specify this Dynamic System Setting:

Owning Ruleset: Pega-IntSvcs

Purpose: Email/DisableSecuritySTARTTLS

value: true

Do not disable STARTTLS in a production environment.

You can also set up your application to send digitally signed email messages. This helps the recipient to verify that the message is really from your system and that the message has not been altered.

Obtaining digital certificates for SSL/TLS

PRPC applications that connect to secured services require that the application server have the one of the following for each remote endpoint:

A copy of a valid digital certificate for the Certificate Authority (CA) that signed the server’s certificate
A copy of the exact certificate that the server provides to clients

These certificates are readily available free of charge. Certificate Authorities (CA) such as Verisign normally provide downloads for their certificates on their public websites.

When your PRPC application will be secured with SSL/TLS or connect to a service using two-way or mutual SSL, you must obtain and install a certificate from a trusted certificate authority or use a certificate that you have created.

Common tools for creating certificates or certificate requests, which are used to create signed certificates, are the following:

The Key Tool command-line utility, provided with the Oracle/Sun Java Development Kit
Portecle, a free Java utility that provides a graphical user interface and has similar capabilities to Key Tool
OpenSSL, a free, open-source library for SSL/TLS

Refer to keytool - Key and Certificate Management Tool, under the section Requesting a Signed Certificate from a Certification Authority.

Locating the trust store for SSL/TLS

Once obtained, the digital CA certificates for a remote endpoint must be added to a trust store that is available to the JSSE library. This may be set by the Java parameter javax.net.ssl.trustStore. The default Java SE trusted certificate storage file, used when no other trust store has been set, is located in the directory <java-home>/lib/security/cacerts.

Refer to keytool - Key and Certificate Management Tool, under the section Terminology and Warnings, in the subsection The cacerts Certificates File.

Consult your application server documentation for instructions on installing digital certificates for establishing trust in secure connections (SSL, TLS, or both).

Restart the application server to ensure that all configuration changes are initialized and used by the system.

CA certificates on Apache Tomcat

Apache Tomcat may set the trust store by a setting in a Connector node in the server.xml configuration file.

Refer to the Tomcat documentation for more information.

CA certificates on Oracle WebLogic

Oracle WebLogic may need to be manually configured to use Java Secure Socket Extension (JSSE).

Refer to the Oracle WebLogic documentation for more information.

CA certificates on IBM WebSphere Application Server

WebSphere Application Server often uses a separate trust store layer that --

May not have any certificates installed.
Must be modified in the WebSphere Application Server Administrator Console in order to set Server-level trust to match the requirements of PRPC applications.
Might specify Node-level trust that does not work in PRPC.

Refer to the IBM WebSphere Application Server documentation for more information.