---
layout: default
title: OpenSSL based Security Plugin
---
[SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
[Registration]: registration.html
[AESPlugin]: security_aes.html
[SecurityOverview]: ../../security.html

## Overview
Implements a public/private key based message validation system using SSL
public and private keys.

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

The design goal of the plugin are two fold:

 * give different security credentials to clients and servers to avoid a compromised server from sending new client requests.
 * create a token that uniquely identify the client - based on the filename of the public key.  This creates a strong identity token for [SimpleRPCAuthorization].
 * As of 1.3.2 it cryptographically protect the TTL and Message Time properties of requests.  Aiding in securing against replay atacks.

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

Validation is as default and is provided by *MCollective::Security::Base*

Initial code was contributed by Vladimir Vuksan and modified by R.I.Pienaar

An [alternative plugin][AESPlugin] exist that encrypts data but is more work to setup and maintain.

## Setup

### Nodes
To setup you need to create a SSL key pair that is shared by all nodes.

The certificate names must match /\w\.\-/.

{% highlight console %}
 % openssl genrsa -out server-private.pem 1024
 % openssl rsa -in server-private.pem -out server-public.pem -outform PEM -pubout
{% endhighlight %}

Distribute the private and public file to */etc/mcollective/ssl* on all the nodes.
Distribute the public file to */etc/mcollective/ssl* everywhere the client code runs.

server.cfg:

{% highlight ini %}
  securityprovider = ssl
  plugin.ssl_server_private = /etc/mcollective/ssl/server-private.pem
  plugin.ssl_server_public = /etc/mcollective/ssl/server-public.pem
  plugin.ssl_client_cert_dir = /etc/mcollective/ssl/clients/
{% endhighlight %}

TTL and Message Times are protected by default 2.0.0, this means older clients will not be able to
communicate with servers running this version of the security plugin.  You can make it warn but not
deny older clients:

{% highlight ini %}
  plugin.ssl.enforce_ttl = 0
{% endhighlight %}

### Users and Clients
Now you should create a key pair for every one of your clients, here we create one
for user john - you could also if you are less concerned with client id create one
pair and share it with all clients:

The certificate names must match /\w\.\-/.

{% highlight console %}
 % openssl genrsa -out john-private.pem 1024
 % openssl rsa -in john-private.pem -out john-public.pem -outform PEM -pubout
{% endhighlight %}

Each user has a unique userid, this is based on the name of the public key.
In this example case the userid would be *'john-public'*.

Store these somewhere like:

{% highlight console %}
 /home/john/.mc/john-private.pem
 /home/john/.mc/john-public.pem
{% endhighlight %}

Every users public key needs to be distributed to all the nodes, save the john one
in a file called:

{% highlight console %}
  /etc/mcollective/ssl/clients/john-public.pem
{% endhighlight %}

If you wish to use [Registration] or auditing that sends connections over MC to a
central host you will need also put the *server-public.pem* in the clients directory.

You should be aware if you do add the node public key to the clients dir you will in
effect be weakening your overall security.  You should consider doing this only if
you also set up an Authorization method that limits the requests the nodes can make.

client.cfg:

{% highlight ini %}
 securityprovider = ssl
 plugin.ssl_server_public = /etc/mcollective/ssl/server-public.pem
 plugin.ssl_client_private = /home/john/.mc/john-private.pem
 plugin.ssl_client_public = /home/john/.mc/john-public.pem
{% endhighlight %}

If you have many clients per machine and dont want to configure the main config file
with the public/private keys you can set the following environment variables:

{% highlight console %}
 export MCOLLECTIVE_SSL_PRIVATE=/home/john/.mc/john-private.pem
 export MCOLLECTIVE_SSL_PUBLIC=/home/john/.mc/john-public.pem
{% endhighlight %}

### Serialization Method

You can choose either YAML or Marshal, the default is Marshal.  The view with optional Marshal encoding is to have a serializer supported by other languages other than Ruby to enable future integration with those.

To use YAML set this in both *client.cfg* and *server.cfg*:

{% highlight ini %}
plugin.ssl_serializer = yaml
{% endhighlight %}