Securing a Glacier2 Router

17 min read

A Glacier2 router accepts connections from clients outside a private network and forwards their requests to servers inside it. Use SSL 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 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; set Glacier2.CryptPasswords to the path of this file to install this verifier in the router. To use your own verifier instead, set 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 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:

Properties

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.

Certificate Authentication

The createSessionFromSecureConnection 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 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:

Properties

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.

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