|
Creates
an SSL environment.
Format #include <gskssl.h>
gsk_status gsk_environment_open (
gsk_handle * env_handle)
Parameters- env_handle
- Returns the handle for the environment. The application should
call the gsk_environment_close() routine to release the environment
when it is no longer needed.
ResultsThe function return value will be
0 ( GSK_OK) if no error is detected. Otherwise, it will be one
of the return codes listed in the gskssl.h include file. These
are some possible errors: - [GSK_ATTRIBUTE_INVALID_ENUMERATION]
- The value of an environment variable is not valid.
- [GSK_ATTRIBUTE_INVALID_LENGTH]
- The length of an environment variable value is not valid.
- [GSK_ATTRIBUTE_INVALID_NUMERIC_VALUE]
- The value of an environment variable is not valid.
- [GSK_INSUFFICIENT_STORAGE]
- Insufficient storage is available.
UsageThe gsk_environment_open() routine
creates an SSL environment. The environment will be initialized with
default values and then any SSL environment variables will be processed.
These values can be changed by the application using the appropriate gsk_attribute_set_*() routines.
The gsk_environment_init() routine should then be called to
initialize the SSL environment. This environment can then be used
to establish one or more SSL connections.
When not executing
in FIPS mode, the following default values are set: - SSL V2, SSL V3, and TLS V1.0 are enabled (TLS V1.1 and TLS
V1.2 are disabled by default)
- The connection type is set to CLIENT
- The SSL V2 connection timeout is set to 100 seconds
- The SSL V3 connection timeout is set to 86400 seconds
- The SSL V2 cache size is set to 256
- The SSL V3 cache size is set to 512
- The sysplex session cache is disabled
- The default key will be used
- No revoked certificate checking performed
- The default callback routines will be used
- The SSL V2 cipher specification is set to "713642" if United
States only encryption is enabled and "642" otherwise
- 2-character cipher definitions in GSK_V3_CIPHER_SPECS will be
used for SSL V3 cipher values
- The SSL V3 cipher specification is set to "050435363738392F303132330A1613100D0915120F0C0306020100"
if United States only encryption is enabled and "0915120F0C0306020100"
otherwise
- The supported elliptic curve list is set to "00210023002400250019"
- The signature algorithm pair list is set to "0601060305010503040104030402030103030201020302020101"
- No TLS extensions are initialized
- Suite B is disabled.
When executing in FIPS mode, the following default values
are set: - TLS V1.0 is enabled (TLS V1.1 and TLS V1.2 are disabled
by default)
- The connection type is set to CLIENT
- The connection timeout is set to 86400 seconds
- The cache size is set to 512
- The sysplex session cache is disabled
- The default key will be used
- No revoked certificate checking performed
- The default callback routines will be used
- 2-character cipher definitions in GSK_V3_CIPHER_SPECS will be
used for SSL V3 cipher values
- The cipher specification is set to "35363738392F303132330A1613100D"
- The supported elliptic curve list is set to "00210023002400250019"
- The signature algorithm pair list is set to "060106030501050304010403040203010303020102030202"
- Suite B is disabled.
See Table 1 for
a list of supported SSL V2 cipher specifications.
See Table 2 for a list of supported 2-character
SSL V3 cipher specifications.
See Table 3 for a list of supported 4-character
SSL V3 cipher specifications.
See Table 5 for a list of supported 4-character
elliptic curve specifications.
Applications wanting to use
cipher suites that use elliptic curve certificates must set an appropriate
cipher specification in GSK_V3_CIPHER_SPECS_EXPANDED. If an application
requires an SSL V3, TLS V1.0, or higher session to use the
4-character cipher suites specified in GSK_V3_CIPHER_SPECS_EXPANDED
then it must explicitly call gsk_attribute_set_enum() and set
the enumeration identifier GSK_V3_CIPHERS to have a value of GSK_V3_CIPHERS_CHAR4.
If
an application has indicated it is using the 4-character cipher specifications
by setting GSK_V3_CIPHERS to GSK_V3_CIPHERS_CHAR4, but does not set
a cipher specification in GSK_V3_CIPHER_SPECS_EXPANDED the default
cipher specification will be set as follows: - executing in non-FIPS mode with United States only encryption
enabled:
"0005000400350036003700380039002F0030003100320033000A001600130010000D000900150012
000F000C00030006000200010000"
- executing in non-FIPS mode with United States only encryption
disabled:
"000900150012000F000C00030006000200010000"
- executing in FIPS mode:
"00350036003700380039002F0030003100320033000A001600130010000D"
If an application has indicated it will be running in
Suite B compatibility mode by setting GSK_SUITE_B_PROFILE to a value
other than GSK_SUITE_B_PROFILE_OFF, the cipher specification will
be set based on the values for GSK_SUITE_B_PROFILE as follows: - executing with GSK_SUITE_B_PROFILE_128 "C02BC023"
- executing with GSK_SUITE_B_PROFILE_192 "C02CC024"
- executing with GSK_SUITE_B_PROFILE_ALL "C02CC024C02BC023"
If executing in FIPS mode, the following cipher specifications
are supported: - When using 2-character cipher suites:
0A 0D 10 13 16 2F 30 31 32 33 35 36 37 38 39 3C 3D 3E 3F 40 67 68 69
6A 6B 9C 9D 9E 9F A0 A1 A2 A3 A4 A5
- When using 4-character cipher suites:
000A 000D 0010 0013 0016 002F 0030 0031 0032 0033 0035 0036 0037 0038
0039 003C 003D 003E 003F 0040 0067 0068 0069 006A 006B 009C 009D 009E
009F 00A0 00A1 00A2 00A3 00A4 00A5 C003 C004 C005 C008 C009 C00A
C00D C00E C00F C012 C013 C014 C023 C024 C025 C026 C027 C028 C029
C02A C02B C02C C02D C02E C02F C030 C031 C032
If using the TLS V1.1 or higher protocols,
export ciphers are not supported. The 40-bit ciphers (cipher specifications
"03" and "06" or "0003" and "0006") will be ignored if specified.
If
using the TLS V1.2 or higher protocols the 56-bit DES cipher suites
"09", "0C", "0F", "12" and "15" (or "0009", "000C", "000F", "0012"
and "0015") will be ignored if specified.
These environment
variables are processed: - GSK_CLIENT_ECURVE_LIST
- Specifies the list of elliptic curves supported by the client
as a string consisting of 1 or more 4-character decimal values in
order of preference for use. The list is used by the client to guide
the server as to which elliptic curves are preferred when using ECC-based
cipher suites for the TLS V1.0, TLS V1.1, and TLS V1.2 protocols.
Only
NIST recommended curves are able to be specified. To use Brainpool
standard curves for an SSL environment or connection, set GSK_CLIENT_ECURVE_LIST
to "" or use gsk_attribute_set_buffer() to reinitialize the
GSK_CLIENT_ECURVE_LIST buffer to NULL. See Table 5 for a list of valid 4-character
elliptic curve specifications.
- GSK_CRL_SECURITY_LEVEL
- Specifies the level of security SSL applications will use when
contacting LDAP servers to check CRLs for revoked certificates during
certificate validation.
- GSK_EXTENDED_RENEGOTIATION_INDICATOR
- Specifies the level of enforcement of renegotiation indication
as specified by RFC 5746 during the initial handshake.
Specify "OPTIONAL"
to not require the renegotiation indicator during initial handshake.
This is the default.
Specify "CLIENT" to allow the client initial
handshake to proceed only if the server indicates support for RFC
5746 Renegotiation.
Specify "SERVER" to allow the server initial
handshake to proceed only if the client indicates support for RFC
5746 Renegotiation.
Specify "BOTH" to allow the server and client
initial handshakes to proceed only if partner indicates support for
RFC 5746 Renegotiation.
- GSK_KEY_LABEL
- Specifies the label of the key used to authenticate the application.
The default key will be used if a key label is not specified.
- GSK_KEYRING_FILE
- Specifies the name of the key database file, SAF key ring
or z/OS® PKCS #11 token.
A key database is used if a database password or stash file is defined
using either an environment variable or the gsk_attribute_set_buffer() routine.
Otherwise a SAF key ring or z/OS PKCS
#11 token is used. GSK_KEYRING_FILE may be specified only for
an SSL environment.
The SAF key ring name is specified as "userid/keyring".
The current user ID is used if the user ID is omitted. The user must
have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY
class when using a SAF key ring owned by the user. The user must have
UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY
class when using a SAF key ring owned by another user.
A z/OS PKCS #11 token name is specified
as *TOKEN*/token-name. *TOKEN* indicates a PKCS #11 token is being
specified.
Note: Certificate private keys are not available when
using a SAF key ring owned by another user, except for SITE certificates
where CONTROL authority is given to IRR.DIGTCERT.GENCERT in the FACILITY
class or for user certificates where READ or UPDATE authority is given
to ringOwner.ringName.LST resource
in the RDATALIB class.
- GSK_KEYRING_PW
- Specifies the password for the key database.
- GSK_KEYRING_STASH
- Specifies the name of the key database password stash file. The
stash file name always has an extension of ".sth" and the supplied
name will be changed if it does not have the correct extension. The
GSK_KEYRING_PW environment variable will be used instead of the GSK_KEYRING_STASH
environment variable if it is also specified.
- GSK_LDAP_SERVER
- Specifies one or more blank-separated LDAP server host names.
Each host name can contain an optional port number separated from
the host name by a colon. The LDAP server is used to obtain CA certificates
when validating a certificate and the local database does not contain
the required certificate. The local database must contain the required
certificates if no LDAP server is specified. Even when an LDAP server
is used, root CA certificates must be found in the local database
since the LDAP server is not a trusted data source. The LDAP server
is also used to obtain certificate revocation lists. When multiple
LDAP server names are specified, a bind is attempted for each name
in the list until a bind is successful. Once a bind is successful,
that LDAP server is used.
- GSK_LDAP_PASSWORD
- Specifies the password to use when connecting to the LDAP server.
- GSK_LDAP_PORT
- Specifies the LDAP server port. Port 389 will be used if no LDAP
server port is specified.
- GSK_LDAP_USER
- Specifies the distinguished name to use when connecting to the
LDAP server.
- GSK_PROTOCOL_SSLV2
- Specifies whether the SSL V2 protocol is supported. A value of
"0", "OFF", or "DISABLED" disables the SSL V2 protocol while a value
of "1", "ON", or "ENABLED" enables the SSL V2 protocol. The SSL V2
protocol should be disabled whenever possible since the SSL V3 protocol
provides significant security enhancements.
When operating in FIPS
mode, SSL Version 2 protocol will not be used. Enabling this protocol
will have no effect.
When TLS extensions are defined for the
client and any of the TLS protocols are also enabled, the SSL Version
2 protocol will not be used. Enabling this protocol will have no effect.
- GSK_PROTOCOL_SSLV3
- Specifies whether the SSL V3 protocol is supported. A value of
"0", "OFF", or "DISABLED" disables the SSL V3 protocol while a value
of "1", "ON", or "ENABLED" enables the SSL V3 protocol.
When operating
in FIPS mode, SSL Version 3 protocol will not be used. Enabling this
protocol will have no effect.
- GSK_PROTOCOL_TLSV1
- Specifies whether the TLS V1.0 protocol is supported. A value
of "0", "OFF", or "DISABLED" disables the TLS V1.0 protocol while
value of "1", "ON", or "ENABLED" enables the TLS V1.0 protocol. The
TLS V1.0 protocol uses the same session cache and cipher specifications
as the SSL V3 protocol.
- GSK_PROTOCOL_TLSV1_1
- Specifies whether the TLS V1.1 protocol is supported. A value
of "0", "OFF", or "DISABLED" disables the TLS V1.1 protocol while
value of "1", "ON", or "ENABLED" enables the TLS V1.1 protocol. The
TLS V1.1 protocol uses the same session cache and cipher specifications
as the SSL V3 protocol. The TLS V1.1 protocol will not use export
(40-bit) ciphers. They will be ignored if TLS V1.1 is negotiated as
the communications protocol.
- GSK_PROTOCOL_TLSV1_2
- Specifies whether the TLS V1.2 protocol is supported. A value
of "0", "OFF", or "DISABLED" disables the TLS V1.2 protocol while
value of "1", "ON", or "ENABLED" enables the TLS V1.2 protocol. The
TLS V1.2 protocol uses the same session cache as the SSL V3 protocol.
The TLS V1.2 protocol will not use export cipher suites. 40-bit ciphers
will be ignored if TLS V1.2 is negotiated as the communications protocol.
- GSK_SUITE_B_PROFILE
- Specifies the Suite B profile that an SSL server or client will
apply to TLS sessions. RFC 5430 defines the cipher suites that are
valid for use when using the Suite B profile for TLS.
- Specify "128" if only the 128-bit Suite B security profile is
required.
- Specify "192" if only the 192-bit Suite B security profile is
required.
- Specify "ALL" if both the 128-bit and 192-bit Suite B security
profiles are required.
- Specify "OFF" if the Suite B security profile is not to be applied
to any TLS sessions.
- GSK_RENEGOTIATION
- Specifies the type of session renegotiation allowed for an SSL
environment.
Specify "NONE" to disable SSL V3 and TLS handshake
renegotiation as a server and allow RFC 5746 renegotiation. This is
the default.
Specify "DISABLED" to disable SSL V3 and TLS handshake
renegotiation as a server and also disable RFC 5746 renegotiation.
Specify
"ALL" to allow SSL V3 and TLS handshake renegotiation as a server
while also allowing RFC 5746 renegotiation.
Specify "ABBREVIATED"
to allow SSL V3 and TLS abbreviated handshake renegotiation as a server
for resuming the current session only, while disabling SSL V3 and
TLS full handshake renegotiation as a server. With this value specified,
the System SSL session ID cache is not checked when resuming the
current session. RFC 5746 renegotiation is allowed.
- GSK_RENEGOTIATION_PEER_CERT_CHECK
- Specifies if the peer certificate is allowed to change during
renegotiation.
Specify "OFF" or "0" to not perform an identity check
against the peer's certificate during renegotiation. This allows the
peer certificate to change during renegotiation. This is the default.
Specify
"ON" or "1" to perform a comparison against the peer's certificate
to ensure certificate does not change during renegotiation.
- GSK_SYSPLEX_SIDCACHE
- Specifies whether sysplex session caching is supported for this
application. A value of 0, OFF or DISABLED will disable sysplex session
caching while a value of 1, ON or ENABLED will enable sysplex session
caching.
- GSK_TLS_SIG_ALG_PAIRS
- Specifies the list of hash and signature algorithm pair specifications
supported by the client or server as a string consisting of 1 or more
4-character values in order of preference for use. The signature algorithm
pair specifications are sent by either the client or server to the
session partner to indicate which signature/hash algorithm combinations
are supported for digital signatures. Signature algorithm pair specification
only has relevance for sessions using TLS V1.2 or higher protocols.
See Table 6 for a list of valid
4-character signature algorithm pair specifications.
- GSK_V2_CIPHER_SPECS
- Specifies the SSL V2 cipher specifications in order of preference
as a null-terminated string consisting of 1 or more 1-character values.
Valid cipher specifications that are not supported because of the
installed cryptographic level will be skipped when the connection
is initialized.
- GSK_V2_SESSION_TIMEOUT
- Specifies the session timeout value in seconds for the SSL
V2 protocol. The valid timeout values are 0 through 100 and defaults
to 100.
- GSK_V2_SIDCACHE_SIZE
- Specifies the number of session identifiers that can be contained
in the SSL V2 cache. The valid cache sizes are 0 through 32000 and
defaults to 256. The SSL V2 cache will be disabled if 0 is specified.
- GSK_V3_CIPHER_SPECS
- Specifies the SSL V3 cipher specifications in order of preference
as a null-terminated string consisting of 1 or more 2-character values.
The SSL V3 cipher specifications are used for the SSL V3, TLS V1.0, and
higher protocols. Valid cipher specifications that are not supported
because of the installed cryptographic level will be skipped when
the connection is initialized. For protocols TLS V1.1 and above,
40-bit ciphers will be ignored if these protocols are negotiated as
the security protocol. For protocols TLS V1.2 and above, the
56-bit DES cipher suites will be ignored if these protocols are negotiated
as the communications protocol. See Table 2 for a list of the supported
2-character SSL V3 cipher specifications.
- GSK_V3_CIPHER_SPECS_EXPANDED
- Specifies the SSL V3 cipher specifications in order of preference
as a null-terminated string consisting of 1 or more 4-character values.
The SSL V3 cipher specifications are used for the SSL V3.0, TLS V1.0,
and higher protocols. Valid cipher specifications that are not supported
because of the installed cryptographic level will be skipped when
the connection is initialized. For protocols TLS V1.1 and above,
40-bit ciphers will be ignored if these protocols are negotiated as
the security protocol. For protocols TLS V1.2 and above, the 56-bit
DES cipher suites will be ignored if these protocols are negotiated
as the communications protocol. See Table 3 for a list of supported 4-character
SSL V3 cipher specifications.
- GSK_V3_SESSION_TIMEOUT
- Specifies the session timeout value in seconds for the SSL
V3, TLS V1.0 and higher protocols. The valid timeout values
are 0 through 86400 and defaults to 86400.
- GSK_V3_SIDCACHE_SIZE
- Specifies the number of session identifiers that can be contained
in the SSL V3 cache. The valid cache sizes are 0 through 64000 and
defaults to 512. The SSL V3 cache will be disabled if 0 is specified.
The SSL V3 cache is used for the SSL V3, TLS V1.0 and higher protocols.
|