Troubleshooting: Email Listener does not start, SSL/TLS certificate missing
When a PRPC application connects to an email server to receive or send email correspondence, the Email Listener may fail to start or function. This can occur if the application server lacks the proper digital certificates for establishing secure connections to the email servers or relays used by the Email Listener. This symptom may present itself regardless of the Use SSL? setting on the PRPC email configuration records associated with the Email Listener. Incomplete or improper installation of digital certificates can also cause this problem.
Consult your application server documentation for instructions on installing digital certificates for establishing trust in secure connections (SSL, TLS, or both). As a temporary alternative in a development or test environment – not in a production environment – disable the STARTTLS default setting for email features on your PRPC application server.
The error message varies depending on root cause and environment. Typical errors are
Peer Not Authenticated or
Unable to determine certification path to host.
To protect data and message-based communications, securing email infrastructure with the Transport Layer Security (TLS) protocol, formerly known as Secure Sockets Layer (SSL), increasingly prevails as the best practice. The Email Listener feature in PRPC acts as an email client and communicates with email relays and email servers that support or require this type of security.
In traditional, secure email protocols, you must explicitly intend on securing the transport layer prior to establishing the connection. In PRPC, you check the Use SSL? option in Email Account records, Email Server records, or both.
A newer trend in securing email is to issue an implicit STARTTLS command. In current practices, STARTTLS is primarily used for SMTP (outbound) connections.
- PRPC versions prior to PRPC 6.3 SP2 do not natively support STARTTLS; you must apply a hotfix.
- PRPC versions 6.3 SP2 and later always attempt STARTTLS when supported by an email server, even if the USE SSL? option is not enabled on email-related data records.
Reliance on digital certificates
Both SSL and TLS rely on digital certificates to establish trust between the server and the client and to exchange information used to secure the connection. An email server provides a digital certificate for use by the client when establishing a secure connection to it.
PRPC as an email client
When PRPC acts as the email client, this certificate must be installed on the application server. If the application server on which PRPC is running does not have a corresponding digital certificate installed in the trust settings for SSL/TLS, the connection will fail.
The noticeable symptoms vary depending on the application server and on the ultimate cause for the failure. A common result is a logged error of
Peer Not Authenticated or an inability to establish a chain of trust for the digital certificate provided by the email server.
To provide the best security for the email connection, PRPC always attempts to use STARTTLS for email servers that support it. All versions of PRPC always require that the PRPC application server be configured to trust the digital certificates provided by an external resource that is secured using SSL or TLS protocol, email servers included. Enabling SSL or TLS settings for email connections is only successful if you have already completed the trust configuration on the application server. STARTTLS, which handles both SSL and TLS, imposes this requirement.
To trust the digital certificates of a certain email server, the application server must have the one of the following:
- A copy of a valid digital certificate for the Certificate Authority that provided or signed the server’s certificate
- A copy of the exact certificate that the email server provides to clients
These certificates are readily available free of charge. Certificate Authorities normally provide downloads for their certificates on their websites.
Follow the best practice of obtaining and installing digital certificates for the PRPC application server. As an alternative, apply the Local Change as a temporary solution in your PRPC development and test environments only, never in your production environment.
Obtaining and properly installing the digital certificate on the PRPC application server is the best way to resolve PRPC Email Listener failure. Consult your application server documentation for instructions on installing digital certificates for establishing trust in secure connections (SSL, TLS, or both).
Resolution of the PRPC email listener failure depends on how the system and applications are set up and which application server software is in use. For more information, see How to configure the application server to support SSL/TLS in PRPC.
Local change for development and test environments
If you are experiencing the PRPC Email Listener failure in a development or test environment, you can disable the STARTTLS command that is enabled by default for email features on your PRPC application server.
For PRPC versions 6.3 SP2 and later, specify the following Dynamic System Setting:
- Owning Ruleset: Pega-IntSvcs
- Setting Purpose: Email/DisableSecuritySTARTTLS
- Value: true
For PRPC versions prior to PRPC 6.3 SP2, install the appropriate hotfix. Both are available on Hotfix Self-Service.
- For PRPC 6.2 SP2, install HFix-6029.
- For PRPC 6.3 SP1, install HFix-6859.