3 title: OpenSSL based Security Plugin
5 [SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
6 [Registration]: registration.html
7 [AESPlugin]: security_aes.html
8 [SecurityOverview]: ../../security.html
11 Implements a public/private key based message validation system using SSL
12 public and private keys.
14 Please review the [Security Overview][SecurityOverview] for a general discussion about security in Marionette Collective.
16 The design goal of the plugin are two fold:
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.
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.
25 Validation is as default and is provided by *MCollective::Security::Base*
27 Initial code was contributed by Vladimir Vuksan and modified by R.I.Pienaar
29 An [alternative plugin][AESPlugin] exist that encrypts data but is more work to setup and maintain.
34 To setup you need to create a SSL key pair that is shared by all nodes.
36 The certificate names must match /\w\.\-/.
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
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.
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/
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
60 plugin.ssl.enforce_ttl = 0
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:
68 The certificate names must match /\w\.\-/.
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
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'*.
78 Store these somewhere like:
80 {% highlight console %}
81 /home/john/.mc/john-private.pem
82 /home/john/.mc/john-public.pem
85 Every users public key needs to be distributed to all the nodes, save the john one
88 {% highlight console %}
89 /etc/mcollective/ssl/clients/john-public.pem
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.
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.
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
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:
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
116 ### Serialization Method
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.
120 To use YAML set this in both *client.cfg* and *server.cfg*:
123 plugin.ssl_serializer = yaml