---
title: "IceSSL.*"
url: https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties
language: csharp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# IceSSL.\*

Programming language: C#. Other languages: [C++](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/cpp.md), [Java](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/php.md), [Python](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/swift.md).

## IceSSL Property Overview

The IceSSL implementations for our supported platforms use many of the same configuration properties. However, there are some properties that are specific to certain platforms or languages. For properties with such limitations, we list the supported platforms or underlying SSL libraries in the synopsis and provide additional platform-specific notes if necessary. You'll see the following platforms, languages and SSL libraries listed in the property reference:

- SChannel (C++ on Windows)
- SecureTransport (C++ on macOS and iOS)
- OpenSSL (C++ on Linux)
- Java
- .NET

A property is supported by all of the platforms above if no limitations are mentioned.

Finally, note that Ice for Swift and the Ice extensions for MATLAB, PHP, Python and Ruby use IceSSL for C++, therefore they use the IceSSL properties for SChannel, SecureTransport or OpenSSL as appropriate for the target platform.

## IceSSL.CAs

`IceSSL.CAs=path` (.NET)

Specifies the path name of a file containing the certificates of trusted certificate authorities (CAs). The file can be encoded using the DER or PEM formats. When using PEM, the file can contain multiple certificates.

IceSSL attempts to locate `path` as specified; if the given path is relative but does not exist, IceSSL also attempts to locate `path` relative to the default directory defined by `IceSSL.DefaultDir`.

If you wish to use the CA certificates bundled with your platform, leave this property unset and enable `IceSSL.UsePlatformCAs`.

## IceSSL.CertFile

`IceSSL.CertFile=file` (.NET)

Specifies a file that contains the program's certificate and the corresponding private key. The file must use the PFX (PKCS#12) format. If a password is required to load the file, the application must supply the password using `IceSSL.Password`.

IceSSL attempts to locate `file` as specified; if the given path is relative but does not exist, IceSSL also attempts to locate `file` relative to the default directory defined by `IceSSL.DefaultDir`.

IceSSL imports the private key into the machine key set when `IceSSL.CertStoreLocation` is `LocalMachine`, and into the user key set otherwise.

## IceSSL.CertStore

`IceSSL.CertStore=name` (.NET)

Specifies the name of a certificate store to use when locating certificates via `IceSSL.FindCert`. Legal values for `name` include `AddressBook`, `AuthRoot`, `CertificateAuthority`, `Disallowed`, `My`, `Root`, `TrustedPeople`, and `TrustedPublisher`. You can also use an arbitrary value for `name`.

If not specified, the default value is `My`.

## IceSSL.CertStoreLocation

`IceSSL.CertStoreLocation=CurrentUser|LocalMachine` (.NET)

Specifies the location of the certificate store to use when locating certificates via `IceSSL.FindCert`. The location also selects the key set into which IceSSL imports the private key of the certificate loaded from `IceSSL.CertFile`: the machine key set for `LocalMachine` and the user key set for `CurrentUser`.

If not specified, the default value is `CurrentUser`.

> **Tip**
>
> An Ice program running as a Windows service will typically need to set this property to `LocalMachine`.

## IceSSL.CheckCertName

`IceSSL.CheckCertName=num`

Specifies if certificate host name verification is enabled. The legal values are shown in the table below. If this property is not defined, the default value is `0`.

| Value | Description |
| --- | --- |
| `0` | Host name verification is disabled. |
| `1` | Host name verification is enabled. |
| `2` | Host name verification is enabled. In Java, IceSSL also sends the host name with SNI. |

This property has no effect on a server's validation of a client's certificate.

If the host name verification is performed and fails, IceSSL aborts the connection attempt and raises an exception.

The verification ensures the host name matches the certificate's subject alternative names or the subject's `CommonName` if no subject alternative names are provided. Note the following difference in behavior for this check depending on the platform or language:

- if the endpoint uses an IP address: the SChannel, SecureTransport, OpenSSL and Java implementations only match the IP address against the subject alternative names, they don't check the `CommonName`
- if the endpoint uses a DNS name: SecureTransport on macOS only matches the DNS name against the subject alternative names, it doesn't check the `CommonName`

In Java, IceSSL verifies the host name only when `IceSSL.VerifyPeer` is greater than `0`, and sends the host name to the server through the TLS server name indication (SNI) extension only when this property is set to `2`. The C++ and .NET implementations always send a DNS host name with SNI.

## IceSSL.CheckCRL

`IceSSL.CheckCRL=num` (.NET)

Specifies whether IceSSL checks the certificates of the peer's chain for revocation:

| Value | Description |
| --- | --- |
| `0` | Revocation checks are disabled (default). |
| `1` | Revocation checks are enabled. IceSSL accepts an intermediate CA certificate whose revocation status it cannot determine. |
| `2` | Revocation checks are enabled. IceSSL rejects an intermediate CA certificate whose revocation status it cannot determine. |

With `1` and `2`, IceSSL checks every certificate of the chain except the root CA certificate. IceSSL aborts the connection when it finds a revoked certificate, or when it cannot determine the revocation status of the peer's own certificate.

IceSSL cannot determine the revocation status of a certificate that carries no revocation information, or whose OCSP responder or CRL distribution point it cannot reach.

If `IceSSL.Trace.Security` is set to a non-zero value, IceSSL logs the certificate chain status of a rejected connection.

The revocation sources are those of the platform, since .NET delegates certificate chain building to Windows CryptoAPI, to its own OpenSSL-based chain builder on Linux, and to the Security framework on macOS. Windows and Linux fetch CRLs from the distribution points and query the OCSP responders named in the certificates.

### Platform Notes {#icessl.checkcrl-platform-notes}

#### macOS {#icessl.checkcrl-macos}

The Security framework queries OCSP responders but does not fetch CRLs from distribution points. IceSSL therefore cannot determine the revocation status of a certificate that publishes only a CRL.

## IceSSL.DefaultDir

`IceSSL.DefaultDir=path`

Specifies the default directory in which to look for certificates, key stores, and other files. See the descriptions of the relevant properties for more information.

## IceSSL.FindCert

`IceSSL.FindCert=criteria` (.NET)

Selects the program's certificate from a certificate store instead of loading it from a file. IceSSL ignores this property when `IceSSL.CertFile` is defined.

IceSSL queries a certificate store for matching certificates. The settings for `IceSSL.CertStore` and `IceSSL.CertStoreLocation` determine the target certificate store to be queried. Communicator initialization fails when no certificate matches.

A server presents the first matching certificate. A client with several matching certificates presents the first one whose issuer is among the issuers the server accepts, or the first one when none matches.

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 white space. The valid field names are described below:

| Field | Description |
| --- | --- |
| `Issuer` | Matches a substring of the issuer's name. |
| `IssuerDN` | Matches the issuer's entire distinguished name. |
| `Serial` | Matches the certificate's serial number. |
| `Subject` | Matches a substring of the subject's name. |
| `SubjectDN` | Matches the subject's entire distinguished name. |
| `SubjectKeyId` | Matches the certificate's subject key identifier. |
| `Thumbprint` | Matches the certificate's SHA1 hash. |

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 white space.

## IceSSL.Password

`IceSSL.Password=password`

Specifies the password necessary to decrypt the private key.

### Platform Notes {#icessl.password-platform-notes}

#### SChannel, SecureTransport, OpenSSL {#icessl.password-schannel-securetransport-openssl}

This property supplies the password that was used to secure the private key contained in the file defined by `IceSSL.CertFile`.

#### Java {#icessl.password-java}

This property supplies the password that was used to secure the private key contained in the key store defined by `IceSSL.Keystore`. All of the keys in the key store must use the same password.

#### .NET {#icessl.password-.net}

This property supplies the password that was used to secure the file defined by `IceSSL.CertFile`.

#### iOS {#icessl.password-ios}

This property supplies the password that was used to secure the file defined by `IceSSL.CertFile`.

## IceSSL.Trace.Security

`IceSSL.Trace.Security=num`

The SSL plug-in trace level:

| Value | Description |
| --- | --- |
| `0` | No security tracing (default). |
| `1` | Displays a summary of each SSL connection, the reason a connection is rejected, and the peer's distinguished name when an `IceSSL.TrustOnly*` property applies. |
| `2` | Additionally displays the `IceSSL.TrustOnly*` entries evaluated against the peer's distinguished name. .NET displays these at level `1`. |

## IceSSL.TrustOnly

`IceSSL.TrustOnly=ENTRY[;ENTRY;...]`

Identifies trusted and untrusted peers. This family of properties provides an additional level of authentication by using the peer certificate's distinguished name (DN) to decide whether to accept or reject a connection.

IceSSL on iOS cannot read the distinguished name of a peer certificate, so any `IceSSL.TrustOnly*` entry fails every connection it applies to with a `FeatureNotSupportedException`.

Each `ENTRY` in the property value consists of relative distinguished name (RDN) components, formatted according to the rules in [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253.txt). Specifically, the components must be separated by commas, and any component that contains a comma must be escaped or enclosed in quotes. For example, the following two property definitions are equivalent:

```config
IceSSL.TrustOnly=O="Acme, Inc.",OU=Sales
IceSSL.TrustOnly=O=Acme\, Inc.,OU="Sales"
```

Use a semicolon to separate multiple entries in a property:

```config
IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales;O=Acme\, Inc.,OU=Marketing
```

By default, each entry represents an acceptance entry. A `!` character appearing at the beginning of an entry signifies a rejection entry. The order of the entries in a property is not important.

After the SSL engine has successfully completed its authentication process, IceSSL evaluates the relevant `IceSSL.TrustOnly` properties in an attempt to find an entry that matches the peer certificate's DN. For a match to be successful, the peer DN must contain an exact match for all of the RDN components in an entry. 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 in an entry is not important.

The connection semantics are described below:

1. IceSSL aborts the connection if any rejection or acceptance entries are defined and the peer does not supply a certificate.
2. IceSSL aborts the connection if the peer DN matches any rejection entry. (This is true even if the peer DN also matches an acceptance entry.)
3. IceSSL accepts the connection if the peer DN matches any acceptance entry, or if no acceptance entries are defined.

Our original example limits access to people in the sales and marketing departments:

```config
IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales;O=Acme\, Inc.,OU=Marketing
```

If it later becomes necessary to deny access to certain individuals in these departments, you can add a rejection entry and restart the program:

```config
IceSSL.TrustOnly=O=Acme\, Inc.,OU=Sales; O=Acme\, Inc.,OU=Marketing; !O=Acme\, Inc.,CN=John Smith
```

While testing your trust configuration, you may find it helpful to set the `IceSSL.Trace.Security` property to a non-zero 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

`IceSSL.TrustOnly.Client=ENTRY[;ENTRY;...]`

Identifies trusted and untrusted peers for outgoing (client) connections. The entries defined in this property are combined with those of `IceSSL.TrustOnly`.

## IceSSL.TrustOnly.Server

`IceSSL.TrustOnly.Server=ENTRY[;ENTRY;...]`

Identifies trusted and untrusted peers for incoming ("server") connections. The entries defined in this property are combined with those of `IceSSL.TrustOnly`. To configure trusted and untrusted peers for a particular object adapter, use `IceSSL.TrustOnly.Server.AdapterName`.

## IceSSL.TrustOnly.Server.*AdapterName*

`IceSSL.TrustOnly.Server.AdapterName=ENTRY[;ENTRY;...]`

Identifies trusted and untrusted peers for incoming (server) connections to the object adapter `AdapterName`. The entries defined in this property are combined with those of `IceSSL.TrustOnly` and `IceSSL.TrustOnly.Server`.

## IceSSL.UsePlatformCAs

`IceSSL.UsePlatformCAs=num`

If `num` is a value greater than `0`, IceSSL uses the platform's bundled Root Certificate Authorities. This setting is ignored if `IceSSL.CAs` is defined.

If not defined, the default value is `0`.

## IceSSL.VerifyPeer

`IceSSL.VerifyPeer=num`

Specifies whether an object adapter accepting an incoming connection requests a certificate from the client, and whether the client must supply one. The legal values are shown in the table below; any other value causes communicator initialization to fail with an `InitializationException`. If this property is not defined, the default value is `2`.

| Value | Description |
| --- | --- |
| `0` | The server does not request a certificate from the client. |
| `1` | The server requests a certificate from the client and accepts a client that supplies none. If the client supplies one, the server verifies it and aborts the connection if verification fails. |
| `2` | The server requires a certificate from the client and aborts the connection if the client supplies none or if verification fails. |

This property has no effect on outgoing connections (except in Java, see below): a client always requires and verifies the server's certificate.

### Platform Notes {#icessl.verifypeer-platform-notes}

#### Java {#icessl.verifypeer-java}

With the value `0`, a client accepts a server that does not present a certificate and does not check the server's host name (see `IceSSL.CheckCertName`). A certificate the server does present is still verified.
