Secure Socket Layers and Public Key infrastructure | EPM-UL

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.

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

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.

Before enabling ssloptions ClientCertificates or ssloptions validateClient on servers, ensure that all client/submit hosts (for example, hosts running pbrun, pbsh, or pbksh are configured with a certificate authority (CA), a client certificate, and a client private key.

BeyondTrust does not guarantee that all client hosts have client certificates provisioned (for example, immediately after a new install or after upgrading to use managed certificates). If you enable ClientCertificates or validateClient on servers before updating clients, any client host that does not have a valid certificate and key configured will fail to connect.

On each client/submit host, configure the settings in pb.settings:

• sslpbruncadir or sslpbruncafile: CA used to validate servers (and optionally the chain)
• sslpbruncertfile or sslpbruncertdir: PEM-format client certificate
• sslpbrunkeyfile or sslpbrunkeydir: PEM-format client private key

On each server host that enforces client validation, configure:

• sslservercafile or sslservercadir: CA that issued/signed the client certificates
• sslservercertfile/ sslserverkeyfile (or sslservercertdir / sslserverkeydir): Server certificate and key

Do not enable ClientCertificates or validateClient until these prerequisites are met on all relevant hosts.

Examples

Supported combinations

ssloptions AllowNonSSL
ssloptions requiressl sslfirst
ssloptions ClientCertificates
ssloptions AllowNonSSL ClientCertificates

Unsupported combination

ssloptions allownonssl sslfirst

Default

requiressl

Used on

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

X509 certificates

Prior to v26.1, a customer could forego the use of their own certificates in favor of EPM-UL default self-signed certificates. Starting with v26.1, EPM-UL establishes a per-installation Public Key Infrastructure (PKI).

• The first (primary/license) server generates a self-signed Root Certificate Authority (Root CA) certificate, which becomes the trust anchor for the entire installation.
• Policy and log servers that can act as registration servers each receive a Subordinate CA certificate signed by the Root CA (or by another subordinate CA), and all servers and client endpoints receive individual CA-signed certificates for use in TLS communication.
• Certificate and hostname validation are now fully enforced for connections using these new certificates.

The new EPM-UL Public Key Infrastructure is only used in cases when the customer doesn't use their own certificates for secure EPM-UL communication.

Certificates commands and options are used in pbinstall, pbregister, and pbdbutil info.

Certificate types

X509 certificates used by EPM-UL:

• Unknown: Type that cannot be identified as an EPM-UL generated certificate, including customer generated and managed certificates.
• Legacy: By default, self-signed certificates generated by EPM-UL during installation of earlier versions.

Starting in 26.1.0, added certificate types:

• New client: A CA signed certificate issued to clients or endpoints for use in TLS communication.
• New server: A CA signed certificate issued to EPM-UL servers (license server, policy server, log server, etc.) for use in TLS communication.
• New CA: A certificate issued to EPM-UL servers capable of acting as registration servers for use in signing other certificates. It will have been signed by either some other new CA certificate in the customer's installation or by the root CA itself.
• New Root CA: The certificate to be deemed the root of all trust for a given customer installation. This will be self-signed, and must be securely transported to any system needing to interact with EPM-UL, such as endpoints, other EPM-UL servers, and BIUL.

Starting in 26.2.0, added:

• crl_signer: A certificate used for delegated revocations.

Determine the type of certificate using pbdbutil with command line options:

pbdbutil --info --certtype </path/file>

Certificate lifetimes

Default lifetimes for certificates:

• Root CA certificates: 15 years
• Sub CA certificates: 5 years
• Server CA certificates: 3 years
• Endpoint certificates: 13 months

For the initial release, pbinstall will allow changing the certificate lifetime values only on the first (or primary) server using a new command line option.

Certificate revocation

Starting in 26.2.0, you can revoke a certificate that EPM-UL issued. Revoke the certificate for a lost laptop, a decommissioned server, or any host whose private key may be exposed, and that host can no longer take part in EPM-UL communication. pbrun fails when it tries to use a revoked certificate.

Typically you revoke a certificate on the server that issued it. If the issuing server can no longer revoke, use delegated revocation on another system, described in the following section. A revocation is valid only when carried in a certificate revocation list (CRL) signed by the issuing certificate authority (CA), so requests made on any other server are refused.

Revoke a certificate

1. On the issuing server, list the certificates to find the one you want. Certificates issued to endpoints have the type client.

   pbdbutil --cadata -lll -P

2. Revoke the certificate using its id and a reason code.

   pbdbutil --cadata --revoke '{"id": "<id>", "reason": 1}'

To revoke every certificate issued to one machine in a single command, give the machine's UUID or hostname instead of a certificate id:

pbdbutil --cadata --revoke '{"machine": "<uuid-or-hostname>", "reason": <code>}'

Reason codes. The reason is an integer as defined in RFC 5280 section 5.3.1. Values 1 through 10 are accepted, except 7, which is not used. Two values have a special meaning:

• 6 (certificateHold) marks a revocation you can undo later.
• 8 (removeFromCRL) undoes a hold, dropping the certificate from the CRL so you can contact the affected system again without issuing it a new certificate.

Restore a host after revocation. If you revoked the certificate with reason 6, revoke it again with reason 8 to release the hold. The host can then connect again with no further changes.

For any other reason code, issue the host a new certificate as if you were installing it fresh:

rm /etc/pmul_root_ca.pem
rm /etc/pbssl*.pem
pbdbutil --certops --update '{"fingerprint": "<root-ca-fingerprint>", "appid": "<appid>", "appkey": "<appkey>"}'

Additional optional arguments to pbdbutil --certops --update include:

• "hostname": "" # optional hostname of the Registry Manager REST service
• "port":
• "rootCA": <true|false> # specify true to update the first installed server to be the root CA; default is false

How quickly a revocation takes effect

EPM-UL distributes revocation data to your hosts as CRLs, so a revocation reaches the rest of the installation shortly after you make it:

• Other servers usually have the update within seconds. The issuing server rewrites its CRL as soon as you revoke a certificate and tells the other servers. A check every fifteen minutes covers any notification that goes missing.
• Clients refresh while setting up their next outbound connection. A client connecting to a server that holds newer revocation data fetches it immediately. Otherwise a client checks its configured license, policy and log for updates at most once every seven and a half minutes.

A client machine can connect to any one server and receive every CRL currently in force, no matter which server issued the certificates they cover.

Verification is deliberately tolerant of a missing or stale CRL. EPM-UL reports that condition and allows the connection but a certificate that appears in a CRL is always rejected.

Use CRLs from your own PKI

If you issue your own certificates, revoke them in your own PKI and then place the updated CRL file in the CRL directory (/opt/pbul/crls by default) on any one of your servers. EPM-UL then:

• Distributes the file to all servers that might serve it.
• Distributes the file to clients to use for their connections.
• Rejects certificates that your PKI administrator marked as revoked.

CRL files must be valid and conform to RFC 5280, and must use the longer ASCII PEM format rather than the shorter binary DER format. Some CAs publish their CRLs in DER format, so check the format before you copy a file across.

Delegated certificate revocation

Normally, only the certificate authority (CA) that issued a certificate can revoke it; the revocation must be signed with that authority's private key. This creates a gap: if a certificate server is destroyed, decommissioned unexpectedly, or replaced, the certificates it issued cannot be revoked by any other machine. They remain valid until they naturally expire.

Delegated certificate revocation closes that gap. The file locations for the delegated CRL's signing credential are set in the crlsigncert and crlsignkey settings, whose defaults, respectively, are pmul_crlsign.pem and pmul_crlsign.key in the server CA directory (typically /etc).

How it works

Each EPM-UL server that issues certificates is assigned a CRL signing certificate. This certificate:

• Authorizes only one action: signing Certificate Revocation Lists (CRLs)
• Is not itself a certificate authority
• Chains to the same enterprise root as all other certificates in your installation
• Is created automatically when the machine registers or when its certificates are updated
• Is stored in the CA directory, identified by the crlsigncert and crlsignkey settings

If the CRL signing certificate cannot be created or obtained during registration, the system reports that the machine cannot revoke certificates it did not issue, then continues normally. No other functionality is affected.

How revocations are signed

When you revoke a certificate, EPM-UL chooses how to sign the revocation based on which authority originally issued it:

When the CRL signing certificate is used, the result is an indirect CRL. A revocation list that:

• Explicitly identifies itself as indirect
• Includes the name of the CA that originally issued each revoked certificate
• Is published alongside that authority's own revocation list
• Uses a filename that identifies both the authority it covers and the machine that signed it

This naming convention means multiple machines can publish revocations for the same lost authority without overwriting each other.

How revocations are distributed and validated

Indirect CRLs are distributed through the same channels and on the same schedule as all other revocation lists. No special steps required.

When EPM-UL validates a certificate, it checks for indirect CRLs covering that certificate's issuer. A revocation entry in an indirect CRL is honored only if all of the following are true:

• The machine that signed the list can be identified locally
• That machine is authorized to sign revocation lists
• That machine chains to a root certificate already installed on the validating machine

If any of these conditions are not met, the revocation list is ignored.

Revoke a certificate from a lost authority

To revoke a certificate that was issued by a CA that is no longer available:

1. Run the revocation on any certificate-issuing server in your installation.
2. Use the command: pbdbutil --cadata --revoke with either the certificate's record ID or the machine name.

Requirements:

• The certificate's record must exist in the local CA database (standard database synchronization provides this).
• The certificate must be one of the following types: client, server, sub-CA, or CRL signing certificate.
• Root CA certificates cannot be revoked this way.

Important limitations and considerations

Delegated revocation restores the ability to withdraw a lost authority's certificates. It does not restore the ability to issue new ones.

Keep the following in mind:

• Re-establishing a lost CA still requires either a backup of its private key, or setting up a new authority and re-enrolling affected machines.
• Any machine holding a valid CRL signing certificate can revoke any certificate in the installation. Treat certificate-issuing servers with appropriate access controls.
• Revocations, other than those made for reason 6 (revocation placed on hold), cannot be reversed once published.

Keywords

• cadatadb: The base name of the certificate authority database. By default it's pbcadata.db which resides in the PMUL database directory which, by default, is /opt/pbul/dbs.

• rootcakey: x509 private key for the Root Certificate Authority.

• rootcacert: x509 public certificate for the Root Certificate Authority. This certificate is distributed to all hosts, so they can verify certificates.

• sslservercakey: x509 private key for EPM-UL servers (pbmasterd, pblogd, pblocald, license server).

• sslservercacert: x509 public certificate for EPM-UL servers (pbmasterd, pblogd, pblocald, license server).

• sslcertcheckdays: The number of days prior to certificate expiration to attempt renewals. The default for this value is 30.

• certificatelifetimes: To override the default certificate lifetimes, this setting can define the custom valid periods for each type of certificate. The value is a list of one or more space-separated combinations of the following:

ca|subca|sca|server|svr|client|clnt=<number>[y|m|w|d]

Example

certificatelifetimes ca=10y sca=5y svr=3y clnt=2y

• certbackdateskew: The amount by which EPM-UL backdates the start of a certificate's validity period when it writes the file. Backdating absorbs small clock differences between machines in the installation. The default is 300 seconds (5 minutes).

• crldir: The directory that holds certificate revocation list (CRL) files. By default it's /opt/pbul/crls. Place CRL files from your own PKI in this directory.

• crlrefreshinterval: How often, in minutes, an issuing server checks whether it needs to rewrite its own CRL files. The default is 1440 minutes (1 day). A fixed one-day window also applies, so a value below 1440 makes the check run more often without rewriting the CRL. This setting does not control how often a client or another server fetches a CRL.

• crlbackdateskew: The amount by which EPM-UL backdates the start of a CRL's validity period when it writes the file. Backdating absorbs small clock differences between machines in the installation. The default is 600 seconds (10 minutes).

• crlsigncert: The certificate EPM-UL uses to sign a certificate revocation list on behalf of a certificate authority whose signing key this machine does not hold. EPM-UL signs with the machine's own CA certificate whenever it can, and uses crlsigncert only for certificates issued elsewhere. When using this setting, the generated CRL is an indirect CRL that names the original issuer for each entry. The value is a file name resolved against sslservercadir, and the certificate is created when the machine registers with the certificate server. The default is /etc/pmul_crlsign.pem.

• crlsignkey: The private key matching crlsigncert. EPM-UL reads it only when signing a certificate revocation list on behalf of another certificate authority, so machines that have never been given that role do not have one. The value is a file name resolved against sslservercadir, and the key is created alongside the certificate when the machine registers. The default is /etc/pmul_crlsign.key.

• cadatadbrefreshinterval: How often, in minutes, a certificate-issuing server reconciles its local pbcadata.db with the other issuing servers. The default is 10 minutes.

• cadatadbmaxsyncpeers: The maximum number of peer servers contacted in one certificate database synchronization pass. The default is 0, which derives a limit from the number of servers you have set up. The maximum is 1024.

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.

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.

Trusted CA directory path

By default, EPM-UL uses /etc/pbcerts as the trusted root CA directory for client tools such as pbrun. If you change sslservercadir to a non-default location (for example, to align with your PKI standards), ensure one of the following is true:

• The default directory /etc/pbcerts exists on upgraded systems, or
• The client trusted CA directory setting sslpbruncadir matches sslservercadir

If neither condition is met, client tools may still report a missing /etc/pbcerts directory even though the server CA directory was changed.

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.

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 algorithms to use for encryption. Use the sslpbruncipherlist setting 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.

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.

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

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.

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.

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 algorithms to use for encryption. Use the sslservercipherlist setting 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

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.

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

Default

No default value

Used on

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

Additional configuration to improve EPM

As of version 26.1, EPM-UL no longer generates self-signed certificates in cases where customers do not provide their own certifictates. Instead, EPM-UL now establishes a built-in public key infrastructure (PKI) whereby all certificates other than the EPM-UL root Certificate Authority (CA) are in a trust chain leading up to that root CA. If the customer uses this new default public key infrastructure, rather than their own certificates, then TLS certificate and hostname validation will be fully enforced for connections using these new certificates.

Although the new EPM-UL PKI siginficantly enhances connection security compared to prior versions, there are additional actions that the customer may optionally take to enhances security. These are discussed in the remainder of this section.

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"
                              )

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.

Use your own certificates

Starting in EPM-UL 26.1.0, you can deploy EPM-UL using certificates that are issued by, or chained to, your existing enterprise certificate authority (CA), instead of relying on the self-signed certificates created during install.

Use this configuration when:

• Your organization uses an internal PKI, and
• Policy requires that TLS certificates used by EPM-UL are issued by, or chained to, that PKI.

  ℹ️

  Note

  EPM-UL does not support arbitrary customer self-signed endpoint or server certificates. Certificates must chain to a trusted CA.
  At a minimum:

  • Configure server-side certificates and keys using sslservercertfile and sslserverkeyfile.
  • Configure client-side certificates and keys using sslpbruncertfile and sslpbrunkeyfile, where required.
  • Configure trusted CA locations using sslpbruncadir / sslpbruncafile and sslservercadir / sslservercafile.

During installation, you can prevent automatic certificate creation and point EPM-UL at your own PKI by using the following pbinstall options:

• -n no to skip checking and auto-creation of default certificates and keys.
• -H rootcacert=<path> / -H rootcakey=<path> to specify your Root CA certificate and key.
• -V sslservercacert=<path> / -V sslservercakey=<path> to specify your server SubCA certificate and key.
• Avoid using -k if you want to retain existing customer-managed certificates, because -k overwrites self-signed certificates with new EPM-UL CA-signed certificates.

SSL architectures

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.