Overview

In most cases, users will probably want to use the SSLSecurity plugin instead of this one.

This plugin impliments a AES encryption and RSA public / private key based security system for The Marionette Collective.

Please review the Security Overview for a general discussion about security in Marionette Collective.

The design goals of this plugin are:

  • Each actor - clients and servers - can have their own set of public and private keys
  • All actors are uniquely and cryptographically identified
  • Requests are encrypted using the clients private key and anyone that has the public key can see the request. Thus an atacker may see the requests given access to a public key of the requester.
  • Request TTLs and Message Times are cryptographically secured and tampered messages are not accepted by default. This is a first line defence in message replaying and tampering.
  • Replies are encrypted using the calling clients public key. Thus no-one but the caller can view the contents of replies.
  • Servers can all have their own SSL keys, or share one, or reuse keys created by other PKI using software like Puppet
  • Requests from servers - like registration data - can be secured even to external eavesdropping depending on the level of configuration you are prepared to do
  • Given a network where you can ensure third parties are not able to access the middleware public key distribution can happen automatically

During the design of this system we considered the replies back to clients to be most important piece of information on the network. This is secured in a way that only the client can decrypt the replies he gets. An attacker will need to gain access to every private key of every client to see all the reply data.

Serialization uses Marshal or YAML, which means data types in and out of mcollective will be preserved from client to server and reverse.

Compared to the SSL plugin

The earlier SSLSecurity only provided message signing and identification of clients, this new plugin builds on this adding payload encryption, identification of servers and optional automatic key distribution.

The SSLSecurity plugin puts less drain on resources, if you do not specifically need encryption you should consider using that one instead.

If you are using ActiveMQ middleware with CA-verified TLS enabled, the features of this plugin may not be required and you should probably use the SSLSecurity plugin instead.

Deployment Scenarios

There are various modes of deployment, the more secure you wish to be the more work you have to do in terms of key exchange and initial setup.

This plugin is designed to allow you to strike a balance between security and setup cost the sections below discuss the possible deployment scenarios to help you choose an approach.

In all of the below setups the following components are needed:

  • Each user making requests - the client - needs a public and private key pair
  • Each server receiving requests need the public key of each client

In cases where you wish to use Registration or initiate requests from the server for any reason the following are needed:

  • Each server needs a public and private key pair
  • Each other server that wish to receive these requests need the public key of the sending server

In this scenario each server will act as a client making RPC requests to the collective network for any agent called registration. So in this scenario the server acts as a client and therefore need a key-pair to identify it.

Manual key distribution with each server and client having unique keys

In this setup each client and each server needs a unique set of keys. You need to distribute these keys manually and securely - perhaps using Puppet.

The setup cost is great, to enable registration the nodes receiving registration data need to have the public key of every other node stored locally before registration data can be received.

If you do not use Puppet or some other PKI system that provide access to keys you need create keypairs for each node and client.

This is the most secure setup protecting all replies and registration data. Rogue people on the network who do not compromise a running host cannot make requests on the network.

Attackers who compromise a server can only make registration requests assuming you deployed a strictly configured Authorization system they cannot use those machines as starting points to inject requests for the rest of your network.

By gaining access to your Middleware an attacker will not be able to observe the contents of requests, replies or registration messages. Attackers need to compromise servers and gain access to private keys before they can start observing parts of the exchange.

Feature / Capability Supported
Clients are uniquely identified using cryptographic means yes
Anyone with the client public key can observe request contents yes
Attackers can gain access to the client public key by just listening on the network no
Replies back to the client are readable only by client that initiated the request yes
Attackers can create new certificates and start using them to make requests as clients no
Servers are uniquely identified using cryptographic means yes
Anyone with the server public key can observe registration contents yes
Attackers can gain access to the server public keys by just listening on the network no
Registration data can be protected from rogue agents posing as registration agents yes
Attackers can create new nodes and inject registration data for those new nodes no

To configure this scenario use the following options and manually copy public keys to the plugin.aes.client_cert_dir directory:

Settings Value Descritpion
plugin.aes.send_pubkey 0 Do not send public keys
plugin.aes.learn_pubkeys 0 Do not learn public keys

Automatic public key distribution with each server and client having unique keys

Here we enable the plugin.aes.learn_pubkeys feature on all servers. Your public keys will now be distributed automatically on demand but you loose some security in that anyone with access to your network or middleware can observe the contents of replies and registration data

You still need to create keys for every node - or use Puppets. You still need to create keys for every user.

In order to protect against attackers creating new certificates and making requests on your network deploy a Authorization plugin that denies unknown clients.

Feature / Capability Supported
Clients are uniquely identified using cryptographic means yes
Anyone with the client public key can observe request contents yes
Attackers can gain access to the client public key by just listening on the network yes
Replies back to the client are readable only by client that initiated the request yes
Attackers can create new certificates and start using them to make requests as clients yes
Servers are uniquely identified using cryptographic means yes
Anyone with the server public key can observe registration contents yes
Attackers can gain access to the server public keys by just listening on the network yes
Registration data can be protected from rogue agents posing as registration agents yes
Attackers can create new nodes and inject registration data for those new nodes yes

To configure this scenario use the following options and ensure the mcollectived can write to the plugin.aes.client_cert_dir directory:

Settings Value Descritpion
plugin.aes.send_pubkey 1 Send public keys
plugin.aes.learn_pubkeys 1 Learn public keys

Manual public key distribution with servers sharing a key pair and clients having unique keys

This is comparable to the older SSL plugin where all servers shared the same public / private pair. Here anyone who is part of the network can decrypt the traffic related to registration but replies to clients are still securely encrypted and visable only to them.

You will not need to create unique keys for every server, you can simply copy the same one out everywhere. You still need to create keys for every user.

If you do not use registration, this is a very secure setup that requires a small configuration overhead.

Feature / Capability Supported
Clients are uniquely identified using cryptographic means yes
Anyone with the client public key can observe request contents yes
Attackers can gain access to the client public key by just listening on the network no
Replies back to the client are readable only by client that initiated the request yes
Attackers can create new certificates and start using them to make requests as clients no
Servers are uniquely identified using cryptographic means no
Anyone with the server public key can observe registration contents yes
Attackers can gain access to the server public keys by just listening on the network no
Registration data can be protected from rogue agents posing as registration agents no

To configure this scenario use the following options and ensure the mcollectived can write to the plugin.aes.client_cert_dir directory:

Settings Value Descritpion
plugin.aes.send_pubkey 0 Do not send public keys
plugin.aes.learn_pubkeys 0 Do not learn public keys

Automatic public key distribution with servers sharing a key and client having unique keys

This is comparable to the older SSL plugin where all servers shared the same public / private pair. Here anyone who is part of the network can decrypt the traffic related to registration but replies to clients are still securely encrypted and visable only to them.

Here we enable the plugin.aes.learn_pubkeys feature on all servers. Your public keys will now be distributed automatically on demand but you loose some security in that anyone with access to your network or middleware can observe the contents of replies and registration data

You will not need to create unique keys for every server, you can simply copy the same one out everywhere. You still need to create keys for every user.

In order to protect against attackers creating new certificates and making requests on your network deploy a Authorization plugin that denies unknown clients.

Feature / Capability Supported
Clients are uniquely identified using cryptographic means yes
Anyone with the client public key can observe request contents yes
Attackers can gain access to the client public key by just listening on the network yes
Replies back to the client are readable only by client that initiated the request yes
Attackers can create new certificates and start using them to make requests as clients yes
Servers are uniquely identified using cryptographic means no
Anyone with the server public key can observe registration contents yes
Attackers can gain access to the server public keys by just listening on the network yes
Registration data can be protected from rogue agents posing as registration agents no

To configure this scenario use the following options and ensure the mcollectived can write to the plugin.aes.client_cert_dir directory:

Settings Value Descritpion
plugin.aes.send_pubkey 1 Send public keys
plugin.aes.learn_pubkeys 1 Learn public keys

Creating keys

Keys are created using OpenSSL. The filenames of public keys are significant you should name them so that they are unique for your network and they should match on the client and servers.

% openssl genrsa -out server-private.pem 1024
 % openssl rsa -in server-private.pem -out server-public.pem -outform PEM -pubout

Client and Server keys are made using the same basic method.

Reusing Puppet keys

Puppet managed nodes will all have keys created by Puppet already, you can reuse these if your mcollectived runs as root.

Generally Puppet stores these in /var/lib/puppet/ssl/private_keys/fqdn.pem and /var/lib/puppet/ssl/public_keys/fqdn.pem simply configure these paths for your server_private and server_public options.

Clients will still need their own keys made and distributed.

Future Roadmap

  • Depending on performance of the initial system we might validate request certificates are signed by a known CA this will provide an additional level of security preventing attackers from creating their own keys and using those on the network without also compromising the CA.
  • Private keys will be secured with a password

Configuration Options

Common Options

Setting Example / Default Description
securityprovider aes_security Enables this security provider
plugin.aes.serializer yaml or marshal Serialization to use
plugin.aes.send_pubkey 0 or 1 Send the public key with every request
plugin.aes.learn_pubkeys 0 or 1 Receive public keys from the network and cache them locally

Client Options

Setting Example / Default Description
plugin.aes.client_private /home/user/.mcollective.d/user-private.pem The private key path for the user. File must be /\w\.\-/
plugin.aes.client_public /home/user/.mcollective.d/user.pem The public key path for the user. File must be /\w\.\-/

Server Options

Setting Example / Default Description
plugin.aes.client_cert_dir /etc/mcollective/ssl/clients Where to store and load client public keys
plugin.aes.server_private /etc/mcollective/ssl/server-private.pem Server private key. File must be /\w\.\-/
plugin.aes.server_public /etc/mcollective/ssl/server-public.pem Server public key. File must be /\w\.\-/
plugin.aes.enforce_ttl 1 Enforce TTL and Message time security, warn only when disabled. 1.3.2 and newer only
Back to top