Secure Socket Layers and Public Key infrastructure

Secure Socket Layers (SSL) enables the use of digital certificates, certificate authorities, extensive network encryption, and checksums for all network packets.

Starting with v3.0, EPM supports Public Key Infrastructure (PKI) through SSL. This feature enables the use of Privacy Enhanced Mail (PEM) format certificates, private keys, and certificate authority files. The SSL features are controlled through the ssloptions setting, and the client and server settings.

ℹ️

Note

Starting with v22.3.0, ssl is always enabled.

Many of the SSL settings enable token expansion for some useful strings. These are summarized in the following table.

SSL parameter substitutions

ssl

The ssl setting is always set to yes, and enables the use of EPM-UL SSL features.

Example

ssl yes

ℹ️

Note

Version 22.3 deprecates ssl, but ssl can still be set to no. In v23.1, the keyword ssl is no longer supported.

⚠️

Important

For a new EPM-UL v23.1.0 install , the ssl keyword is not present in /etc/pb.settings. For an upgrade, the keyword is ignored.

Default

ssl yes

Used on

• Log hosts
• Policy server hosts
• Submit hosts
• Run hosts

restssloptions

• Version 10.1.0 and earlier: restssloptions setting not available.
• Version 10.2.0 and later: restssloptions setting available.

The current restssloptions include:

• TLSMinV1, TLSMinV1.0, TLSMinV1.1, TLSMinV1.2, and TLSMinV1.3
• TLSMaxV1, TLSMaxV1.0, TLSMaxV1.1, TLSMaxV1.2 and TLSMaxV1.3
• MinHMACMD5 and MinHMACSHA512

For FIPS compliance, all EPM-UL hosts must add MinHMACSHA512 to the restssloptions setting.

ssloptions

• Version 4.0.0 and later: ssloptions setting available.

The ssloptions setting controls the following system-wide options:

ℹ️

Note

The program terminates if invalid values are provided for ssloptions.

Example

ssloptions AllowNonSSL
ssloptions requiressl sslfirst
ssloptions ClientCertificates
ssloptions AllowNonSSL ClientCertificates

Default

requiressl

Used on

• Log hosts
• Policy server hosts
• Submit hosts
• Run hosts

Server-side SSL

For client hosts where optimized run mode is always used (the submit host is always the run host), a server-side SSL scenario can be set up where the client machine does not need a server key/certificate pair or a client key/certificate pair.

The sslpbruncafile keyword is optional. If sslpbruncafile is specified, sslpbruncafile is the certificate authority (CA) that signed the server’s certificate. If sslpbruncafile is not specified, then the server’s certificate authenticity is not verified.

ℹ️

Note

If the submit host is not the same host as the run host or if a log server is not used, then the pblocald server is used to execute the secured task. pblocald is an SSL server and requires the sslservercafile, sslservercertfile, and sslserverkeyfile settings.

SSL client settings

The SSL client settings configure SSL for EPM-UL client programs.

sslpbruncadir and sslpbruncafile

• Version 4.0.0 and later: sslpbruncadir and sslpbruncafile settings available.

These settings specify the path to a certificate authority directory or file.

A certificate authority file is a PEM-formatted file that contains one or more PEM-formatted signature certificates. The programs pbrun, pbksh, and pbsh use these certificate authority files to validate certificates from pbmasterd and pblocald. This file should not contain private keys.

If sslpbruncafile contains an absolute path, then that file is used as the certificate authority file. If sslpbruncafile contains a relative path, then the value of the sslpbruncadir setting is prepended to form an absolute path. The pbrun certificate authority file and certificate authority directory must be owned by root and no one else should have write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslpbruncafile /secure/ca/pbrun/OurAuthority.pem
sslpbruncadir /secure/ca/pbrun
sslpbruncafile OurAuthority.pem
sslpbruncadir /secure/ca/pbrun sslpbruncafile %N.pem

Default

No default value

Used on

Submit hosts

sslpbruncertdir and sslpbruncertfile

• Version 4.0.0 and later: sslpbruncertdir and sslpbruncertfile settings available.

The sslpbruncertdir and sslpbruncertfile settings specify the path of a Privacy Enhanced Mail (PEM) format certificate file for clients to communicate with pbmasterd and pblocald.

If a full absolute path is provided for sslpbruncertfile, then it is used. If a relative path is provided for sslpbruncertfile, then the directory specified in the sslpbruncertdir setting is prepended to form the certificate file path.

root or the submitting user must own the pbrun certificate file and certificate directory. No one else should have write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslpbruncertfile /secure/certificates/pbrun/pbrun.pem
sslpbruncertdir /secure/certificates/pbrun
sslpbruncertfile pbrun.pem
sslpbruncertdir /home/%u/certificates
sslpbruncertfile %u.pem

Defaults

No default value

Used on

Submit hosts

sslpbruncipherlist

• Version 4.0.0 and later: sslpbruncipherlist setting available.

OpenSSL provides a variety of algorithms that can be used for encryption. The sslpbruncipherlist setting enables the administrator to restrict or promote the set of encryption algorithms that are used by Endpoint Privilege Management clients to communicate with SSL enabled server services.

The keyword sslpbruncipherlist accepts "cipherlist=" and "tlsv1.3=" cipher groups.

The cipher groups cipherlist= and tlsv1.3= are case-sensitive and space is not allowed before =.

When using the sslpbruncipherlist keyword, the order of cipher lists is not relevant.

This format: sslpbruncipherlist cipherlist= TLSv1.2:!SSLv2:@STRENGTH tlsv1.3= TLS_AES_256_GCM_SHA384

is the same as this format:

sslpbruncipherlist tlsv1.3= TLS_AES_256_GCM_SHA384 cipherlist= TLSv1.2:!SSLv2:@STRENGTH

These ciphers are limited to the set of ciphers available in the given version of OpenSSL used by the Endpoint Privilege Management installation.

📘

For more information, see the Release Notes.

Valid values

Refer to the following table for the valid values for the sslpbruncipherlist. To use more than one cipher set, separate the values with colons.

cipherlist Values

tlsv1.3 Values

Examples

In the following code snippet, EPM-UL uses the cipher lists:

• TLSv1.2:!SSLv2:@STRENGTH for TLS v1.2 (and earlier) connections
• TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256 for TLS v1.3 connections

sslpbruncipherlist cipherlist=TLSv1.2:!SSLv2:@STRENGTH tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256

In the following code snippet, EPM-UL uses the cipher lists:

• TLSv1.2:!SSLv2:!3DES:!eNULL:@STRENGTH for TLS v1.2 (and earlier) connections.
• tlsv1.3= cipher group for TLSv1.3 connections. This is the default value.

sslpbruncipherlist cipherlist=TLSv1.2:!SSLv2:!3DES:!eNULL:@STRENGTH

Default

cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH

tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

Used on

Submit hosts

sslpbrunkeydir and sslpbrunkeyfile

• Version 4.0.0 and later: sslpbrunkeydir and sslpbrunkeyfile settings available.

The sslpbrunkeyfile and sslpbrunkeydir settings enable you to specify the location of a PEM-formatted private key for the client certificate file that is used to communicate with pbmasterd and pblocald.

If sslpbrunkeyfile is a full path name, then it is used for the private key. If sslpbrunkeyfile does not contain an absolute path, then sslpbrunkeydir is prepended to it.

The clients are usually interactive, so the private keys can be encrypted. The clients prompt for the passphrase when needed. If you are invoking a client non-interactively (for example, from cron), then the private key should not be encrypted.

root or the submitting user must own the private key file and the private key directory. No one else should have read or write permission.

If the key file and directory are not set, then the client looks in the certificate file to see if the key is there. In this case, the certificate file and directory must be read-only and owned by root or the submitting user. No one else should have read or write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslpbrunkeyfile /secure/privatekeys/pbrun.pem
sslpbrunkeydir /secure/privatekeys/
sslpbrunkeyfile %u.pem
sslpbrunkeydir /home/%u/privatekeys
sslpbrunkeyfile %u.pem

Defaults

No default value

Used on

Submit hosts

sslpbrunverifysubject

• Version 4.0.0 and later: sslpbrunverifysubject setting available.

sslpbrunverifysubject contains a series of regular expressions to check against the policy server’s certificate subject line. If the subject line matches all patterns, then the connection is allowed to proceed. If any of the patterns do not match, then the connection fails.

Example

This example verifies that the CN attribute (common name) matches the host name of the remote machine:

sslpbrunverifysubject /CN=%R/

Example

This example verifies that the O attribute equals Company Name and that the OU attribute starts with Technology:

sslpbrunverifysubject '/O=Company Name/' /OU=Technology

ℹ️

Note

Single quotation marks should surround the attribute if there are embedded spaces.

Default

No default value

Used on

Submit hosts

SSL server settings

The SSL server settings configure SSL for EPM server programs.

sslservercadir and sslservercafile

• Version 4.0.0 and later: sslservercadir and sslservercafile settings available.

The sslservercadir and sslservercafile settings specify the path to a certificate authority directory or file. A certificate authority file is a PEM-formatted file that contains one or more PEM-formatted signature certificates that are used to validate server certificates. This file should not contain private keys.

If sslservercafile contains an absolute path, then that file is used as the certificate authority file. If sslservercafile contains a relative path, then the value of the sslservercadir setting is prepended to form an absolute path.

The server certificate authority file and certificate authority directory must be owned by root and no one else should have write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslservercafile /secure/ca/servers/OurAuthority.pem
sslservercadir /secure/ca/servers
sslservercafile OurAuthority.pem
sslservercadir /secure/ca/servers sslservercafile %h.pem

Defaults

/etc/<prefix>pbssl.pem<suffix>

Used on

• GUI hosts
• Log hosts
• Policy server hosts
• Run hosts

sslservercertdir and sslservercertfile

• Version 4.0.0 and later: sslservercertdir and sslservercertfile settings available.

The sslservercertdir and sslservercertfile settings specify the path of a Privacy Enhanced Mail (PEM) format certificate file for pbmasterd, pblocald, and pblogd to communicate with each other or with client programs.

• If a full absolute path is provided for sslservercertfile, then it is used as specified.
• If a relative path is provided for sslservercertfile, then the directory specified in the sslservercertdir setting is prepended to form the certificate file path.

The server certificate file and certificate directory must be owned by root and no one else should have write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslservercertfile /secure/certificates/servers/pbmasterd.pem
sslservercertdir /secure/certificates/servers
sslservercertfile pbmasterd.pem
sslservercertdir /secure/certificates/servers
sslservercertfile %N.pem

Defaults

/etc/pbssl.pem

Used on

• GUI hosts
• Log hosts
• Policy server hosts
• Run hosts

sslservercipherlist

• Version 4.0.0 and later: sslservercipherlist setting available.

OpenSSL provides a variety of algorithms that can be used for encryption. The sslservercipherlist setting enables the administrator to restrict or promote the set of encryption algorithms that are used by EPM servers when they receive communications from SSL enabled clients.

These ciphers are limited to the set of ciphers available in the given version of OpenSSL used by the EPM installation.

The keyword sslservercipherlist accepts "cipherlist=" and "tlsv1.3=" cipher groups.

The cipher groups cipherlist= and tlsv1.3= are case-sensitive and space is not allowed before =.

When using the sslservercipherlist keyword, the order of cipher lists is not relevant.

This format: sslservercipherlist cipherlist= TLSv1.2:!SSLv2:@STRENGTH tlsv1.3= TLS_AES_256_GCM_SHA384

is the same as this format:

sslservercipherlist tlsv1.3= TLS_AES_256_GCM_SHA384 cipherlist= TLSv1.2:!SSLv2:@STRENGTH

Valid values

To use more than one cipher set, separate the values with colons.

Examples

sslservercipherlist cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

sslservercipherlist cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH

sslservercipherlist tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_SHA256:TLS_AES_128_CCM_8_SHA256

Default

Default cipherlist value for the cipher group cipherlist:

cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH

Default cipher suite value of the cipher group tlsv1.3:

tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

Used on

• GUI hosts
• Log hosts
• Policy server hosts
• Run hosts

📘

For more information, see Release Notes, cipherlist Values.

sslserverkeydir and sslserverkeyfile

• Version 4.0.0 and later: sslserverkeydir and sslserverkeyfile settings available.

The sslserverkeyfile and sslserverkeydir settings enable you to specify the location of a PEM- formatted private key for the server certificate file that is used by pbmasterd, pblocald, and pblogd to communicate with each other or with client programs.

If sslserverkeyfile is a full path name, then it is used for the private key. If sslserverkeyfile does not contain an absolute path, then sslserverkeydir is prepended to it.

The servers are not interactive, so the private keys should not be encrypted.

The private key file and the private key directory must be owned by root and no one else should have read or write permission.

If the key file and directory are not set, then the daemons look in the certificate file to see if the key is there. In this case, the certificate file and directory must be read-only and owned by root. No one else should have read or write permission.

📘

These settings enable the parameter substitutions shown in SSL parameter substitutions.

Example

sslserverkeyfile /secure/certificates/serverkeys/pbmasterd.pem
sslserverkeydir /secure/certificates/serverkeys
sslserverkeyfile pbmasterd.pem
sslserverkeydir /secure/certificates/serverkeys
sslserverkeyfile %N.pem

Defaults

/etc/<prefix>pbssl.pem<suffix>

Used on

• GUI hosts
• Log hosts
• Policy server hosts
• Run hosts

sslserververifysubject

• Version 4.0.0 and later: sslserververifysubject setting available.

sslserververifysubject contains a series of regular expressions to check against the client’s or other server’s certificates subject line. If the subject line matches all patterns, then the connection is allowed to proceed. If any of the patterns do not match, then the connection fails.

Example

This example verifies that the CN attribute (common name) matches the host name of the remote machine:

sslserververifysubject /CN=%R/

Example

This example verifies that the O attribute equals Company Name and the OU attribute starts with Technology:

sslserververifysubject '/O=Company Name/' /OU=Technology

ℹ️

Note

Single quotation marks should surround the attribute if there are embedded spaces.

Default

No default value

Used on

• GUI hosts
• Log hosts
• Policy server hosts
• Run hosts

Additional configuration to improve EPM

EPM-UL does not contain a Certificate Authority (CA), therefore certificates generated during install are self-signed, and cannot be used to properly identify the host.

Creating and deploying proper x509 certificates, with hostname information in the Subject Alternative Name field, allows hosts to properly identify hosts. TLS clients can verify the server’s certificate and hostname by adding the validateServer option to the ssloptions keyword in /etc/pb.settings. For TLS, pbmasterd and pblocald are clients to pblogd. Additionally, servers can validate the certificates and hostnames of the client hosts by adding the validateClient option to the ssloptions keyword in /etc/pb.settings.

Configure EPM to use the SSLFirst keyword in /etc/pb.settings. This keyword must have the same value on all hosts in the EPM domain. The SSLFirst keyword results in SSL/TLS occurring prior to any EPM proprietary protocol negotiations that use symmetric keys, reducing any issue with compromised symmetric networkencryption keys.

The TLS ciphers should be changed to disallow anonymous ciphers.

Edit the sslpbruncipherlist and sslservercipherlist entries in /etc/pb.settings:

sslpbruncipherlist      cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

sslservercipherlist     cipherlist=TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH tlsv1.3=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

Edit the ssl.cipher-list entry in /usr/lib/beyondtrust/pb/rest/etc/pblighttpd.conf:

ssl.cipher-list         = "TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH"

and

ssl.openssl.ssl-conf-cmd    = (
                    "MinProtocol" => " TLSv1.2",
                    "CipherString" => "TLSv1.2:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH",
                    "Ciphersuites" => "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
                              )

ℹ️

Note

EPM-UL version 21.1 and below of EPM-UL client registration uses TLSv1. Use below TLS protocol version to allow older versions of EPM-UL client registrations.

ssl.cipher-list = "HIGH:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH"

and

ssl.openssl.ssl-conf-cmd    = (
                    "MinProtocol" => " TLSv1",
                    "CipherString" => "HIGH:!SSLv2:!3DES:!MD5:!ADH:!AECDH:!DHE:!eNULL:@STRENGTH",
                    "Ciphersuites" => "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

In the following sections the diagram shows the SSL server and SSL client connections between pbmasterd, pblocald, pblogd and pbrun and the table shows the required certificate keywords in pb.settings file on each host when validateServer or validateClient is added to ssloptions.

SSL connections in default architecture: classic pbrun

* Mentioning sslpbruncafile with or without validateServer and validateClient options requires pbmasterd and pblocald certificates.

** Mentioning sslservercafile on a SSL client (pbmasterd and pblocald) with or without validateServer and validateClient options always requires certificates from its immediate SSL server or servers.

*** pblocald needs sslpbruncertfile and sslpbrunkeyfile to log finish event.

SSL connections in optimized runmode

* Mentioning sslpbruncafile with or without validateServer and validateClient options requires pbmasterd and pblogd certificates.

** Mentioning sslservercafile on pbmasterd with or without validateServer and validateClient options always requires certificates from pblogd.

SSL connections with noreconnect=1 in the policy

• noreconnect=1 : pbrun does not connect to pblocald directly

* Mentioning sslpbruncafile with or without validateserver and validateclient options requires pbmasterd certificates.

** Mentioning sslservercafile on a SSL client (pbmasterd and pblocald) with or without validateserver and validateclient options always requires certificates from its immediate SSL server or servers.

*** pblocald needs sslpbruncertfile and sslpbrunkeyfile to log finish event.

SSL connections with lognoreconnect=1 in the policy

• lognoreconnect=1 : pblocald does not connect to pblogd directly and pbrun does not connect to pblocald directly.

* Mentioning sslpbruncafile with or without validateServer and validateClient options requires pbmasterd certificates.

** Mentioning sslservercafile on pbmasterd with or without validateserver and validateclient options always requires certificates from pblocald and pblogd.

SSL connections with pbrunreconnection=1 in the policy

• pbrunreconnection=1 : pblocald listens for the connections that are initiated by pbrun under the control of pbmasterd.
• pbrunreconnection=0 : pbrun listens for the connections that are initiated by pblocald under the control of pbmasterd. This value is the default.

* Mentioning sslpbruncafile with or without validateserver and validateclient options requires pbmasterd and pblocald certificates.

** Mentioning sslservercafile on a SSL client (pbmasterd and pblocald) with or without validateserver and validateclient options always requires certificates from its immediate SSL server or servers.

*** pblocald needs sslpbruncertfile and sslpbrunkeyfile to log finish event.

SSL connections with pblogdreconnection=1 in the policy

• pblogdreconnection=1 : pblocald listens for the connections that are initiated by pblogd under the control of pbmasterd.
• pblogdreconnection=0 : pblogd listens for the connections that are initiated by pblocald under the control of pbmasterd. This value is the default.

* Mentioning sslpbruncafile with or without validateServer and validateClient options requires pbmasterd and pblocald certificates.

** Mentioning sslservercafile on a SSL client (pbmasterd and pblocald) with or without validateserver and validateclient options always requires certificates from its immediate SSL server or servers.

*** pblocald needs sslpbruncertfile and sslpbrunkeyfile to log finish event.