Configure OpenSSL directives

Last updated
Save as PDF

Use this information to configure OpenSSL in your EZproxy config.txt file.

EZproxy 7.3 was built with the most current Long Term Support release of OpenSSL (3.0.11t).

By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The default SSLCipherSuite string remains unchanged from v6.3.5.

SSL directives

The following directives can be used to customize OpenSSL settings.

Directive Values Description

Directive	Values	Description
`SSLCipherSuite`	OpenSSL ciphers	In EZproxy 6.3.5 and later, SSLCipherSuite defaults to the following values: ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2:!RC4 Additional values can be appended or used to replace those in the default to customize EZproxy OpenSSL security settings. This directive should be placed before any LoginPortSSL statement in config.txt.
`SSLHonorCipherOrder`	`On Off`	Assigning this directive a value `On` indicates that the EZproxy server should choose the cipher to use when accepting incoming secure connections. Assigning this directive a value `Off` indicates that EZproxy should use the client's preferred cipher when accepting incoming secure connections.
`SSLOpenSSLConfCmd`	Supported Configuration File Commands	This directive allows OpenSSL-specific commands to be used to control advanced settings of OpenSSL.

SSLCipherSuite

OpenSSL ciphers

In EZproxy 6.3.5 and later, SSLCipherSuite defaults to the following values:

ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2:!RC4

Additional values can be appended or used to replace those in the default to customize EZproxy OpenSSL security settings. This directive should be placed before any LoginPortSSL statement in config.txt.

SSLHonorCipherOrder

On

            Off

Assigning this directive a value On indicates that the EZproxy server should choose the cipher to use when accepting incoming secure connections.

Assigning this directive a value Off indicates that EZproxy should use the client's preferred cipher when accepting incoming secure connections.

SSLOpenSSLConfCmd Supported Configuration File Commands This directive allows OpenSSL-specific commands to be used to control advanced settings of OpenSSL.

Supported OpenSSL parameters

The following OpenSSL parameters are compatible with EZproxy.

Parameters	Values	Description
Diffie-Hellman parameters	dhparam	These parameters can now be included within a key file in the SSL subdirectory. Such values can be generated with the OpenSSL dhparam command.
Elliptical Curve parameters	ecparam	These parameters can now be included within a key file in the SSL subdirectory. Such values can be generated with the OpenSSL ecparam command.

Previous versions

Details about previous versions of EZproxy and compatibility with OpenSSL can be found below.

EZproxy V7.2

EZproxy 7.2 was built with the most current Long Term Support release of OpenSSL (1.1.1j). It supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

Inbound connections from browsers support ECDHE-RSA-AES256-GCM-SHA384 and ECDHE-RSA-AES128-GCM-SHA256.
Outbound connections to content providers default to a more tolerant configuration of ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2:!RC4 . This change avoids breaking connectivity to content providers that may not have raised their minimum standards to EZproxy's new default.
The outbound requirements can be increased to match the new inbound default with the directive:

SSLCipherSuite -outbound ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256

Although this should no longer be necessary, if TLS 1.1 is required in either direction, it can be enabled with either or both of these directives:

SSLOpenSSLConfCmd -inbound MinProtocol TLSv1.1

SSLOpenSSLConfCmd -outbound MinProtocol TLSv1.1

The default SSLCipherSuite string remains unchanged from v6.3.5.

EZproxy V7.1.17

EZproxy 7.1.17 was built with the most current Long Term Support release of OpenSSL (1.1.1j). It supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The default SSLCipherSuite string remains unchanged from v6.3.5.

EZproxy V7.1

EZproxy v7.1 was built with OpenSSL 1.1.1i, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The default SSLCipherSuite string remains unchanged from v6.3.5.

EZproxy V7.0.16

EZproxy v7.0.16 was built with OpenSSL 1.1.1f, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The default SSLCipherSuite string remains unchanged from v6.3.5.

EZproxy V6.5.2

EZproxy v6.5.2 was built with OpenSSL 1.0.2q, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The new default SSLCipherSuite string unchanged from v6.3.5.

EZproxy V6.3.5

EZproxy v6.3.5 was built with OpenSSL 1.0.2m, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

RC4
SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

The new default SSLCipherSuite string is:

ALL: !EXPORT: !LOW: !aNULL: !eNULL: !SSLv2: !RC4

EZproxy V6.2.2

EZproxy v6.2.2 was built with OpenSSL 1.0.2j, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

EZproxy V6.1.16

EZproxy v6.1.16 was built with OpenSSL 1.0.2h, so it supports TLS 1.0, 1.1, and 1.2. By default, the following encryption/security options are disabled:

SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

EZproxy V6.0.8

By default, the following encryption/security options are disabled:

SSLv2
SSLv3
40 bit encryption keys
56 bit encryption keys

Previously these options had to be disabled manually with directives in config.txt.

The new default SSLCipherSuite string is:

HIGH:MEDIUM:!ADH:!Anull:!LOW:!EXP:!SSLv2:@STRENGTH

All other settings available in EZproxy V5.7.44 are available in EZproxy V6.0.8.

EZproxy V5.7.44

EZproxy 5.7.44 supports TLS 1.0. By default however, SSLv2 is enabled, and this must be manually disabled to make TLS 1.0 the default. For more details on SSL 2 and SSL 3, please see http://en.wikipedia.org/wiki/Transpo...2C_2.0_and_3.0. This article also describes transport level security (TLS), the successor to SSL 2 and SSL 3. By default, the following encryption/security options are disabled:

SSLv3

By default, the following encryption/security options are enabled:

SSLv2

The following config.txt statements control the SSL/TLS options your instance of EZproxy will use.

Directive Values Description

Option Disable SSLv2 NA By default, EZproxy V5.7.44 disables SSL 3 and enables SSL 2. Because EZproxy V5.7.44 supports TLS 1.0 for client to webserver interactions, OCLC recommends that you also disable SSL 2 in addition to the default-disabled SSL 3.To do this, place Option DisableSSLv2 before any LoginPortSSL statements in your config.txt file. After disable SSL and retaining the default setting of disabled SSL 3, you EZproxy will default to TLS 1.0.

Directive	Values	Description
`Option Disable SSLv2`	NA	By default, EZproxy V5.7.44 disables SSL 3 and enables SSL 2. Because EZproxy V5.7.44 supports TLS 1.0 for client to webserver interactions, OCLC recommends that you also disable SSL 2 in addition to the default-disabled SSL 3.To do this, place Option DisableSSLv2 before any LoginPortSSL statements in your config.txt file. After disable SSL and retaining the default setting of disabled SSL 3, you EZproxy will default to TLS 1.0.
`SSLCipherSuite`	Cipher Strings	SSLCipherSuite offers finer-grained control over SSL/TLS options. We use OpenSSL as our security library layer, and SSLCipherSuite options are passed directly to OpenSSL for processing. EZproxy V5.7.44 supports all of the cipher settings defined by OpenSSL Cipher Strings. SSLCipherSuite was introduced with the first V5.7 release. OCLC recommends updating to V5.7.44 if you use SSLCipherSuite. For more details about SSLCipherSuite values and EZproxy directives, see SSLCipherSuite below.
`Option EnableSSLv3`	NA	SSL 2 and SSL 3 are older protocol definitions that normally should not be used. We provide the ability to use them since some legacy environments may need them. If you are using an environment that requires SSL 3, you can force EZproxy to use this protocol by entering Option EnableSSLv3 before an LoginPortSSL statements in your config.txt file, but this is not the recommended setting.

SSLCipherSuite

Cipher Strings

SSLCipherSuite offers finer-grained control over SSL/TLS options. We use OpenSSL as our security library layer, and SSLCipherSuite options are passed directly to OpenSSL for processing. EZproxy V5.7.44 supports all of the cipher settings defined by OpenSSL Cipher Strings.

SSLCipherSuite was introduced with the first V5.7 release. OCLC recommends updating to V5.7.44 if you use SSLCipherSuite. For more details about SSLCipherSuite values and EZproxy directives, see SSLCipherSuite below.

Option EnableSSLv3 NA SSL 2 and SSL 3 are older protocol definitions that normally should not be used. We provide the ability to use them since some legacy environments may need them. If you are using an environment that requires SSL 3, you can force EZproxy to use this protocol by entering Option EnableSSLv3 before an LoginPortSSL statements in your config.txt file, but this is not the recommended setting.

SSLCipherSuite

If SSLCipherSuite is present in config.txt, and no values are defined for this directive, EZproxy defaults to the values:

SSLCipherSuite HIGH:MEDIUM:LOW:EXP:!ADH:!aNULL

The table below provides additional directives that influence the SSLCipherSuite string.

Directive	Values appended to default
`Option DisableSSL56bit`	`:!LOW!EXP`
`Option DisableSSL40bit`	`:!EXP`
`Option DisableSSL40bit` OR `Option DisableSSLv2`	`:!SSLv2`

After any of the above changes are applied, EZproxy always appends to the default string:

:@STRENGTH

Note: EZproxy supports the following formats for the SSLCipherSuite directive:

A separate entry for inbound and outbound suites as follows:

SSLCipherSuite -inbound (inboundsuite)

and/or:

SSLCipherSuite -outbound (outboundsuite)

EZproxy also supports a combined entry with a shared suite (the CipherSuite for both inbound and outbound must be the same):

SSLCipherSuite -inbound -outbound (sharedsuite)

EZproxy does not allow a single entry with a separate inbound suite and an outbound suite. Where the inbound and outbound suites are intended to be different. The following example is not allowed:

SSLCipherSuite -inbound (inboundsuite) -outbound (outboundsuite)

DES and AES Encryption

EZproxy supports, 40 bit encryption, 56 bit encryption, and 128, 192 and 256 bit AES encryption. Encryption keys define the size of the cipher used to encrypt data transmitted via SSL/TLS over https: connections.

40 and 56 bit encryption should be disabled by default; however, OCLC provides 40 and 56 bit encryption for legacy purposes. OCLC recommends that you disable 40 and 56 bit encryption unless you have specific legacy requirements.

To disable 40 bit encryption, add the following statement to your config.txt file:

Option DisableSSL40bit

To disable 56 bit encryption, add the following statement to your config.txt file:

Option DisableSSL56bit