website/reference/plugins/security_ssl.md

   1 ---
   2 layout: default
   3 title: OpenSSL based Security Plugin
   4 ---
   5 [SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
   6 [Registration]: registration.html
   7 [AESPlugin]: security_aes.html
   8 [SecurityOverview]: ../../security.html
   9
  10 ## Overview
  11 Implements a public/private key based message validation system using SSL
  12 public and private keys.
  13
  14 Please review the [Security Overview][SecurityOverview] for a general discussion about security in Marionette Collective.
  15
  16 The design goal of the plugin are two fold:
  17
  18  * give different security credentials to clients and servers to avoid a compromised server from sending new client requests.
  19  * create a token that uniquely identify the client - based on the filename of the public key.  This creates a strong identity token for [SimpleRPCAuthorization].
  20  * As of 1.3.2 it cryptographically protect the TTL and Message Time properties of requests.  Aiding in securing against replay atacks.
  21
  22 Serialization uses Marshal or YAML, which means data types in and out of mcollective
  23 will be preserved from client to server and reverse.
  24
  25 Validation is as default and is provided by *MCollective::Security::Base*
  26
  27 Initial code was contributed by Vladimir Vuksan and modified by R.I.Pienaar
  28
  29 An [alternative plugin][AESPlugin] exist that encrypts data but is more work to setup and maintain.
  30
  31 ## Setup
  32
  33 ### Nodes
  34 To setup you need to create a SSL key pair that is shared by all nodes.
  35
  36 The certificate names must match /\w\.\-/.
  37
  38 {% highlight console %}
  39  % openssl genrsa -out server-private.pem 1024
  40  % openssl rsa -in server-private.pem -out server-public.pem -outform PEM -pubout
  41 {% endhighlight %}
  42
  43 Distribute the private and public file to */etc/mcollective/ssl* on all the nodes.
  44 Distribute the public file to */etc/mcollective/ssl* everywhere the client code runs.
  45
  46 server.cfg:
  47
  48 {% highlight ini %}
  49   securityprovider = ssl
  50   plugin.ssl_server_private = /etc/mcollective/ssl/server-private.pem
  51   plugin.ssl_server_public = /etc/mcollective/ssl/server-public.pem
  52   plugin.ssl_client_cert_dir = /etc/mcollective/ssl/clients/
  53 {% endhighlight %}
  54
  55 TTL and Message Times are protected by default 2.0.0, this means older clients will not be able to
  56 communicate with servers running this version of the security plugin.  You can make it warn but not
  57 deny older clients:
  58
  59 {% highlight ini %}
  60   plugin.ssl.enforce_ttl = 0
  61 {% endhighlight %}
  62
  63 ### Users and Clients
  64 Now you should create a key pair for every one of your clients, here we create one
  65 for user john - you could also if you are less concerned with client id create one
  66 pair and share it with all clients:
  67
  68 The certificate names must match /\w\.\-/.
  69
  70 {% highlight console %}
  71  % openssl genrsa -out john-private.pem 1024
  72  % openssl rsa -in john-private.pem -out john-public.pem -outform PEM -pubout
  73 {% endhighlight %}
  74
  75 Each user has a unique userid, this is based on the name of the public key.
  76 In this example case the userid would be *'john-public'*.
  77
  78 Store these somewhere like:
  79
  80 {% highlight console %}
  81  /home/john/.mc/john-private.pem
  82  /home/john/.mc/john-public.pem
  83 {% endhighlight %}
  84
  85 Every users public key needs to be distributed to all the nodes, save the john one
  86 in a file called:
  87
  88 {% highlight console %}
  89   /etc/mcollective/ssl/clients/john-public.pem
  90 {% endhighlight %}
  91
  92 If you wish to use [Registration] or auditing that sends connections over MC to a
  93 central host you will need also put the *server-public.pem* in the clients directory.
  94
  95 You should be aware if you do add the node public key to the clients dir you will in
  96 effect be weakening your overall security.  You should consider doing this only if
  97 you also set up an Authorization method that limits the requests the nodes can make.
  98
  99 client.cfg:
 100
 101 {% highlight ini %}
 102  securityprovider = ssl
 103  plugin.ssl_server_public = /etc/mcollective/ssl/server-public.pem
 104  plugin.ssl_client_private = /home/john/.mc/john-private.pem
 105  plugin.ssl_client_public = /home/john/.mc/john-public.pem
 106 {% endhighlight %}
 107
 108 If you have many clients per machine and dont want to configure the main config file
 109 with the public/private keys you can set the following environment variables:
 110
 111 {% highlight console %}
 112  export MCOLLECTIVE_SSL_PRIVATE=/home/john/.mc/john-private.pem
 113  export MCOLLECTIVE_SSL_PUBLIC=/home/john/.mc/john-public.pem
 114 {% endhighlight %}
 115
 116 ### Serialization Method
 117
 118 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.
 119
 120 To use YAML set this in both *client.cfg* and *server.cfg*:
 121
 122 {% highlight ini %}
 123 plugin.ssl_serializer = yaml
 124 {% endhighlight %}