{"_id":"54fda39021538c21006c49ba","githubsync":"","user":"54bf8cd9dcfc4d0d00a1a19e","category":{"_id":"54fea8975c4ab10d00ef4279","version":"54fda38e21538c21006c49a6","__v":2,"pages":["54fea91a26230917004adcad","54ff12b95c4ab10d00ef42e5"],"project":"545e249c7ca5470800b3a1b2","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-10T08:17:27.521Z","from_sync":false,"order":4,"slug":"encryption","title":"Encryption"},"project":"545e249c7ca5470800b3a1b2","version":{"_id":"54fda38e21538c21006c49a6","__v":3,"forked_from":"54eb4535615ffc19003059f0","project":"545e249c7ca5470800b3a1b2","createdAt":"2015-03-09T13:43:42.927Z","releaseDate":"2015-03-09T13:43:42.927Z","categories":["54fda38f21538c21006c49a7","54fda38f21538c21006c49a8","54fda38f21538c21006c49a9","54fda38f21538c21006c49aa","54fda38f21538c21006c49ab","54fda3d347f93619001d2ae2","54fea8975c4ab10d00ef4279"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5.0"},"__v":4,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-02-09T14:02:19.308Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"If you haven't done so, you should have a look at our [Introduction to encryption in ElectricSheep.IO](doc:introduction).\n\nYou can use a GPG keypair to encrypt informations which you will want to put into your _Sheepfile_ and keep them private. This way you may place your _Sheepfile_ under version control, even in a public repository, without compromising your credentials.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How it works\"\n}\n[/block]\nElectricSheep.IO relies on [GPG](https://www.gnupg.org/) to encrypt and decrypt secrets using  public key cryptography. Public key cryptography involves a _public key_ and a _private key_. You use the _public key_ to encrypt secrets while your ElectricSheep.io installation use its _private key_ to decrypt them at runtime.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Setup\"\n}\n[/block]\n### Prerequisites\n\nGPG should be installed on the target system.\n\n### Generate a GPG keypair\n\nThe first step is to generate and export a keypair. You'll then deploy the _private key_ to the server running ElectricSheep.IO, and use the _public key_ to encrypt credentials. To generate a GPG keypair:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"gpg --gen-key\",\n      \"language\": \"shell\",\n      \"name\": \"Keypair generation\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"At the time of speaking, ES.io **does not support passphrases** so you should use a blank one.\",\n  \"title\": \"Passphrases\"\n}\n[/block]\nYou'll be asked to provide arbitrary values for \"Real name\" (e.g. \"ElectricSheep.IO\") and email (e.g. \"electricsheep.io:::at:::your-company.com\"). GPG defaults for other parameters are secure, so feel free to use them.\n\nRemember to write down the email address you provided as it will be used to export the keys during the next step.\n\n### Export the keys\n\nUse the email provided in the previous step as the key identifier and export the keys to a specific (and secure) location:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Export the public key (replace </path/to> with the actual path)\\ngpg  --batch --armor --output </path/to>/electric_sheep.public.gpg.asc --export electricsheep.io@your-company.com\\n# Export the private key (replace </path/to> with the actual path)\\ngpg  --batch --armor --output </path/to>/electric_sheep.private.gpg.asc --export-secret-key electricsheep.io@your-company.com\",\n      \"language\": \"shell\",\n      \"name\": \"Export keys\"\n    }\n  ]\n}\n[/block]\nStore a copy of your keys in a safe place and place the _private key_ in a secure location on the server hosting ES.IO. Distributing the _public key_ does not put you at risk, so you may communicate it to your teammates or event make it available somewhere on the Web.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the keys\"\n}\n[/block]\nElectricSheep.IO provides the `encrypt` command to encrypt private information using a GPG _public key_:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Replace </path/to> with the actual path to the public key\\nelectric_sheep encrypt -k </path/to>/electric_sheep.public.gpg.asc \\\"PASSWORD\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Encrypt secret\"\n    }\n  ]\n}\n[/block]\nThe command outputs the encrypted data so that you may use it as the argument of the `encrypted` function in your _Sheepfile_. You'll also have to make ES.IO aware of the location of the _private key_ using the `decrypt` verb:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Replace </path/to> with the actual key location\\ndecrypt with: \\\"</path/to>/electric_sheep.private.gpg.asc\\\"\\n\\njob \\\"mysql-backup\\\" do\\n  resource \\\"database\\\", name: \\\"my-db\\\", host: \\\"db-host\\\"\\n  remotely as: \\\"operator\\\" do\\n    mysql_dump user: \\\"user\\\", password: encrypted(\\\"hQEMA5gb42cxCFIzAQf+Phn+Y/z+SLroDX0/d0Qg6YinauaKEODUvnHwxxns3LCwCY2/YWQdP076AlX2o8zU/0/hDXUksakCFlRn+kYL3amT8yNbcApwo6Z6pDLtYCWEp1M0lx0N9vVYvdUF5/R9nh1eT5zJqOIsVmFau4V4WeJ/V67zXNrd3nXWoZpMH+HlO1qo+vL9p2hDfm/zIYDaZI2SJ90zZbwsfpYbjgirVjuHtYVN2FCti3k1k2dc5fmzzA6WE82w7rnLlv6sV3wSo3xsChgSdj1JJw0kkJ8XV0gYuvT/IGgQEIQiwSVQzwhXPdJGaPXnZ+P3UpIMXQQqq52QF+BkZvkbs5nCqI+EqNJDAXVen691DvgJjHp4cIunZKJC9H3EWftw8XcMORQjqlokPkRw9ZJn3X58WN7x4M9mC1o+Fp2VPhFv/Qpeju8GZ9d9Zw===bYzA\\\")\\n  end\\nend\",\n      \"language\": \"ruby\",\n      \"name\": \"Sheepfile\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Output format of the `encrypt` command\",\n  \"body\": \"By default, ES.IO removes the PGP headers and carriage returns from the GPG output so it fits on a single line. If you prefer a standard ASCII-armored output, set the `--standard-armor` option and use heredoc in your _Sheepfile_.\"\n}\n[/block]\nSee the [Command Line Reference](doc:command-line) for all options of the `encrypt` command.","excerpt":"Keep your passwords, access keys and other secrets private","slug":"encrypt-your-credentials","type":"basic","title":"Encrypt your credentials"}

Encrypt your credentials

Keep your passwords, access keys and other secrets private

If you haven't done so, you should have a look at our [Introduction to encryption in ElectricSheep.IO](doc:introduction). You can use a GPG keypair to encrypt informations which you will want to put into your _Sheepfile_ and keep them private. This way you may place your _Sheepfile_ under version control, even in a public repository, without compromising your credentials. [block:api-header] { "type": "basic", "title": "How it works" } [/block] ElectricSheep.IO relies on [GPG](https://www.gnupg.org/) to encrypt and decrypt secrets using public key cryptography. Public key cryptography involves a _public key_ and a _private key_. You use the _public key_ to encrypt secrets while your ElectricSheep.io installation use its _private key_ to decrypt them at runtime. [block:api-header] { "type": "basic", "title": "Setup" } [/block] ### Prerequisites GPG should be installed on the target system. ### Generate a GPG keypair The first step is to generate and export a keypair. You'll then deploy the _private key_ to the server running ElectricSheep.IO, and use the _public key_ to encrypt credentials. To generate a GPG keypair: [block:code] { "codes": [ { "code": "gpg --gen-key", "language": "shell", "name": "Keypair generation" } ] } [/block] [block:callout] { "type": "warning", "body": "At the time of speaking, ES.io **does not support passphrases** so you should use a blank one.", "title": "Passphrases" } [/block] You'll be asked to provide arbitrary values for "Real name" (e.g. "ElectricSheep.IO") and email (e.g. "electricsheep.io@your-company.com"). GPG defaults for other parameters are secure, so feel free to use them. Remember to write down the email address you provided as it will be used to export the keys during the next step. ### Export the keys Use the email provided in the previous step as the key identifier and export the keys to a specific (and secure) location: [block:code] { "codes": [ { "code": "# Export the public key (replace </path/to> with the actual path)\ngpg --batch --armor --output </path/to>/electric_sheep.public.gpg.asc --export electricsheep.io@your-company.com\n# Export the private key (replace </path/to> with the actual path)\ngpg --batch --armor --output </path/to>/electric_sheep.private.gpg.asc --export-secret-key electricsheep.io@your-company.com", "language": "shell", "name": "Export keys" } ] } [/block] Store a copy of your keys in a safe place and place the _private key_ in a secure location on the server hosting ES.IO. Distributing the _public key_ does not put you at risk, so you may communicate it to your teammates or event make it available somewhere on the Web. [block:api-header] { "type": "basic", "title": "Using the keys" } [/block] ElectricSheep.IO provides the `encrypt` command to encrypt private information using a GPG _public key_: [block:code] { "codes": [ { "code": "# Replace </path/to> with the actual path to the public key\nelectric_sheep encrypt -k </path/to>/electric_sheep.public.gpg.asc \"PASSWORD\"", "language": "shell", "name": "Encrypt secret" } ] } [/block] The command outputs the encrypted data so that you may use it as the argument of the `encrypted` function in your _Sheepfile_. You'll also have to make ES.IO aware of the location of the _private key_ using the `decrypt` verb: [block:code] { "codes": [ { "code": "# Replace </path/to> with the actual key location\ndecrypt with: \"</path/to>/electric_sheep.private.gpg.asc\"\n\njob \"mysql-backup\" do\n resource \"database\", name: \"my-db\", host: \"db-host\"\n remotely as: \"operator\" do\n mysql_dump user: \"user\", password: encrypted(\"hQEMA5gb42cxCFIzAQf+Phn+Y/z+SLroDX0/d0Qg6YinauaKEODUvnHwxxns3LCwCY2/YWQdP076AlX2o8zU/0/hDXUksakCFlRn+kYL3amT8yNbcApwo6Z6pDLtYCWEp1M0lx0N9vVYvdUF5/R9nh1eT5zJqOIsVmFau4V4WeJ/V67zXNrd3nXWoZpMH+HlO1qo+vL9p2hDfm/zIYDaZI2SJ90zZbwsfpYbjgirVjuHtYVN2FCti3k1k2dc5fmzzA6WE82w7rnLlv6sV3wSo3xsChgSdj1JJw0kkJ8XV0gYuvT/IGgQEIQiwSVQzwhXPdJGaPXnZ+P3UpIMXQQqq52QF+BkZvkbs5nCqI+EqNJDAXVen691DvgJjHp4cIunZKJC9H3EWftw8XcMORQjqlokPkRw9ZJn3X58WN7x4M9mC1o+Fp2VPhFv/Qpeju8GZ9d9Zw===bYzA\")\n end\nend", "language": "ruby", "name": "Sheepfile" } ] } [/block] [block:callout] { "type": "info", "title": "Output format of the `encrypt` command", "body": "By default, ES.IO removes the PGP headers and carriage returns from the GPG output so it fits on a single line. If you prefer a standard ASCII-armored output, set the `--standard-armor` option and use heredoc in your _Sheepfile_." } [/block] See the [Command Line Reference](doc:command-line) for all options of the `encrypt` command.