V3 Multi-Datacenter Replication:
SSL

Features

Riak Multi-Datacenter (MDC) Replication SSL consists of the following items:

  • Encryption of replication data
  • SSL certificate chain validation
  • SSL common name whitelisting support

Note on cross-internet traffic

As an alternative to Riak Enterprise’s built-in SSL capabilities, we recommend using stunnel or a virtual private network (VPM) for inter-datacenter connections.

SSL Configuration

To configure SSL, you will need to include the following 4 settings in the riak-core section of advanced.confg:

{riak_core, [
             % ...
             {ssl_enabled, true},
             {certfile, "/full/path/to/site1-cert.pem"},
             {keyfile, "/full/path/to/site1-key.pem"},
             {cacertdir, "/full/path/to/cacertsdir"}
             % ...
            ]}

The cacertsdir is a directory containing all the CA certificates needed to verify the CA chain back to the root.

Note on configuration

In Version 3 replication, the SSL settings need to be placed in the riak-core section of advanced.config as opposed to the riak-repl section used by Version 2 replication.

Verifying Peer Certificates

Verification of a peer’s certificate common name (CN) is enabled by using the peer_common_name_acl property in the riak_core section of your advanced.config to specify an Access Control List (ACL).

The ACL is a list of one or more patterns, separated by commas. Each pattern may be either the exact CN of a certificate to allow, or a wildcard in the form *.some.domain.name. Pattern comparison is case-insensitive, and a CN matching any of the patterns is allowed to connect.

For example, ["*.corp.com"] would match site3.corp.com but not foo.bar.corp.com or corp.com. If the ACL were ["*.corp.com", "foo.bar.corp.com"], site3.corp.com and foo.bar.corp.com would be allowed to connect, but corp.com still would not.

If no ACL (or only the special value "*") is specified, no CN filtering is performed, except as described below.

Identical Local and Peer Common Names

As a special case supporting the view that a host’s CN is a fully-qualified domain name that uniquely identifies a single network device, if the CNs of the local and peer certificates are the same, the nodes will NOT be allowed to connect.

An exception is made when the CN begins with *, on the assumption that a pool of nodes might all legitimately use a certificate with a CN like *.dc5.example.com. In this specific case, peers with matching CNs are allowed to connect, so long as an explicit or implicit ACL allows it.

This evaluation supercedes ACL checks, so it cannot be overridden with any setting of the peer_common_name_acl property.

Examples

The following example will only allow connections from peer certificate names like db.bashosamplecorp.com and security.bashosamplecorp.com:

{riak_core, [
             % ...
             {peer_common_name_acl, ["db.bashosamplecorp.com", "security.bashosamplecorp.com"]}
             % ...
            ]}

The following example will allow connections from peer certificate names like foo.bashosamplecorp.com or db.bashosamplecorp.com, but not a peer certificate name like db.backup.bashosamplecorp.com.

{riak_core, [
             % ...
             {peer_common_name_acl, ["*.bashosamplecorp.com"]}
             % ...
            ]}

This example will match any peer certificate name (and is the default):

{riak_core, [
             % ...
             {peer_common_name_acl, "*"}
             % ...
            ]}

SSL CA Validation

You can adjust the way CA certificates are validated by adding the following to the riak_repl section of advanced.config:

{riak_core, [
             % ...
             {ssl_depth, 3} % Sets the depth to 3
             % ...
            ]}

Note: ssl_depth takes an integer parameter.

The depth specifies the maximum number of intermediate certificates that may follow the peer certificate in a valid certification path. The intermediate certificates must not be self signed.

The following example depths illustrate this:

  • a depth of 0 indicates that the certificate must be signed directly by a root certificate authority (CA)
  • a depth of 1 indicates that the certificate may be signed by at most 1 intermediate CA’s, followed by a root CA
  • a depth of 2 indicates that the certificate may be signed by at most 2 intermediate CA’s, followed by a root CA

Compatibility

Replication SSL for Version 3 is available in Riak 1.4+.

If SSL is enabled and a connection is made to a Riak Enterprise 1.0 or 1.1 node, the connection will be denied and an error will be logged.

Self-Signed Certificates

Read how to generate your own CA and keys. Ensure that you remove the password protection from the keys you generate.