Ice Reference Documentation | ||
---|---|---|
<<< Previous | Properties | Next >>> |
IceSSL.Alias=alias (Java) |
Selects a particular certificate from the keystore specified by IceSSL.Keystore. The certificate identified by alias is presented to the peer upon request during authentication.
IceSSL.CertAuthDir=path (C++) |
Specifies the directory containing the certificates of trusted Certificate Authorities. The directory must be prepared in advance using the OpenSSL utility c_rehash. The pathname may be specified relative to the default directory defined by IceSSL.DefaultDir.
IceSSL.CertAuthFile=file (C++) |
Specifies a file containing the certificate of a trusted Certificate Authority. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir. The certificate must be encoded using the PEM format.
IceSSL.CertFile=file (C++, .NET) |
Specifies a file that contains the program's certificate, and may also contain the corresponding private key. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir.
Platform Notes
The private key is optional; if not present, the file containing the private key must be identified by IceSSL.KeyFile. If a password is required, OpenSSL will prompt the user at the terminal unless the application has installed a password handler or supplied the password using IceSSL.Password. The certificate must be encoded using the PEM format.
The file must use the PFX (PKCS#12) format and contain the certificate and its private key. The password for the file must be supplied using IceSSL.Password.
IceSSL.CheckCertName=num |
If num is a value greater than zero, IceSSL compares the server's hostname as specified in the proxy against the DNS or IP address fields of the server's certificate. If no match is found, IceSSL aborts the connection attempt and raises an exception. If not defined, the default value is zero.
IceSSL.CheckCRL=num (.NET) |
If num is a value greater than zero, IceSSL checks the certificate revocation list to determine if the peer's certificate has been revoked. If so, IceSSL aborts the connection and raises an exception.
IceSSL.Ciphers=ciphers (C++, Java) |
Specifies the ciphersuites that IceSSL is allowed to negotiate. A ciphersuite is a set of algorithms that satisfies the four requirements for establishing a secure connection: signing and authentication, key exchange, secure hashing, and encryption. Some algorithms satisfy more than one requirement, and there are many possible combinations.
Platform Notes
The value of this attribute is given directly to the OpenSSL library and is dependent on how OpenSSL was compiled. You can obtain a complete list of the supported cipher suites using the command openssl ciphers. This command will likely generate a long list. To simplify the selection process, OpenSSL supports several classes of ciphers:
ALL | Enables all supported ciphersuites. This class should be used with caution, as it may enable low-security ciphersuites. |
ADH | Anonymous ciphers. |
LOW | Low bit-strength ciphers. |
EXP | Export-crippled ciphers. |
ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
This value excludes the ciphers with low bit-strength and known problems, and orders the remaining ciphers according to their strength. Note that no warning is given if an unrecognized cipher is specified.
The property value is interpreted as a list of tokens delimited by whitespace. The plugin executes the tokens in the order of appearance in order to assemble the list of enabled ciphersuites. The table below describes the tokens:
NONE | Disables all ciphersuites. If specified, it must be the first token in the list. |
ALL | Enables all supported ciphersuites. If specified, it must be the first token in the list. This token should be used with caution, as it may enable low-security ciphersuites. |
NAME | Enables the ciphersuite matching the given name. |
!NAME | Disables the ciphersuite matching the given name. |
(EXP) | Enables ciphersuites whose names contain the regular expression EXP. For example, the value NONE (.*DH_anon.*) selects only ciphersuites that use anonymous Diffie-Hellman authentication. |
!(EXP) | Disables ciphersuites whose names contain the regular expression EXP. For example, the value ALL !(.*DH_anon.*) enables all ciphersuites except those that use anonymous Diffie-Hellman authentication. |
If not specified, the plugin uses the security provider's default ciphersuites. Set IceSSL.Trace.Security=1 to determine which ciphersuites are enabled by default, or to verify your ciphersuite configuration.
IceSSL.DefaultDir=path |
Specifies the default directory in which to look for certificate, key, and keystore files. See the descriptions of the relevant properties for more information.
IceSSL.DH.bits=file (C++) |
Specifies a file containing Diffie Hellman parameters whose key length is bits, as shown in the following example:
IceSSL.DH.1024=dhparams1024.pem
IceSSL supplies default parameters for key lengths of 512, 1024, 2048 and 4096 bits, which are used if no user-defined parameters of the desired key length are specified. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir. The parameters must be encoded using the PEM format.
IceSSL.EntropyDaemon=file (C++) |
Specifies a Unix domain socket for the Entropy Gathering Daemon, from which OpenSSL gathers entropy data to initialize its random number generator.
IceSSL.FindCert.location.name=criteria (.NET) |
Queries the certificate repository for matching certificates and adds them to the application's collection of certificates that are used for authentication. The value for location must be LocalMachine or CurrentUser. The name corresponds to the .NET enumeration StoreName and may be one of the following values: AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, TrustedPublisher. It is also possible to use an arbitrary value for name.
The value for criteria may be *, in which case all of the certificates in the store are selected. Otherwise, criteria must be one or more field:value pairs separated by whitespace. The valid field names are described below:
Matches a substring of the issuer's name.
Matches the issuer's entire distinguished name.
Matches the certificate's serial number.
Matches a substring of the subject's name.
Matches the subject's entire distinguished name.
Matches the certificate's subject key identifier.
Matches the certificate's thumbprint.
The field names are case-insensitive. If multiple criteria are specified, only certificates that match all criteria are selected. Values must be enclosed in single or double quotes to preserve whitespace.
Multiple occurrences of the property are allowed, but only one query is possible for each location/name combination. The certificates from all queries are combined to form the certificate collection, including a certificate loaded using IceSSL.CertFile.
Some sample queries are shown below:
IceSSL.FindCert.LocalMachine.My=issuer:verisign serial:219336
IceSSL.FindCert.CurrentUser.Root=subject:"Joe's Certificate"
![]() | A server requires a certificate for authentication purposes, therefore IceSSL selects the first certificate in the accumulated collection. This is normally the certificate loaded via IceSSL.CertFile, if that property was defined. Otherwise, one of the certificates from IceSSL.FindCert is selected. Since IceSSL does not guarantee the order in which it evaluates IceSSL.FindCert properties, it is recommended that the criteria select only one certificate. |
IceSSL.ImportCert.location.name=file[;password] (.NET) |
Imports the certificate in file into the specified certificate store. The value for location must be LocalMachine or CurrentUser. The name corresponds to the .NET enumeration StoreName and may be one of the following values: AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, TrustedPublisher. It is also possible to use an arbitrary value for name, which adds a new store to the repository. If you are importing a trusted CA certificate, it must be added to AuthRoot or Root.
The password is optional; it is only necessary if the certificate file also contains a private key or uses a secure storage format such as PFX.
The filename and password may be enclosed in single or double quotes if necessary. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir.
![]() | Importing a certificate into LocalMachine requires administrator privileges, while importing into CurrentUser may cause the platform to prompt the user for confirmation. |
IceSSL.KeyFile=file (C++) |
Specifies a file containing the private key associated with the certificate identified by IceSSL.CertFile. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir. The key must be encoded using the PEM format.
IceSSL.Keystore=file (Java) |
Specifies a keystore file containing certificates and their private keys. If the keystore contains multiple certificates, you should specify a particular one to use for authentication using IceSSL.Alias. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir. The format of the file is determined by IceSSL.KeystoreType.
If this property is not defined, the application will not be able to supply a certificate during SSL handshaking. As a result, the application may not be able to negotiate a secure connection, or might be required to use an anonymous ciphersuite.
IceSSL.KeystorePassword=password (Java) |
Specifies the password used to verify the integrity of the keystore defined by IceSSL.Keystore. The integrity check is skipped if this property is not defined.
![]() | It is a security risk to use a plain-text password in a configuration file. |
IceSSL.KeystoreType=type (Java) |
Specifies the format of the keystore file defined by IceSSL.Keystore. Legal values are JKS and PKCS12. If not defined, the JVM's default value is used (normally JKS).
IceSSL.Password=password |
Specifies the password necessary to decrypt the private key.
Platform Notes
This property supplies the password that was used to secure the private key contained in the file defined by IceSSL.CertFile or IceSSL.KeyFile. If this property is not defined and you have not installed a password callback object, OpenSSL will prompt the user for a password if one is necessary.
This property supplies the password that was used to secure the private key contained in the keystore defined by IceSSL.Keystore. All of the keys in the keystore must use the same password.
This property supplies the password that was used to secure the file defined by IceSSL.CertFile.
![]() | It is a security risk to use a plain-text password in a configuration file. |
IceSSL.PasswordRetryMax=num (C++) |
Specifies the number of attempts IceSSL should allow the user to make when entering a password. If not defined, the default value is 3.
IceSSL.Protocols=list |
Specifies the protocols to allow during SSL handshaking. Legal values are SSL3 and TLS1. You may also specify both values, separate by commas or whitespace. If this property is not defined, the platform's default is used.
IceSSL.Random=filelist (C++, Java) |
Specifies one or more files containing data to use when seeding the random number generator. The filenames should be separated using the platform's path separator (a colon on Unix and a semicolon on Windows). The filenames may be specified relative to the default directory defined by IceSSL.DefaultDir.
IceSSL.TrustOnly=ENTRY[;ENTRY;...] |
Identifies trusted peers. This family of properties provides an additional level of authentication by restricting connections to trusted peers. After the SSL engine has successfully completed its authentication process, IceSSL compares the peer's distinguished name (DN) with each ENTRY in the property value and allows the connection to succeed if the peer's DN matches any of the entries. ENTRY must contain only those relative distinguished name (RDN) components that a peer is required to have in its DN. IceSSL rejects a connection if no match is found for the peer's DN, or if the peer did not supply a certificate.
For example, you can limit access to people in the sales and marketing departments using the following configuration:
IceSSL.TrustOnly=O="Acme, Inc.",OU="Sales"; O="Acme, Inc.",OU="Marketing"
The peer's DN must match one of these entries in order to establish a connection.
An entry may contain as many RDN components as you wish, depending on how narrowly you need to restrict access. The order of the RDN components is not important.
To specify more than one entry, separate them using semicolons. IceSSL expects each entry to be formatted according to the rules defined by RFC2253.
While testing your trust configuration, you may find it helpful to set the IceSSL.Trace.Security property to a nonzero value, which causes IceSSL to display the DN of each peer during connection establishment.
This property affects incoming and outgoing connections. IceSSL also supports similar properties that affect only incoming connections or only outgoing connections.
IceSSL.TrustOnly.Client=ENTRY[;ENTRY;...] |
Identifies trusted peers for outgoing ("client") connections. For a connection to succeed, the peer's distinguished name (DN) must match an entry in this property or in IceSSL.TrustOnly. See the description of IceSSL.TrustOnly for more information.
IceSSL.TrustOnly.Server=ENTRY[;ENTRY;...] |
Identifies trusted peers for incoming ("server") connections. For a connection to succeed, the peer's distinguished name (DN) must match an entry in this property or in IceSSL.TrustOnly. See the description of IceSSL.TrustOnly for more information. To configure trusted peers for a particular object adapter, use IceSSL.TrustOnly.Server.AdapterName.
IceSSL.TrustOnly.Server.AdapterName=ENTRY[;ENTRY;...] |
Identifies trusted peers for incoming ("server") connections to the object adapter AdapterName. For a connection to succeed, the peer's distinguished name (DN) must match an entry in this property, an entry in IceSSL.TrustOnly.Server, or an entry in IceSSL.TrustOnly. See the description of IceSSL.TrustOnly for more information.
IceSSL.Truststore=file (Java) |
Specifies a keystore file containing the certificates of trusted certificate authorities. The filename may be specified relative to the default directory defined by IceSSL.DefaultDir. The format of the file is determined by IceSSL.TruststoreType.
If this property is not defined, the application will not be able to authenticate the peer's certificate during SSL handshaking. As a result, the application may not be able to negotiate a secure connection, or might be required to use an anonymous ciphersuite.
IceSSL.TruststorePassword=password (Java) |
Specifies the password used to verify the integrity of the keystore defined by IceSSL.Truststore. The integrity check is skipped if this property is not defined.
![]() | It is a security risk to use a plain-text password in a configuration file. |
IceSSL.TruststoreType=type (Java) |
Specifies the format of the keystore file defined by IceSSL.Truststore. Legal values are JKS and PKCS12. If not defined, the default value is JKS.
IceSSL.VerifyDepthMax=num |
Specifies the maximum depth of a trusted peer's certificate chain, including the peer's certificate. A value of zero accepts chains of any length. If not defined, the default value is 2.
IceSSL.VerifyPeer=num |
Specifies the verification requirements to use during SSL handshaking. The legal values are shown in the table below:
0 | For an outgoing connection, the client verifies the server's certificate (if an anonymous cipher is not used) but does not abort the connection if verification fails. For an incoming connection, the server does not request a certificate from the client. |
1 | For an outgoing connection, the client verifies the server's certificate and aborts the connection if verification fails. For an incoming connection, the server requests a certificate from the client and verifies it if one is provided, aborting the connection if verification fails. |
2 | For an outgoing connection, the semantics are the same as for value 1. For an incoming connection, the server requires a certificate from the client and aborts the connection if verification fails. |
Platform Notes
This property has no effect on outgoing connections, since .NET always uses the semantics of value 2. For an incoming connection, value 0 has the same semantics as value 1.
<<< Previous | Home | Next >>> |
Ice Miscellaneous Properties | Up | IceBox Properties |