chef-encrypted-attributes 0.3.0 → 0.4.0

metadata.gz.sig

@@ -1 +1 @@
-(\�K�{�������y�t����T�Ú%A��+�b��L�"$�=4/c�~�� ������MS;�ī�5I>�Il������q#�Б���n�8{O�]���aD����܏gyc%��Q4�c�3��V����"E���OAqC0qX�g�K�6�X�����<!eUKS���QT<�7IڬqP���Ⱦ�[�6���=H8�zˍa�$���ty)�m!��X<C)�7vɯR����u⇹�8M�~�]S�J6��o
+���m�o�=Z&ۯ��@]��6W`�ݡ�
D��q�Oau<��`��2p\�E���6ZO	�}c���MJ�v����A&�u^��	�Aa��;��0�,�������rYn�q}!G���s�J��B��ZB���`��]�d�Σ�ত���b

data/API.md

@@ -1,174 +0,0 @@
-# Chef::EncryptedAttribute API Documentation
-
-`Chef::EncryptedAttribute` has some static methods intended to be used from cookbooks.
-
-## Static Methods
-
-### Chef::EncryptedAttribute.load(hs [, config])
-
-Reads an encrypted attribute from a hash, usually a node attribute.
-
-* `hs` - An encrypted hash, usually a node attribute. For example: `node["myapp"]["ftp_password"]`.
-* `config` - A configuration hash (optional). For example: `{ :partial_search => false }`.
-
-Returns the attribute in clear text, decrypted.
-
-An exception is thrown if the attribute cannot be decrypted or no encrypted attribute is found.
-
-### Chef::EncryptedAttribute.create(value [, config])
-
-Creates an encrypted attribute. The returned value should be saved in a node attribute, like `node.normal[...] = `.
-
-* `value` - The value to be encrypted. Can be a boolean, a number, a string, an array or a hash (the value will be converted to JSON internally).
-* `config` - A configuration hash (optional). For example: `{ :client_search => "admin:true" }`.
-
-Returns the encrypted attribute.
-
-An exception is thrown if any error arises in the encryption process.
-
-### Chef::EncryptedAttribute.update(hs [, config])
-
-Updates who can read the attribute. This is intended to be used to update to the new nodes returned by `:client_search` and `:node_search` or perhaps global configuration changes.
-
-For example, in case new nodes are added or some are removed, and the clients returned by `:client_search` or `:node_search` are different, this `#update` method will decrypt the attribute and encrypt it again for the new nodes (or remove the old ones).
-
-If an update is made, the shared secrets are regenerated.
-
-* `hs` - This must be a node encrypted attribute, this attribute will be updated, so it is mandatory to specify the type (usually `normal`). For example: `node.normal["myapp"]["ftp_password"]`.
-* `config` - A configuration hash (optional). Surely you want this `#update` method to use the same `config` that the `#create` call.
-
-Returns `true` if the encrypted attribute has been updated, `false` if not.
-
-An exception is thrown if there is any error in the updating process.
-
-### Chef::EncryptedAttribute.exist?(hs)
-
-Checks whether an encrypted attribute exists.
-
-* `hs` - An encrypted hash, usually a node attribute. The attribute type can be specified but is not necessary. For example: `node["myapp"]["ftp_password"]`.
-
-Returns `true` if an encrypted attribute is found, `false` if not.
-
-### Chef::EncryptedAttribute.load_from_node(name, attr_ary [, config])
-
-Reads an encrypted attribute from a remote node.
-
-* `name` - The node name.
-* `attr_ary` - The attribute path as *array of strings*. For example: `[ "myapp", "ftp_password" ]`.
-* `config` - A configuration hash (optional). For example: `{ :partial_search => false }`.
-
-An exception is thrown if the attribute cannot be decrypted or no encrypted attribute is found.
-
-### Chef::EncryptedAttribute.create_on_node(name, attr_ary, value [, config])
-
-Creates an encrypted attribute on a remote node.
-
-* `name` - The node name.
-* `attr_ary` - The attribute path as *array of strings*. For example: `[ "myapp", "ftp_password" ]`.
-* `value` - The value to be encrypted. Can be a boolean, a number, a string, an array or a hash (the value will be converted to JSON internally).
-* `config` - A configuration hash (optional). For example: `{ :client_search => "admin:true" }`.
-
-An exception is thrown if any error arises in the encryption process.
-
-This method **requires admin privileges**. So in most cases, cannot be used from cookbooks.
-
-### Chef::EncryptedAttribute.update_on_node(name, attr_ary [, config])
-
-Updates who can read the attribute.
-
-* `name` - The node name.
-* `attr_ary` - The attribute path as *array of strings*. For example: `[ "myapp", "ftp_password" ]`.
-* `config` - A configuration hash (optional). Surely you want this `#update_on_node` method to use the same `config` that the `#create` call.
-
-Returns `true` if the encrypted attribute has been updated, `false` if not.
-
-An exception is thrown if there is any error in the updating process.
-
-This method **requires admin privileges**. So in most cases, cannot be used from cookbooks.
-
-### Chef::EncryptedAttribute.exist_on_node?(name, attr_ary [, config])
-
-Checks whether an encrypted attribute exists in a remote node.
-
-* `name` - The node name.
-* `attr_ary` - The attribute path as *array of strings*. For example: `[ "myapp", "ftp_password" ]`.
-* `config` - A configuration hash (optional). For example: `{ :partial_search => false }`.
-
-Returns `true` if an encrypted attribute is found, `false` if not.
-
-## Configuration
-
-All the methods read the default configuration from the `Chef::Config[:encrypted_attributes]` hash. Most of methods also support setting some configuration parameters as last argument. Both the global and the method argument configuration will be merged.
-
-If the configuration value to be merged is an array or a hash (for example `keys`), the method argument configuration value has preference over the global configuration. Arrays and hashes are not merged.
-
-Both `Chef::Config[:encrypted_attributes]` and method's `config` parameter should be a hash which may have any of the following keys:
-
-* `:version` - `EncryptedMash` format version to use, by default `1` is used which is recommended. The version `2` uses [GCM](http://en.wikipedia.org/wiki/Galois/Counter_Mode) and probably should be considered the most secure, but it is disabled by default because it has some more requirements:
- * Ruby `>= 2`.
- * OpenSSL `>= 1.0.1`.
-* `:partial_search` - Whether to use Chef Server partial search, enabled by default. It may not work in some old versions of Chef Server.
-* `:client_search` - Search query for clients allowed to read the encrypted attribute. Can be a simple string or an array of queries to be *OR*-ed.
-* `:node_search` - Search query for nodes allowed to read the encrypted attribute. Can be a simple string or an array of queries to be *OR*-ed.
-* `:users` - Array of user names to be allowed to read the encrypted attribute(s). `"*"` to allow access to all users. Keep in mind that only admin clients or admin users are allowed to read user public keys. It is **not recommended** to use this from cookbooks unless you know what you are doing.
-* `:keys` - raw RSA public keys to be allowed to read encrypted attributes(s), in PEM (string) format. Can be client public keys, user public keys or any other RSA public key.
-
-For example, to disable Partial Search globally:
-
-```ruby
-Chef::Config[:encrypted_attributes][:partial_search] = false
-
-# ftp_pass = Chef::EncryptedAttribute.load(node["myapp"]["ftp_password"])
-# ...
-```
-
-To disable Partial Search locally:
-
-```ruby
-ftp_pass = Chef::EncryptedAttribute.load(node["myapp"]["ftp_password"], { :partial_search => false })
-```
-
-To use protocol version 2 globally, which uses [GCM](http://en.wikipedia.org/wiki/Galois/Counter_Mode):
-
-```ruby
-Chef::Config[:encrypted_attributes][:version] = 2
-# ...
-```
-
-If you want to use knife to work with encrypted attributes, surely you will need to save your Chef User public keys in a Data Bag (there is no need to encrypt them because they are public) and add them to the `:keys` configuration option. See the [Example Using User Keys Data Bag](README.md#example-using-user-keys-data-bag) in the README for more information on this.
-
-## Caches
-
-This API uses some LRU caches to avoid making many requests to the Chef Server. All the caches are global and has the following methods:
-
-* `max_size` - Gets or sets the cache maximum item size.
-* `clear` - To empty the cache.
-* `[]` - To read a cache value (used internally).
-* `[]=` - To set a cache value (used internally).
-
-This are the currently available caches:
-
-* `Chef::EncryptedAttribute::RemoteClients.cache` - Caches the `:client_search` query results (max_size: `1024`).
-* `Chef::EncryptedAttribute::RemoteNodes.cache` - Caches the `:node_search` query results (max_size: `1024`).
-* `Chef::EncryptedAttribute::RemoteUsers.cache` - Caches the Chef Users public keys (max_size: `1024`).
-* `Chef::EncryptedAttribute::RemoteNode.cache` - Caches the node (encrypted) attributes. Disabled by default (max_size: `0`).
-
-### Clear All the Caches
-
-You can clear all the caches with the following code:
-
-```ruby
-Chef::EncryptedAttribute::RemoteClients.cache.clear
-Chef::EncryptedAttribute::RemoteUsers.cache.clear
-Chef::EncryptedAttribute::RemoteNode.cache.clear
-```
-
-### Disable All the Caches
-
-You can disable all the caches with the following code:
-
-```ruby
-Chef::EncryptedAttribute::RemoteClients.cache.max_size(0)
-Chef::EncryptedAttribute::RemoteUsers.cache.max_size(0)
-Chef::EncryptedAttribute::RemoteNode.cache.max_size(0)
-```

data/INTERNAL.md

@@ -1,166 +0,0 @@
-# Internal Documentation
-
-## EncryptedAttribute Class
-
-This class contains both static and instance level public methods. Internally, all work with `EncryptedMash` object instances.
-
-The **static methods** are intended to be used from Cookbooks. The attributes are encrypted only for the local node by default. The static `*_on_node` methods can be used also, although they have not been designed for this purpose (have not been tested).
-
-The **instance methods** are intended to be used from `knife` or external libraries. Usually only the `*_from_node/*_on_node` instance methods will be used. These methods will grant access only to the remote node by default.
-
-## EncryptedMash Class
-
-This is the most basic encrypted object, which inherits from `Chef::Mash`.
-
-Currently two `EncryptedMash` versions exists. But you can create your own versions and name it with the `Chef::EncryptedAttribute::EncryptedMash::Version` prefix.
-
-### EncryptedMash::Version0
-
-This is the first version, considered old. Uses public key cryptography (PKI) to encrypt the data. There is no shared secret or HMAC for data integrity checking.
-
-#### EncryptedMash::Version0 Structure
-
-If you try to read this encrypted attribute structure, you can see a `Chef::Mash` attribute with the following content:
-
-```
-EncryptedMash
-└── encrypted_data
-    ├── pub_key_hash1: The data encrypted using PKI for the public key 1 (base64)
-    ├── pub_key_hash2: The data encrypted using PKI for the public key 2 (base64)
-    └── ...
-```
-
-The `public_key_hash1` key value is the *SHA1* of the public key used for encryption.
-
-Its content is the data encoded in *JSON*, then encrypted with the public key, and finally encoded in *base64*. The encryption is done using the *RSA* algorithm (PKI).
-
-### EncryptedMash::Version1 (default)
-
-This is the `EncryptedMash` version used by default. Uses public key cryptography (PKI) to encrypt a shared secret. Then this shared secret is used to encrypt the data.
-
-* This implementation can be improved, is not optimized either for performance or for space.
-* Every time the `EncryptedAttribute` is updated, all the shared secrets are regenerated.
-
-#### EncryptedMash::Version1 Structure
-
-If you try to read this encrypted attribute structure, you can see a *Mash* attribute with the following content:
-
-```
-EncryptedMash
-├── chef_type: "encrypted_attribute" (string).
-├── x_json_class: The used `EncryptedMash` version class name (string).
-├── encrypted_data
-│   ├── cipher: The used PKI algorithm, "aes-256-cbc" (string).
-│   ├── data: PKI encrypted data (base64).
-│   └── iv: Initialization vector (in base64).
-├── encrypted_secret
-│   ├── pub_key_hash1: The shared secrets encrypted for the public key 1 (base64).
-│   ├── pub_key_hash2: The shared secrets encrypted for the public key 2 (base64).
-│   └── ...
-└── hmac
-    ├── cipher: The used HMAC algorithm, currently ignored and always "sha256" (string).
-    └── data: Hash-based message authentication code value (base64).
-```
-
-* `x_json_class` field is used, with the `x_` prefix, to be easily integrated with Chef in the future.
-
-##### EncryptedMash[encrypted_data][data]
-
-The data inside `encrypted_data` is symmetrically encrypted using the secret shared key. The data is converted to *JSON* before the encryption, then encrypted and finally encoded in *base64*. By default, the `"aes-256-cbc"` algorithm is used for encryption.
-
-After decryption, the *JSON* has the following structure:
-
-```
-└── encrypted_data
-    └── data (symmetrically encrypted JSON in base64)
-        └── content: attribute content as a Mash.
-```
-
-* In the future, this structure may contain some metadata like default configuration values.
-
-##### EncryptedMash[encrypted_secret][pub_key_hash1]
-
-The `public_key_hash1` key value is the *SHA1* of the public key used for encryption.
-
-Its content is the encrypted shared secrets in *base64*. The encryption is done using the *RSA* algorithm (PKI).
-
-After decryption, you find the following structure in *JSON*:
-
-```
-└── encrypted_secret
-    └── pub_key_hash1 (PKI encrypted JSON in base64)
-        ├── data: The shared secret used to encrypt the data (base64).
-        └── hmac: The shared secret used for the HMAC calculation (base64).
-```
-
-##### EncryptedMash[hmac][data]
-
-The HMAC data is in *base64*. The hashing algorithm used is `"sha256"`.
-
-The following data is used in a alphabetically sorted *JSON* to calculate the HMAC:
-
-```
-Data to calculate the HMAC from
-├── cipher: The algorithm used for `encrypted_data` encryption ("aes-256-cbc").
-├── data: The `encrypted_data` data content after the encryption (encrypt-then-mac).
-└── iv: The initialization vector used to encrypt the encrypted_data.
-```
-
-* All the data required for decryption is included in the HMAC (except the secret key, of course): `cipher`, `data` and `iv`.
-* The data used to calculate the HMAC is the encrypted data, not the clear text data (**Encrypt-then-MAC**).
-* The secret used to calculate the HMAC is not the same as the secret used to encrypt the data.
-* The secret used to calculate the HMAC is shared inside `encrypted_secret` field with the data secret.
-
-### EncryptedMash::Version2
-
-Uses public key cryptography (PKI) to encrypt a shared secret. Then this shared secret is used to encrypt the data using [GCM](http://en.wikipedia.org/wiki/Galois/Counter_Mode).
-
-* This protocol version is based on the [Chef 12 Encrypted Data Bags Version 3 implementation](https://github.com/opscode/chef/pull/1591).
-* To use it, the following **special requirements** must be met:
- * Ruby `>= 2`.
- * OpenSSL `>= 1.0.1`.
-* This implementation can be improved, is not optimized either for performance or for space.
-* Every time the `EncryptedAttribute` is updated, all the shared secrets are regenerated.
-
-#### EncryptedMash::Version2 Structure
-
-If you try to read this encrypted attribute structure, you can see a *Mash* attribute with the following content:
-
-```
-EncryptedMash
-├── chef_type: "encrypted_attribute" (string).
-├── x_json_class: The used `EncryptedMash` version class name (string).
-├── encrypted_data
-│   ├── cipher: The used PKI algorithm, "aes-256-gcm" (string).
-│   ├── data: PKI encrypted data (base64).
-│   ├── auth_tag: GCM authentication tag (base64).
-│   └── iv: Initialization vector (in base64).
-└── encrypted_secret
-    ├── pub_key_hash1: The shared secret encrypted for the public key 1 (base64).
-    ├── pub_key_hash2: The shared secret encrypted for the public key 2 (base64).
-    └── ...
-```
-
-* `x_json_class` field is used, with the `x_` prefix, to be easily integrated with Chef in the future.
-
-##### EncryptedMash[encrypted_data][data]
-
-The data inside `encrypted_data` is symmetrically encrypted using the secret shared key. The data is converted to *JSON* before the encryption, then encrypted and finally encoded in *base64*. By default, the `"aes-256-gcm"` algorithm is used for encryption.
-
-After decryption, the *JSON* has the following structure:
-
-```
-└── encrypted_data
-    └── data (symmetrically encrypted JSON in base64)
-        └── content: attribute content as a Mash.
-```
-
-* In the future, this structure may contain some metadata like default configuration values.
-
-##### EncryptedMash[encrypted_secret][pub_key_hash1]
-
-The `public_key_hash1` key value is the *SHA1* of the public key used for encryption.
-
-Its content is the encrypted shared secret in *raw*. The encryption is done using the *RSA* algorithm (PKI).
-
-After decryption, you find the the shared secret in *raw* (in *Version1* this is a *JSON* in *base64*).