---
title: "Securing a Glacier2 Router"
url: https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router
language: js
docs_index: https://docs.zeroc.com/llms.txt
---

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

# Securing a Glacier2 Router

Programming language: JavaScript. Other languages: [C++](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/java.md), [MATLAB](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/php.md), [Python](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/services/glacier2/securing-a-glacier2-router/swift.md).

A Glacier2 router accepts connections from clients outside a private network and forwards their requests to servers inside it. Use [SSL](https://docs.zeroc.com/ice/3.8/runtime/ssl-transport.md) for the router's client endpoints to encrypt the traffic between clients and the router, and to authenticate clients by their certificates. On top of SSL, the router provides access control, which decides which clients can create a session, and request filtering, which decides which objects a client can reach.

## Glacier2 Access Control

Validating a client's certificate during the SSL handshake establishes who the client is, but not whether that client may use the router. Glacier2 decides this with an access control facility that supports two forms of authentication: passwords and certificates. You can configure the router to use either form, or both.

### Password Authentication

The router verifies the user name and password arguments to its [createSession](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/js.md) operation before it forwards any requests on behalf of the client.

The router always verifies the user name and password with a permissions verifier, an object that implements the `Glacier2::PermissionsVerifier` interface. Glacier2 includes a verifier that checks the user name and password against a [password file](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/js.md#writing-a-password-file); set [Glacier2.CryptPasswords](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.cryptpasswords) to the path of this file to install this verifier in the router. To use your own verifier instead, set [Glacier2.PermissionsVerifier](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.permissionsverifier) to the proxy of your verifier object; when both properties are set, the router uses your verifier. The rest of this section covers the verifier interface.

A custom verifier is useful when a repository of account information already exists (such as an LDAP directory), in which case duplicating that information in another file would be tedious and error-prone.

The Slice definition for the interface contains just one operation:

```slice
module Glacier2
{
    interface PermissionsVerifier
    {
        idempotent bool checkPermissions(
            string userId,
            string password,
            out string reason) throws PermissionDeniedException;
    }
}
```

The router invokes `checkPermissions` on the verifier object, passing it the user name and password arguments that were given to `createSession`. The operation must return true if the arguments are valid, and false otherwise. If the operation returns false, a reason can be provided in the output parameter. `checkPermissions` can also throw `Glacier2::PermissionDeniedException`: the Glacier2 router forwards this exception as-is to the client, which means the verifier can throw a subclass of `PermissionDeniedException` in order to provide more information to the client.

To configure a router with a custom verifier, set the configuration property [Glacier2.PermissionsVerifier](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.permissionsverifier) with the proxy for the object.

In situations where authentication is not necessary, such as during development or when running in a trusted environment, you can use Glacier2's built-in "null" permissions verifier. This object accepts any combination of user name and password, and you can enable it with the following property definition:

```config
Glacier2.PermissionsVerifier=Glacier2/NullPermissionsVerifier
```

Note that the category of the object's identity (`Glacier2` in this example) must match the value of the property [Glacier2.InstanceName](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.instancename).

#### Supported Hash Formats

A password hash in the password file has the form `$identifier$content`, where `identifier` names the hashing scheme and `content` holds the parameters and the hash of this scheme. The schemes the built-in verifier accepts depend on the platform:

- On Linux, the schemes the system's `crypt` library supports, such as SHA-256 crypt (`$5$`) and SHA-512 crypt (`$6$`).
- On macOS and Windows, PBKDF2 with SHA-1, SHA-256 or SHA-512 as the digest algorithm, in the [format of passlib](https://passlib.readthedocs.io/en/stable/lib/passlib.hash.pbkdf2_digest.html): `$pbkdf2$rounds$salt$checksum` for SHA-1, and `$pbkdf2-sha256$rounds$salt$checksum` or `$pbkdf2-sha512$rounds$salt$checksum` for SHA-256 and SHA-512.

#### `icehashpassword` Helper Script

You can use the `icehashpassword` helper script to generate these password hashes. This script requires `Python` and `pip` to be installed. To install this script run:

```shell
pip install zeroc-icehashpassword
```

`icehashpassword` generates PBKDF2 hashes on Windows and macOS, and crypt hashes on Linux. It reads the password and prints the hash. On Linux:

```shell
icehashpassword
Password:
$6$rounds=656000$PFLqAztdBNhCjPeZ$GeZ3rLbMu4FObT78zAqQ15qJu0M/DSAZVBoNJCm95AaTflH.c06IcgFNbm8fOnl1ynGcEBqa.Ftgw3lJ0jPRm0
```

On Windows and macOS:

```shell
icehashpassword
Password:
$pbkdf2-sha256$29000$O4dQinGOcY7RWktJyXlvbQ$D0BZnA1kTw4Jl4xGUzdMOSxKO/vODiMCHEE9ZRLF4Gg
```

You may also specify several optional parameters:

- `-d MESSAGE_DIGEST_ALGORITHM, --digest=MESSAGE_DIGEST_ALGORITHM`: `sha1`, `sha256` (the default), or `sha512` on Windows and macOS; `sha256` or `sha512` (the default) on Linux.
- `-s SALT_SIZE, --salt=SALT_SIZE` (Windows and macOS only)
- `-r ROUNDS, --rounds=ROUNDS`

For example:

```shell
icehashpassword -r 25000 -d sha256
Password:
...
```

### Certificate Authentication

The [createSessionFromSecureConnection](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/js.md) operation does not require a user name or password because the client's SSL connection to the router already supplies the credentials necessary to sufficiently identify the client, in the form of X.509 certificates.

It is up to you to decide what constitutes sufficient identification. For example, a single certificate could be shared by all clients if there is no need to distinguish between them, or you could generate a unique certificate for each client or a group of clients. Glacier2 does not enforce any particular policy, but simply delegates the decision of whether to accept the client's credentials to an application-defined object that implements the `Glacier2::SSLPermissionsVerifier` interface:

```slice
module Glacier2
{
    interface SSLPermissionsVerifier
    {
        idempotent bool authorize(
            SSLInfo info,
            out string reason) throws PermissionDeniedException;
    }
}
```

Router clients may only use `createSessionFromSecureConnection` if the router is configured with a proxy for an `SSLPermissionsVerifier` object. The implementation of `authorize` must return true to allow the client to establish a session. To reject the session, `authorize` must return false and may optionally provide a value for `reason`, which is returned to the client as a field of `PermissionDeniedException`. `authorize` can also throw `Glacier2::PermissionDeniedException`; the router then throws this exception, with the same `reason`, to the client.

The verifier examines the fields of `SSLInfo` to authenticate a client:

```slice
module Glacier2
{
    struct SSLInfo
    {
        string remoteHost;
        int remotePort;
        string localHost;
        int localPort;
        string cipher;
        Ice::StringSeq certs;
    }
}
```

`certs` holds a single element: the certificate the client presented when it established its SSL connection to the router, in PEM encoding. The `remoteHost`, `remotePort`, `localHost`, and `localPort` fields hold the addresses of the client's connection to the router. The router leaves `cipher` empty.

The verifier typically examines the certificate's subject and issuer names. It decodes the PEM string with the certificate API of its platform, such as `X509Certificate2` in .NET or `CertificateFactory` in Java.

To install your verifier, set the [Glacier2.SSLPermissionsVerifier](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.sslpermissionsverifier) property with the proxy of your verifier object.

In situations where authentication is not necessary, such as during development or when running in a trusted environment, you can use Glacier2's built-in "null" permissions verifier. This object accepts the credentials of any client, and you can enable it with the following property definition:

```config
Glacier2.SSLPermissionsVerifier=Glacier2/NullSSLPermissionsVerifier
```

Note that the category of the object's identity (`Glacier2` in this example) must match the value of the property [Glacier2.InstanceName](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.instancename).

### Interaction with a Permissions Verifier

The router attempts to contact the configured permissions verifiers at startup. If an object is unreachable, the router logs a warning message but continues its normal operation. The router does not contact a verifier again until it needs to invoke an operation on the object. For example, when a client asks the router to create a new session, the router makes another attempt to contact the verifier; if the object is still unavailable, the router logs a message and returns `PermissionDeniedException` to the client.

### Obtaining SSL Credentials for a Router Client

Servers that need information about a client's connection to the router can set [Glacier2.AddConnectionContext](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.addconnectioncontext) to `1`. The router then adds connection information to permissions-verifier and session-manager calls and to requests forwarded from clients to servers. Value `2` adds this information only to `checkPermissions` and `authorize` calls on permissions verifiers and `create` calls on session managers.

The context entries describe the client's connection to the router: its type, its local and remote addresses and ports, and, when the client presented a certificate, the PEM-encoded certificate in `_con.peerCert`.

> **Note**
>
> A JavaScript object adapter does not listen on endpoints, so a JavaScript application cannot be a server behind Glacier2 and never receives these context entries.

## Request Filtering

The Glacier2 router can restrict the objects that a client reaches through it, with a category filter, an identity filter and an adapter ID filter:

- The category and identity filters apply to every request; the adapter ID filter applies only to a request whose target proxy has an adapter ID.
- The router forwards a request when at least one of the filters that apply to it accepts it.
- The router forwards a request to which no filter applies, in particular when no filter is configured.

The address filters and the proxy size limit apply independently.

### Address Filters

To prevent a client from accessing arbitrary back-end hosts or ports, you can configure a Glacier2 router to validate the address information in each proxy that the client attempts to use. Two properties determine the router's filtering behavior:

- [Glacier2.Filter.Address.Accept](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.address.accept) Each entry is an accept rule, which matches a proxy when every endpoint of this proxy matches the entry. When this property is set, the router accepts a proxy only when at least one accept rule matches it; when it is not set, the router accepts every proxy that no reject rule matches. An indirect proxy has no endpoints, so no accept rule matches it.
- [Glacier2.Filter.Address.Reject](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.address.reject) Each entry is a reject rule, which matches a proxy when at least one endpoint of this proxy matches the entry. The router rejects a proxy that a reject rule matches, even when an accept rule matches it.

The value of each property is a list of *address*:*port* pairs separated by spaces, as shown in the example below:

```config
Glacier2.Filter.Address.Accept=192.168.1.5:4063 192.168.1.6:4063
```

With this configuration, clients can reach two back-end hosts, each on a single port. The router rejects a proxy with any other endpoint. It also rejects a proxy with the endpoints `tcp -h 192.168.1.5 -p 4063:tcp -h 192.168.1.6 -p 4063`: each entry is a separate rule, and neither rule matches both endpoints. See [Client Impact](#client-impact) for what a rejection means for the client.

You can also use ranges, groups and wildcards when defining your address filters. For example, the following property value shows how to use an address range:

```config
Glacier2.Filter.Address.Accept=192.168.1.[5-6]:4063
```

This property is a single rule that matches both hosts: it accepts the proxies that the first example accepts, and also the proxy with the two endpoints shown above. Similarly, we can restate the property using the group notation by separating values with a comma:

```config
Glacier2.Filter.Address.Accept=192.168.1.[5,6]:4063
```

The wildcard notation uses the \* character to substitute for a value:

```config
Glacier2.Filter.Address.Accept=10.0.*.1:4063
```

The range, group, and wildcard notation is also supported when specifying ports, as shown below:

```config
Glacier2.Filter.Address.Accept=192.168.1.[5,6]:[10000-11000]
Glacier2.Filter.Address.Reject=192.168.1.[5,6]:[10500,10501]
```

In this configuration, the router allows clients to access all of the ports in the range `10000` to `11000`, except for the two ports `10500` and `10501`.

At first glance, you might think that the following property definition is pointless because it would prevent clients from accessing any back-end server:

```config
Glacier2.Filter.Address.Reject=*
```

In reality, this configuration only prevents clients from accessing servers using direct proxies, that is, proxies that contain endpoints. As a result, the property causes Glacier2 to accept only [indirect proxies](https://docs.zeroc.com/ice/3.8/basics/terminology.md).

> **Note**
>
> By default, a Glacier2 router forwards requests for any address.

### Category Filters

An [Ice::Identity](https://docs.zeroc.com/ice/3.8/runtime/object-identity/js.md) has two string fields: category and name. The category filter accepts requests for objects whose identity category is in the list configured with [Glacier2.Filter.Category.Accept](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.category.accept):

```config
Glacier2.Filter.Category.Accept=cat1 cat2
```

This property does not affect the routing of [callback requests](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2/js.md) from back-end servers to router clients.

> **Note**
>
> By default a Glacier2 router forwards requests for any category.

If a category contains spaces, you can enclose the value in single or double quotes. If a category contains a quote character, it must be escaped with a leading backslash.

Glacier2 can optionally manipulate the category filter automatically. When you set [Glacier2.Filter.Category.AcceptUser](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.category.acceptuser) to a value of `1`, the router adds the user name of each session created with `createSession` to the list of accepted categories, unless that user name is empty. To ensure the uniqueness of your categories, you may prefer setting the property to a value of `2`, which causes the router to prepend an underscore to the user name before adding it to the list.

A session manager can also change the accepted categories at run time, as described in [Dynamic Request Filtering with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/dynamic-request-filtering-with-glacier2.md).

### Identity Filters

The ability to filter on identity categories, as described in the previous section, is a convenient way to give clients access to particular groups of objects. To give clients access to individual objects, you can use the [Glacier2.Filter.Identity.Accept](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.identity.accept) property. The value of this property is a list of identities, separated by whitespace, and the identity filter accepts requests for these objects.

If an identity contains spaces, you can enclose the value in single or double quotes. If an identity contains a quote character, it must be escaped with a leading backslash.

Specifying a static list of identities is only practical for a small set of objects. Furthermore, in many applications, the complete set of identities cannot be known in advance, such as when objects are created on a per-session basis and use UUIDs in their identities. For these situations, category-based filtering is generally sufficient. A session manager can also change the accepted identities at run time, as described in [Dynamic Request Filtering with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/dynamic-request-filtering-with-glacier2.md).

### Adapter Filters

Applications often use [IceGrid](https://docs.zeroc.com/ice/3.8/services/icegrid.md) in their back-end network to simplify server administration and take advantage of the benefits offered by indirect proxies. Once you have configured Glacier2 with an appropriate [locator proxy](https://docs.zeroc.com/ice/3.8/services/glacier2/icegrid-and-glacier2-integration.md), clients can use indirect proxies to refer to objects in IceGrid-managed servers. Indirect proxies come in two forms: one that contains only an identity, and one that contains an identity and an adapter ID. You can use the category and identity filters described in previous sections to control identity-only proxies, and you can use the property [Glacier2.Filter.AdapterId.Accept](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.adapterid.accept) to enforce restrictions on indirect proxies that use an adapter ID.

For example, the following property definition allows a client to use the proxy `factory@WidgetAdapter` but not the proxy `factory@SecretAdapter`:

```config
Glacier2.Filter.AdapterId.Accept=WidgetAdapter
```

If an adapter ID contains spaces, you can enclose the value in single or double quotes. If an adapter ID contains a quote character, it must be escaped with a leading backslash.

A session manager can also change the accepted adapter IDs at run time, as described in [Dynamic Request Filtering with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/dynamic-request-filtering-with-glacier2.md).

### Proxy Filters

The proxy filter rejects a proxy whose [stringified form](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) is longer than [Glacier2.Filter.ProxySizeMax](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.proxysizemax) bytes. By default, the router does not limit the size of proxies. This filter protects the router against clients that send very large proxies, since each session's routing table holds every proxy its client uses.

### Client Impact

The Glacier2 router immediately terminates a client's session if it attempts to use a proxy that is rejected by an address filter or exceeds the size limit defined by the property [Glacier2.Filter.ProxySizeMax](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.filter.proxysizemax). The Ice runtime in the client responds by raising `ConnectionLostException` to the application.

For category, identity, and adapter ID filters, the router raises `ObjectNotExistException` if any of the filters rejects a proxy and none of the filters accepts it.

To obtain more information on the router's reasons for terminating a session or rejecting a request, set the following property and examine the router's log output:

```config
Glacier2.Client.Trace.Reject=1
```

## Glacier2 Routing Table

The Glacier2 router maintains an internal routing table for each session. The routing table holds every proxy used by its session. Consequently, the size of the routing table grows in proportion to the number of proxies used by a session. Furthermore, the amount of memory that all of the routing tables consume grows with the number of active sessions.

The property [Glacier2.RoutingTable.MaxSize](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.routingtable.maxsize) allows you to specify an upper limit on the number of entries in the routing table. If the size of the table exceeds the value of this property, the router evicts older entries on a least-recently-used basis. (Eviction of proxies from the routing table is transparent to router clients.) The default size of the routing table is `1000`, but you may need to define a different value depending on the needs of your application. While experimenting with different values, you may find it useful to define the property [Glacier2.Trace.RoutingTable](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md#glacier2.trace.routingtable) to see a log of the router's activities with respect to the routing table.

The router does not remove entries from a session's routing table except when evicting an old entry to make room for a new one. In particular, an exception that occurs while routing a request for a proxy does *not* cause that proxy to be removed from the routing table. Note however that the routing table is destroyed upon session destruction.

## See Also

- [Glacier2.\*](https://docs.zeroc.com/ice/3.8/property-reference/glacier2-properties.md)
- [SSL Transport](https://docs.zeroc.com/ice/3.8/runtime/ssl-transport.md)
- [Getting Started with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/js.md)
- [Callbacks Through Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2/js.md)
- [Dynamic Request Filtering with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/dynamic-request-filtering-with-glacier2.md)
- [IceGrid and Glacier2 Integration](https://docs.zeroc.com/ice/3.8/services/glacier2/icegrid-and-glacier2-integration.md)
