jordandm/chef-vault

Chef-Vault

DESCRIPTION:

Gem that allows you to encrypt passwords and certificates using the public keys of a list of chef nodes. This allows only those chef nodes to decrypt the password or certificate.

INSTALLATION:

Be sure you are running the latest version Chef. Versions earlier than 0.10.0 don't support plugins:

gem install chef

This plugin is distributed as a Ruby Gem. To install it, run:

gem install chef-vault

Depending on your system's configuration, you may need to run this command with root privileges.

CONFIGURATION:

KNIFE COMMANDS:

This plugin provides the following Knife subcommands.
Specific command options can be found by invoking the subcommand with a --help flag

knife encrypt password

Use this knife command to encrypt the username and password that you want to protect. Only Chef nodes returned by the --search at the time of encryption will be able to decrypt the password.

$ knife encrypt password --search SEARCH --username USERNAME --password PASSWORD
--admins ADMINS

In the example below, the mysql_user's password will be encrypted using the public keys of the nodes in the web_server role. In addition to the servers in the web_server role, Chef users alice, bob, and carol will also be able to decrypt the password, an encrypted data bag item.

$ knife encrypt password --search "role:web_server" --username mysql_user
--password "P@ssw0rd" --admins "alice,bob,carol"

knife decrypt password

Use this knife command to decrypt the password that is protected. This is currently hard-coded to look for an encrypted data bag named "passwords" on the Chef server.

knife decrypt password --username USERNAME

knife encrypt cert

Use this knife command to encrypt the contents of a certificate that you want to protect. Only Chef nodes returned by the --search at the time of encryption will be able to decrypt the certificate.

Typically you will decrypt the contents as part of a recipe and write them out to a certificate on your Chef node.

$ knife encrypt cert --search SEARCH --cert CERT --password PASSWORD
--name NAME --admins ADMINS

In the example below, the ~/ssl/web_server_cert.pem certificate will be encrypted using the public keys of the nodes in the web_server role. You can reference the name of the certificate (web_public_key) in a recipe when you need to decrypt it. In addition to the servers in the web_server role, Chef users alice, bob, and carol will also be able to decrypt the contents of the certificate, an encrypted data bag item.

$ knife encrypt cert --search "role:web_server" --cert
~/ssl/web_server_cert.pem --name web_public_key --admins 'alice,bob,carol'

knife decrypt cert

Use this knife command to decrypt the certificate that is protected. This is currently hard-coded to look for an encrypted data bag named certs on the Chef server.

knife decrypt cert --name NAME

USAGE IN RECIPES

To use this gem in a recipe to decrypt data you must first install the gem via a chef_gem resource. Once the gem is installed require the gem and then you can create a new instance of ChefVault.

Example Code (password)

chef_gem "chef-vault"

require 'chef-vault'

vault    = ChefVault.new("passwords")
user     = vault.user("mysql_user")
password = user.decrypt_password

Example Code (certificate)

chef_gem "chef-vault"

require 'chef-vault'

vault    = ChefVault.new("certs")
cert     = vault.certificate("web_public_key")
contents = cert.decrypt_contents

USAGE STAND ALONE

chef-vault can be used a stand alone binary to decrypt values stored in Chef. It requires that Chef is installed on the system and that you have a valid knife.rb. This is useful if you want to mix chef-vault into non-Chef recipe code, for example some other script where you want to protect a password.

It does still require that the data bag has been encrypted for the user's or client's pem and pushed to the Chef server. It mixes Chef into the gem and uses it to go grab the data bag.

Do chef-vault --help for all available options

Example usage (password)

chef-vault -u Administrator -k /etc/chef/knife.rb

Example usage (certificate)

chef-vault -c wildcard_domain_com -k /etc/chef/knife.rb

License and Author:

Author:: Kevin Moser ([email protected])
Copyright:: Copyright (c) 2013 Nordstrom, Inc.
License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.