X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=website%2Freference%2Fplugins%2Fsecurity_ssl.md;fp=website%2Freference%2Fplugins%2Fsecurity_ssl.md;h=12029d6d0126107504bbbc10c3df1157f9080a50;hb=b87d2f4e68281062df1913440ca5753ae63314a9;hp=0000000000000000000000000000000000000000;hpb=ab0ea530b8ac956091f17b104ab2311336cfc250;p=packages%2Fprecise%2Fmcollective.git

diff --git a/website/reference/plugins/security_ssl.md b/website/reference/plugins/security_ssl.md
new file mode 100644
index 0000000..12029d6
--- /dev/null
+++ b/website/reference/plugins/security_ssl.md
@@ -0,0 +1,124 @@
+---
+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 %}