Network traffic and file encryption

EPM-UL can encrypt network traffic, event logs, I/O logs, policy files, and its own settings file. The following table lists the available encryption algorithms. If you are using SSL, then it supersedes the network traffic encryption algorithms after the start-up protocol is complete.

Encryption algorithms

Enhanced encryption

To enable compliance with US government regulations, and specifically FIPS 140-2, encryption has been updated. Many of the older less secure encryption algorithms are deprecated, and when high security is enforced, they are disabled completely.

When new clients are installed, enforcehighsecurity and ssl are both enabled in pb.settings. This switches EPM-UL into FIPS 140-2 mode. All encryption algorithms are FIPS 140-2 compliant, and it does not communicate, encrypt, or decrypt any data that isn't encrypted in AES-128, AES-192, AES-256 or TripleDes (3DES).

ℹ️

Note

If a customer is installing version 9 of EPM-UL from scratch, high security mode is recommended.

For existing customers who are upgrading their enterprise to version 9, the upgrade script automatically adds the AES-256 encryption algorithm onto the I/O log and event log encryption configuration, leaving the existing encryption algorithms at the end of the configuration. This ensures that new I/O logs and event logs are encrypted using modern secure algorithms, but allows existing I/O logs and event logs that are encrypted in less secure algorithms to be decrypted and retrieved. Although existing network encryption can continue to use deprecated encryption algorithms, because the data is transient, more permanent data such as I/O logs and event logs can only be encrypted in FIPS 140-2 compatible algorithms.

ℹ️

Note

Customers who have an existing infrastructure, and would like to be FIPS 140-2 compliant must upgrade all EPM-UL servers and clients to the latest version. If there are existing I/O logs and event logs that are encrypted using less secure algorithms, a specially configured host is required that is dedicated to reading these older logs.

To accomplish this task, you can use the new Client Registration feature to copy new pb.settings configuration, keys and certificates, or you can configure each installation by hand and copy the files manually.

Use client registration

1. Follow the upgrade guide to update the primary policy server to the latest version.
2. Create a new-style encryption key to be used across the enterprise:

   pbkey -F /etc/pbfips.key
   

3. Create a suitable client pb.settings file, for example /etc/pb-client.settings, and configure the new encryption settings:

enforcehighsecurity yes
ssl yes
ssloptions requiressl    sslfirst  sslverbose
sslservercertfile /etc/pbmasterhost.crt
sslserverkeyfile /etc/pbmasterhost.pem
networkencryption aes-256:keyfile=/etc/pbfips.key
iologencryption aes-256:keyfile=/etc/pbfips.key
eventlogencryption aes-256:keyfile=/etc/pbfips.key
submitmasters pbmasterhost.org.com
logservers pbloghost.org.com

4. Follow the Client Registration guide to enable the service and configure an appropriate client profile. For example, on the primary policy server run:

pbdbutil --reg -n
pbdbutil --reg -u '{"name":"client-prof","data":
[{"type":"settings","fname":"/etc/pb-client.settings"},
{"type":"certificate","to":"/etc/${prefix}pbrest.pem${suffix}"},
{"type":"save","sname":"networkencryption"},
{"type":"save","sname":"iologencryption"},
{"type":"save","sname":"eventlogencryption"},
{"type":"save","sname":"restkeyencryption"},
{"type":"save","sname":"sslservercertfile"},
{"type":"save","sname":"sslserverkeyfile"}]}'

5. Create similar profiles for your secondary policy servers, log servers, etc.
6. Create a REST application ID and Key to authenticate your Client Registration requests. For example, on the primary policy server run:

pbdbutil --rest -g clientreg
{"appkey":"cbbc1aab-6f2b-40d0-b611-060bff0aaafa"}

7. Follow the upgrade guide to upgrade each client and server, using Client Registration when prompted. Run the normal pbinstall on the client and when asked whether to use Client Registration, answer yes, and provide responses to the Client Registration configuration questions:

Do you wish to utilize Client Registration? [yes]?
Enter the Application ID generated on the Primary License Server: clientreg
Enter the Application Key generated on the Primary License Server: cbbc1aab-
6f2b-40d0-b611-060bff0aaafa
Enter the Primary License Server address/domain name for registering
clients: pbmasterhost.org.com
Enter the Primary License Server REST TCP/IP port [24351]: 24351
Enter the Registration Client Profile name [default]: client-prof

Using the profile appropriate to the installation type. All the necessary pb.settings, keys, and certificates are automatically copied to the upgrade installation, making upgrade simple.

Alternatively, these Client Registrations options can be specified on the pbinstall command line for automation.

Example

pbinstall -A clientreg -K cbbc1aab-6f2b-40d0-b611-060bff0aaafa -D
pbmasterhost.org.com -N client-prof

Without using client registration

1. Follow the upgrade guide to update the primary policy server to the latest version.
2. Create a new-style encryption key to be used across the enterprise:

   pbkey -F /etc/pbfips.key
   

3. For each upgrade you need to copy the new key, the primary policy manger certificate and the primary policy server key to each host.
4. During upgrade you need to change settings to enable high security mode:

   Enforce High Security Encryption? yes Use SSL? yes
   SSL Configuration? requiresslsslfirst  sslverbose
   SSLServer Certificate File? <path to Primary Policy Server certificate file>
   SSL Server Private Key File? <path to Primary Policy Server key file>
   PowerBroker network encryption options aes-256:keyfile=/etc/pbfips.key
   PowerBroker event log encryption options aes-256:keyfile=/etc/pbfips.key
   PowerBroker I/O log encryption options aes-256:keyfile=/etc/pbfips.key
   

To configure a dedicated host to read older I/O logs and event logs encrypted with deprecated encryption algorithms, the following configuration is required to ensure that it can communicate with the new FIPS 140-2 compliant installations, but allowing it to read the older logs. Follow the above installation procedures, but change the pb.setting configuration:

enforcehighsecurity no
ssl yes
ssloptions requiressl sslfirst sslverbose
sslservercertfile /etc/pbmasterhost.crt
sslserverkeyfile /etc/pbmasterhost.pem
networkencryption aes-256:keyfile=/etc/pbfips.key
iologencryption aes-256:keyfile=/etc/pbfips.key des:keyfile=/etc/oldpb.key
eventlogencryption aes-256:keyfile=/etc/pbfips.key
des:keyfile=/etc/oldpb.key

High security mode is not enabled, allowing the installation to read deprecated logs. SSL is enabled, with the correct configuration to allow the installation to communicate with the policy servers. The iolog and event log encryption must have FIPS 140-2 compatible algorithm specified if new logs are to written. However this can be left out if the sole purpose of the installation is to read older logs. Appended to the end of the iolog and event log encryption configuration are the details of the customers' existing encryption used when the logs were encrypted. EPM-UL selects the relevant algorithm when the logs are replayed.

Set the encryption algorithm and key

Starting with v8.0, the default encryption method is AES-256. If the encryption setting is commented out in the settings file, AES-256 encryption is used. Prior to v8.0, the default encryption method was DES.

Two parameters to consider when selecting an encryption algorithm are the block and key sizes

• The larger an algorithm’s block size, the more efficient it is.
• If an algorithm has multiple key sizes, then the larger the key, the more secure the algorithm.

A key must be generated for the use of encryption. The key must be the same on all the machines using the encryption.

• If the key changes, then all encrypted files are no longer readable.
• If the encryption algorithm changes, any encrypted files are no longer readable.

The iolog and eventlog files are encrypted by their writers and are decrypted by their readers. Policy files must be encrypted manually and are decrypted by their readers. The default is none (no files encrypted).

ℹ️

Note

The settings files must be encrypted manually. An unencrypted copy of the settings file should be kept offline because EPM-UL does not provide a decryption program for the settings file. The installation suite does not work correctly if the settings file is encrypted. The unencrypted file needs to be restored before performing an upgrade, or before running pbmakeremotetar or pbuninstall.

📘

For more information, see enforcehighsecurity, pbencode, pbkey.

enforcehighsecurity

• Version 8.0 and earlier: enforcehighsecurity setting not available.
• Version 8.5 and later: enforcehighsecurity setting available.

This enforces the use of more secure configuration, including using SSL for communications, FIPS 140-2 compliant symmetric encryption algorithms, an enhanced Pseudo Random Number Generator, and the use of the enhanced pb.key format.

ℹ️

Note

Only encryption algorithms that are accredited by FIPS 140-2 can be used for network and file encryption (for example, AES- 128, AES-192, AES-256 and tripledes). All others are deprecated.

Once this has been enabled the following pb.settings need to be configured:

• ssloptions requiressl sslfirst sslverbose
• sslengine
• sslservercertfile /etc/pbssl.pem
• sslcountrycode US
• sslprovince AZ
• ssllocality Phoenix
• sslorgunit Security
• sslorganization BeyondTrust

You also need to generate a new key using pbkey -F.

Example

enforcehighsecurity yes

Default

enforcehighsecurity yes

Used on

• Policy server hosts
• Submit hosts
• Run hosts

sslcountrycode

• Version 8.5.0 and earlier: sslcountrycode setting not available.
• Version 9.0.0 and later: sslcountrycode setting available.

Country code to use when creating x509 SSL client certificates. Used by Client Registration.

Example

sslcountrycode US

Default

sslcountrycode US

Used on

All hosts

sslprovince

• Version 8.5.0 and earlier: sslprovince setting not available.
• Version 9.0.0 and later: sslprovince setting available.

Province to use when creating x509 SSL client certificates. Used by Client Registration.

Example

sslprovince AZ

Default

sslprovince AZ

Used on

All hosts

ssllocality

• Version 8.5.0 and earlier: ssllocality setting not available.
• Version 9.0.0 and later: ssllocality setting available.

Locality to use when creating x509 SSL client certificates. Used by Client Registration.

Example

ssllocality Phoenix

Default

ssllocality Phoenix

Used on

All hosts

sslorgunit

• Version 8.5.0 and earlier: sslorgunit setting not available.
• Version 9.0.0 and later: sslorgunit setting available.

Organization unit to use when creating x509 SSL client certificates. Used by Client Registration.

Example

sslorgunit Security

Default

sslorgunit Security

Used on

All hosts

sslorganization

• Version 8.5.0 and earlier: sslorganization setting not available.
• Version 9.0.0 and later: sslorganization setting available.

Organization to use when creating x509 SSL client certificates. Used by Client Registration.

Example

sslorgunit BeyondTrust

Default

sslorgunit BeyondTrust

Used on

All hosts

networkencryption

• Version 5.1 and earlier: networkencryption setting not available.
• Version 5.2 and later: networkencryption setting available.

The networkencryption setting specifies one or more encryption settings for encrypting network traffic between hosts. The networkencryption setting uses the following syntax:

networkencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
    [:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]
    <algorithm-2>:<keyfile=/fullpath/data-file-2>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] ...

where:

• algorithm-n is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.
• startdate=yyyyy/mm/dd specifies the earliest date that this algorithm is to be used.
• enddate=yyyy/mm/dd specifies the latest date that this algorithm is to be used.

Within each encryption setting, each component is separated by a colon (:). Multiple encryption settings are separated by a space.

For successful communications between Endpoint Privilege Management hosts, each host must use the same encryption algorithm and data file, from which the encryption key is generated. To prevent service interruptions, you can specify multiple algorithms and keys on each host. The hosts resolve discrepancies as follows:

When one Endpoint Privilege Management program attempts to communicate with another, it uses the first valid algorithm/key pair (encryption algorithm type and encryption key derived from the data file) in the networkencryption setting. The receiving host then attempts to find the correct algorithm/key pair from its networkencryption setting.

Servers attempt to connect the first valid algorithm/data-file pair and, if that fails, the servers then attempt to use other valid algorithm/data-file pairs that are defined in the networkencryption entry in the settings file. We strongly recommend placing the best and newest algorithm/data-file pair as the first entry in the settings file in all servers. Also, the algorithm/data-file pairs must be listed in the same order for all servers.

A client that is not upgraded to the newest algorithm/data-file pair continues to be supported by the policy server host as long as the client’s algorithm/data-file pair is listed as a valid entry in the networkencryption setting. These clients continue to use the settings that are defined by the encryption keyword in the settings file, and the same initial algorithm/data-file pair is used during the initial connection between the two hosts.

If an algorithm/data-file pair is deprecated in the policy server host and it is the first item in the clients’ list of supported algorithm/data-file pairs, then the new clients recognize this change and respond by automatically updating their setting files and backing up the previous settings files. Then the new clients reconnect to the policy server host using an algorithm/data-file pair that is common to both the policy server host and the client. However, if an algorithm/data-file pair is deprecated in the policy server host and the encryption that is used by the policy server host is not supported by the client, then the client’s list must be manually upgraded or the initial connection will fail.

The starting date and ending dates are optional and are applied as follows:

• If the optional dates are used, then the algorithm/data-file pair is valid only during the specified time period.
• If a starting date is specified, then the algorithm/data-file pair takes effect at the start of that day; otherwise, the algorithm/data-file pair is active immediately.
• If an ending date is specified, the algorithm/data-file pair becomes inactive at the end of that date; otherwise, the algorithm/data-file pair never expires. The starting and ending dates are determined using Universal Coordinated Time (UTC) to eliminate ambiguity when the machines involved are in different time zones.

⚠️

Important

If the start and/or end date option is used, administrators must ensure that all hosts use the same validity period. Failure to do so will result in the hosts being unable to communicate with each other, or the hosts using other less desirable algorithm/data-file pairs that are common to both hosts, and the hosts must be synchronized. If all listed algorithms have expired (they have an end date and the end date has expired), then the default network algorithm (DES) is used unless one of the network encryptions is listed or the keyword none is specified with no end date.

This keyword supersedes the older encryption, keyfile, and encrypt keywords. The older settings are converted to the new standard when an upgrade installation occurs.

Example

networkencryption des:keyfile=/etc/pb.key:enddate=2008/05/31 aes-256:keyfile=/etc/pb.key.aes

This example setting directs the new client to use the DES encryption algorithm with the data file /etc/pb.key until May 31, 2008 (UTC). After that date, the new client is to use the AES-256 encryption algorithm with the data file /etc/pb.key.aes.

Default

The default encryption algorithm type is AES-256 and the default data file is typically /etc/pb.key.

Used on

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

eventlogencryption

• Version 5.1 and earlier: eventlogencryption setting not available.
• Version 5.2 and later: eventlogencryption setting available.

The eventlogencryption setting specifies one or more encryption settings for encrypting event logs. The eventlogencryption setting uses the following syntax:

eventencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
    [:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]
    <algorithm-2>:<keyfile=/fullpath/data-file-2>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] ...

where:

• algorithm-n is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.
• startdate=yyyyy/mm/dd specifies the earliest date that this algorithm is to be used.
• enddate=yyyy/mm/dd specifies the latest date that this algorithm is to be used.

Within each encryption setting, each component is separated by a colon (:). Multiple encryption settings are separated by a space.

⚠️

Important

When using multiple log servers, all log servers must use the same encryption algorithm and key. Otherwise, they cannot communicate with each other.

When an Endpoint Privilege Management program attempts to write to an event log, it checks to determine if the event log uses the same algorithm/key pair (encryption algorithm and encryption key derived from the data file) as when the event log was created. If so, the event is written to the event log; otherwise, the old event log is archived and a new event log is started using the first available algorithm/key pair in the eventlogencryption setting. Algorithm/key pairs that are not active can still be used to read existing files.

The starting date and ending dates are optional and are applied as follows:

• If the optional dates are used, then the algorithm/data-file pair is valid only for writing to files during the specified time period.
• If a starting date is specified, then the algorithm/data-file pair takes effect at the start of that day; otherwise, the algorithm/data-file pair is active immediately.
• If an ending date is specified, then the algorithm/data-file pair becomes inactive at the end of that date, otherwise, the algorithm/data-file pair never expires. The starting and ending dates are determined using Universal Coordinated Time (UTC) to eliminate ambiguity when the machines involved are in different time zones.

ℹ️

Note

This keyword supersedes the older encryption, keyfile, and encrypts keywords. The older settings are converted to the new standard when an upgrade installation occurs.

Example

eventlogencryption aes-256:keyfile=/etc/pb.key

This example uses AES-256 encryption algorithm type with the encryption data file that is located in /etc/pb.key.

Default

The default is no encryption.

Used on

Log hosts

iologencryption

• Version 5.1 and earlier: iologencryption setting not available.
• Version 5.2 and later: iologencryption setting available.

The iologencryption setting specifies one or more encryption settings for encrypting I/O logs. The iologencryption setting uses the following syntax:

iologencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
    [:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]
    <algorithm-2>:<keyfile=/fullpath/data-file-2>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] ...

where:

• algorithm-n is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.
• startdate=yyyyy/mm/dd specifies the earliest date that this algorithm is to be used.
• enddate=yyyy/mm/dd specifies the latest date that this algorithm is to be used.

Within each encryption setting, each component is separated by a colon (:). Multiple encryption settings are separated by a space.

⚠️

Important

Caution! When using multiple log servers, all log servers must use the same encryption algorithm and key. Otherwise, they cannot communicate with each other, and pbsync cannot merge partial I/O logs.

When an Endpoint Privilege Management program tries to write to an I/O log, it uses the first valid algorithm/key pair (encryption algorithm type and encryption key derived from the data file) in the iologencryption setting.

However, if the end date is reached and a session is still in place, the same algorithm/key pair is used until the end of the I/O log. If a session is abruptly terminated, then any new partial I/O log that is started will use a new algorithm/key pair. Algorithm/key pairs that are not active can still be used to read existing files.

The starting date and ending dates are optional and are applied as follows:

• If the optional dates are used, then the algorithm/data-file pair is only valid for writing to files during the specified time period.
• If a starting date is specified, then the algorithm/data-file pair takes effect at the start of that day; otherwise, the algorithm/data-file pair is active immediately.
• If an ending date is specified, then the algorithm becomes inactive at the end of that date, otherwise, the algorithm/data-file pair never expires.

The starting and ending dates are determined using Universal Coordinated Time (UTC). This eliminates ambiguity when the machines involved are in different time zones.

ℹ️

Note

This keyword supersedes the older encryption, keyfile, and encrypts keywords. The older settings are converted to the new standard when an upgrade installation occurs.

When an Endpoint Privilege Management program attempts to read an I/O log, it searches the list of algorithm/key pairs to find the one that corresponds to the target file.

Example

iologencryption des:keyfile=/etc/pb.key/des

Default

The default is no encryption.

Used on

Log hosts

reportencryption

• Version 5.1 and earlier: reportencryption setting not available.
• Version 5.2 and later: reportencryption setting available.

The reportencryption setting specifies one or more encryption settings for encrypting event log report control files. Each encryption setting consists of the encryption algorithm name, optional key file, optional starting date, and optional ending date using the following syntax:

reportencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
    [:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]
    <algorithm-2>:<keyfile=/fullpath/data-file-2>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] ...

where:

• algorithm-n is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.
• startdate=yyyyy/mm/dd specifies the earliest date that this algorithm is to be used.
• enddate=yyyy/mm/dd specifies the latest date that this algorithm is to be used.

Within each encryption setting, each component is separated by a colon (:). Multiple encryption settings are separated by a space.

A list of algorithm/key pairs can be provided, but only the first valid entry is used for encryption purposes; all other entries are used as historical references to decrypt the report file. Algorithm/key pairs that are not active can still be used to read existing files.

The starting date and ending dates are optional and are applied as follows:

• If the optional dates are used, then the algorithm/data-file pair is only valid for writing to files during the specified time period.
• If a starting date is specified, then the algorithm/key data-file takes effect at the start of that day; otherwise, the algorithm/key data-file is active immediately.
• If an ending date is specified, then the algorithm becomes inactive at the end of that date; otherwise, the algorithm/key data-file never expires.

The starting and ending dates are reckoned using Universal Coordinated Time (UTC). Doing so eliminates ambiguity when the machines are in different time zones.

ℹ️

Note

This keyword supersedes the older encryption, keyfile, and encrypts keywords. The older settings are converted to the new standard when an upgrade installation occurs.

Example

reportencryption saferplus-32:keyfile=/etc/pb.key.sp32

Default

The default is no encryption.

Used on

Log hosts

policyencryption

• Version 5.1 and earlier: policyencryption setting not available.
• Version 5.2 and later: policyencryption setting available.

The policyencryption setting specifies one or more encryption settings for encrypting policy files. Each encryption setting consists of the encryption algorithm name, optional key file, optional starting date, and optional ending date using the following syntax:

policyencryption <algorithm>:<keyfile=/fullpath/data-file>

where:

• algorithm is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.

When pbencode attempts to write to a policy file, it uses the algorithm/key pair (encryption algorithm type and encryption key derived from the data file) in the policyencryption setting. When an Endpoint Privilege Management program attempts to read a policy file, it also uses the algorithm/key pair in the policyencryption setting.

ℹ️

Note

This keyword supersedes the older encryption, keyfile, and encrypts keywords. The older settings are converted to the new standard when an upgrade installation occurs.

Example

policyencryption tripledes:keyfile=/etc/pb.key.3des

We recommend that you keep an unencrypted, offline copy of the policy file in the event you need to manually modify the file.

Default

The default is no encryption.

Used on

Policy server hosts

settingsencryptiontype

• Version 5.1 and earlier: settingsencryptiontype setting not available.
• Version 5.2 and later: settingsencryptiontype setting available.

The pb.settings file can be encrypted using the encryption algorithm type that is specified in the settingsencryptiontype keyword in the pb.settings file, using the following syntax:

settingsencryptiontype <algorithm>

The settings file is encrypted and decrypted using the default encryption key which is derived from the data file that is located in /etc/pb.key, and the encryption algorithm type that is defined in the settingsencryption keyword.

⚠️

Important

We recommend you keep an unencrypted copy of the settings file in a secure location.

ℹ️

Note

This keyword supersedes the older encryption, keyfile, and encrypts keywords. The older settings are converted to the new standard when an upgrade installation occurs.

Example

settingsencryptiontype des

In this example, DES is the encryption algorithm type to be used to encrypt the pb.settings file.

Default

The default is no encryption.

Used on

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

dbencryption

• Version 8.5 and earlier: dbencryption setting not available.
• Version 9.0 and later: dbencryption setting available.

The dbencryption setting specifies the encryption for databases created by EPM-UL (for example: clntregdb, eventdb, svccachedb, logarchivedb, et. al).

The dbencryption setting uses the following syntax:

dbencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] 
<algorithm-2>:<keyfile=/fullpath/data-file-2>[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>] ...

where:

• algorithm-n is the name of the algorithm type.
• /fullpath/data-file (optional) specifies the full path and file name of the data file, which is used to dynamically derive the encryption key.
• startdate=yyyyy/mm/dd specifies the earliest date that this algorithm is to be used.
• enddate=yyyy/mm/dd specifies the latest date that this algorithm is to be used.

Within each encryption setting, each component is separated by a colon (:). Multiple encryption settings are separated by a space.

Default

none

Used on

All hosts