{ "info": { "author": "", "author_email": "", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Intended Audience :: System Administrators", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7" ], "description": "# Cred*Smash*\n\nThis is a fork of [credstash](https://github.com/fugue/credstash), to add \nsome utilities I find useful, see `HISTORY.md` for details.\n\n## Quick Installation\n1. `pip install credsmash[yaml, templates]`\n2. Set up a key called `credsmash` in KMS\n3. Make sure you have AWS creds in a place that boto/botocore can read \n them (eg, [Use environment `AWS_CONFIG_FILE`](http://boto3.readthedocs.io/en/latest/guide/configuration.html#environment-variables))\n4. `credsmash setup-dynamodb`\n\n\n## What is this?\nSoftware systems often need access to some shared credential. For example, \nyour web application needs access to a database password, or an API key for some \nthird party service.\n\nSome organizations build complete credential-management systems, but for most of us, \nmanaging these credentials is usually an afterthought. In the best case, people use \nsystems like ansible-vault, which does a pretty good job, but leads to other management \nissues (like where/how to store the master key). A lot of credential management schemes \namount to just SCP'ing a `secrets` file out to the fleet, or in the worst case, burning \nsecrets into the SCM (do a github search on `password`).\n\nCredSmash is a very simple, easy to use credential management and distribution system \nthat uses AWS Key Management Service (KMS) for key wrapping and master-key storage, \nand DynamoDB for credential storage and sharing.\n\n## How does it work?\nAfter you complete the steps in the `Setup` section, you will have an encryption key \nin KMS (in this README, we will refer to that key as the `master key`), and a credential\nstorage table in DDB.\n\n### Stashing Secrets\nWhenever you want to store/share a credential, such as a database password, you simply \nrun `echo [credential-value] | credsmash put [credential-name] -`. \nFor example, `echo 'supersecretpassword1234' | credsmash put myapp.db.prod -`. credsmash will\ngo to the KMS and generate a unique data encryption key, which itself is encrypted by the\nmaster key (this is called key wrapping). credsmash will use the data encryption key to\nencrypt the credential value. It will then store the encrypted credential, along with the \nwrapped (encrypted) data encryption key in the credential store in DynamoDB.\n\n### Getting Secrets\nWhen you want to fetch the credential, for example as part of the bootstrap process on \nyour web-server, you simply do `credsmash get [credential-name]`. For example, \n`export DB_PASSWORD=$(credsmash get myapp.db.prod)`. When you run `get`, \ncredsmash will go and fetch the encrypted credential and the wrapped encryption \nkey from the credential store (DynamoDB). It will then send the wrapped encryption key to \nKMS, where it is decrypted with the master key. credsmash then uses the decrypted data \nencryption key to decrypt the credential. The credential is printed to `stdout`, so you \ncan use it in scripts or assign it to environment variables.\n\n### Controlling and Auditing Secrets\nOptionally, you can include any number of [Encryption Context](http://docs.aws.amazon.com/kms/latest/developerguide/encrypt-context.html)\nkey value pairs to associate with the credential. The exact set of encryption context \nkey value pairs that were associated with the credential when it was `put` in DynamoDB \nmust be provided in the `get` request to successfully decrypt the credential. These \nencryption context key value pairs are useful to provide auditing context to the encryption\nand decryption operations in your CloudTrail logs. They are also useful for constraining \naccess to a given credsmash stored credential by using KMS Key Policy conditions and KMS \nGrant conditions. Doing so allows you to, for example, make sure that your database servers \nand web-servers can read the web-server DB user password but your database servers can not \nread your web-servers TLS/SSL certificate's private key. A `put` request with encryption \ncontext would look like \n`echo 'supersecretpassword1234' | credsmash put myapp.db.prod - --context app.tier db --context environment prod`. \nIn order for your web-servers to read that same credential they would execute a `get` call \nlike `export DB_PASSWORD=$(credsmash get myapp.db.prod --context environment prod --context app.tier db)`\n\n### Versioning Secrets\nCredentials stored in the credential-store are versioned and immutable. That is, if \nyou `put` a credential called `foo` with a version of `1` and a value of `bar`, \nthen foo version 1 will always have a value of bar, and there is no way in `credsmash` to \nchange its value (although you could go fiddle with the bits in DDB, but you shouldn't do that). \nCredential rotation is handed through versions. Suppose you do `echo 'bar' | credsmash put foo -`, and \nthen decide later to rotate `foo`, you can put version 2 of `foo` by doing \n`echo 'baz' | credsmash put foo - -v 2 `. \nThe next time you do `credsmash get foo`, it will return `baz`. You can get specific credential versions\nas well (with the same `-v` flag). You can fetch a list of all credentials in the \ncredential-store and their versions with the `list` command.\n\nIf you use incrementing integer version numbers (for example, `[1, 2, 3, ...]`), then you can \nsimply skip the `-v` flag with the `put` command to automatically increment the version number. \nHowever, because of the lexicographical sorting in DynamoDB, `credsmash` will left-pad \nthe version representation with zeros (for example, `[001, 025, 103, ...]`, except to 19 characters,\nenough to handle `sys.maxint` on 64-bit systems).\n\n## Dependencies\ncredsmash uses the following AWS services:\n* AWS Key Management Service (KMS) - for master key management and key wrapping\n* AWS Identity and Access Management - for access control\n* Amazon DynamoDB - for credential storage\n\n## Setup\n### tl;dr\n1. Set up a key called `credsmash` in KMS\n2. `pip install credsmash`\n3. Make sure you have AWS creds in a place that boto/botocore can read them\n4. Run `credsmash setup-dynamodb`\n\n### Setting up KMS\n`credsmash` will not currently set up your KMS master key. To create a KMS master key,\n\n1. Go to the AWS console\n2. Go to the IAM console/tab\n3. Click \"Encryption Keys\" in the left\n4. Click \"Create Key\". For alias, put \"credsmash\". If you want to use a different name, be sure to pass it to credsmash with the `-k` flag\n5. Decide what IAM principals you want to be able to manage the key\n6. On the \"Key Usage Permissions\" screen, pick the IAM users/roles that will be using credsmash (you can change your mind later)\n7. Done!\n\n### Setting up credsmash\nThe easiest thing to do is to just run `pip install credsmash`. That will download and install credsmash and its dependencies (boto and PyCypto).\n\nThe second easiest thing to do is to do `python setup.py install` in the `credsmash` directory.\n\nThe python dependencies for credsmash are in the `requirements.txt` file. You can install them with `pip install -r requirements.txt`.\n\nIn all cases, you will need a C compiler for building `PyCrypto` (you can install `gcc` by doing `apt-get install gcc` or `yum install gcc`).\n\nYou will need to have AWS credentials accessible to boto/botocore. The easiest thing to do is to run credsmash on an EC2 instance with an IAM role. Alternatively, you can put AWS credentials in the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. Or, you can put them in a file (see http://boto.readthedocs.org/en/latest/boto_config_tut.html).\n\nYou can specify the region in which `credsmash` should operate by using the `-r` flag, or by setting the `AWS_DEFAULT_REGION` environment variable. Note that the command line flag takes precedence over the environment variable. If you set neither, then `credsmash` will operate against us-east-1.\n\nOnce credentials are in place, run `credsmash setup-dynamodb`. This will create the DDB table needed for credential storage.\n\n### Working with multiple AWS accounts (profiles)\n\nIf you need to work with multiple AWS accounts, an easy thing to do is to set up multiple profiles in \nyour `~/.aws/credentials` file. For example,\n\n```\n[dev]\naws_access_key_id = AKIDEXAMPLEASDFASDF\naws_secret_access_key = SKIDEXAMPLE2103429812039423\n[prod]\naws_access_key_id= AKIDEXAMPLEASDFASDF\naws_secret_access_key= SKIDEXAMPLE2103429812039423\n```\n\nThen, by setting the `AWS_PROFILE` environment variable to the name of the profile, (dev or prod, in this case), \nyou can point credsmash at the appropriate account.\n\nSee https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs for more information.\n\n## Usage\n```\nUsage: credsmash [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n -c, --config PATH\n -t, --table-name TEXT DynamoDB table to use for credential storage\n -k, --key-id TEXT the KMS key-id of the master key to use. See the\n README for more information. Defaults to\n alias/credsmash\n --context ... the KMS encryption context to use.Only works if\n --key-id is passed.\n --help Show this message and exit.\n\nCommands:\n delete Delete every version of a single secret\n delete-many Delete every version of all matching secrets\n find-many Find all secrets matching \n find-one Find exactly one secret matching \n get Fetch the latest, or a specific version of a...\n get-all Fetch the latest version of all secrets\n list List all secrets & their versions.\n prune Delete all but the latest version of a single...\n prune-many Delete all but the latest version of all...\n put Store a secret\n put-many Store many secrets\n render-template Render a configuration template....\n render-templates Render multiple configuration templates -...\n setup-dynamodb Setup the credential table in AWS DynamoDB\n```\n\n## IAM Policies\n\n### Secret Writer\nYou can put or write secrets to credsmash by either using KMS Key Grants, KMS Key Policies,\nor IAM Policies. If you are using IAM Policies, the following IAM permissions are the minimum \nrequired to be able to put or write secrets:\n\n```\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Action\": [\n \"kms:GenerateDataKey\"\n ],\n \"Effect\": \"Allow\",\n \"Resource\": \"arn:aws:kms:us-east-1:AWSACCOUNTID:key/KEY-GUID\"\n },\n {\n \"Action\": [\n \"dynamodb:PutItem\"\n ],\n \"Effect\": \"Allow\",\n \"Resource\": \"arn:aws:dynamodb:us-east-1:AWSACCOUNTID:table/credential-store\"\n }\n ]\n}\n```\nIf you are using Key Policies or Grants, then the `kms:GenerateDataKey` is not required in the policy for the \nIAM user/group/role. Replace `AWSACCOUNTID` with the account ID for your table, and replace the KEY-GUID with the \nidentifier for your KMS key (which you can find in the KMS console).\n\n### Secret Reader\nYou can read secrets from credsmash with the get or getall actions by either using KMS Key Grants, KMS Key \nPolicies, or IAM Policies. If you are using IAM Policies, the following IAM permissions are the minimum \nrequired to be able to get or read secrets:\n```\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Action\": [\n \"kms:Decrypt\"\n ],\n \"Effect\": \"Allow\",\n \"Resource\": \"arn:aws:kms:us-east-1:AWSACCOUNTID:key/KEY-GUID\"\n },\n {\n \"Action\": [\n \"dynamodb:GetItem\",\n \"dynamodb:Query\",\n \"dynamodb:Scan\"\n ],\n \"Effect\": \"Allow\",\n \"Resource\": \"arn:aws:dynamodb:us-east-1:AWSACCOUNTID:table/credential-store\"\n }\n ]\n}\n```\nIf you are using Key Policies or Grants, then the `kms:Decrypt` is not required in the policy for\nthe IAM user/group/role. Replace `AWSACCOUNTID` with the account ID for your table, and replace \nthe KEY-GUID with the identifier for your KMS key (which you can find in the KMS console). Note \nthat the `dynamodb:Scan` permission is not required if you do not use wildcards in your `get`s.\n\n## Security Notes\nAny IAM principal who can get items from the credential store DDB table, and can call KMS.Decrypt,\ncan read stored credentials.\n\nThe target deployment-story for `credsmash` is an EC2 instance running with an IAM role that has \npermissions to read the credential store and use the master key. Since IAM role credentials are \nvended by the instance metadata service, by default, any user on the system can fetch creds and \nuse them to retrieve credentials. That means that by default, the instance boundary is the security\nboundary for this system. If you are worried about unauthorized users on your instance, you should \ntake steps to secure access to the Instance Metadata Service (for example, use iptables to block \nconnections to 169.254.169.254 except for privileged users). Also, because credsmash is written in \npython, if an attacker can dump the memory of the credsmash process, they may be able to recover \ncredentials. This is a known issue, but again, in the target deployment case, the security boundary \nis assumed to be the instance boundary.\n\n## Frequently Asked Questions (FAQ)\n\n### 1. Where is the master key stored?\nThe master key is stored in AWS Key Management Service (KMS), where it is stored in secure \nHSM-backed storage. The Master Key never leaves the KMS service.\n\n### 2. How is credential rotation handled?\nEvery credential in the store has a version number. Whenever you want to a credential to a new \nvalue, you have to do a `put` with a new credential version. For example, if you have `foo` \nversion 1 in the database, then to update `foo`, you can put version 2. You can either specify \nthe version manually (i.e. `echo 'bar' | credsmash put foo - -v 2`), or you can omit the `-v` flag, \nwhich will attempt to autoincrement the version number (for example, `echo 'baz' | credsmash put foo -`). \nWhenever you do a `get` operation, credsmash will fetch the most recent (highest version) version of that \ncredential. So, to do credential rotation, simply put a new version of the credential, and clients fetching \nthe credential will get the new version.\n\n### 3. How much do the AWS services needed to run credsmash cost?\ntl;dr: If you are using less than 25 reads/sec and 25 writes per second on DDB today, \nit will cost ~$1/month to use credsmash.\n\nThe master key in KMS costs $1 per month.\n\nThe credential store DDB table uses 1 provisioned read and 1 provisioned write throughput, along \nwith a small amount of actual storage. This falls well below the free tier for DDB (25 reads and \n25 writes per second). If you are already a heavy DDB user and exceed the free tier, the credential \nstore table will cost about $0.53 per month (mostly from the write throughput).\n\nIf you are using credsmash heavily and need to increase the provisioned reads/writes, you may incur \nadditional charges. You can estimate your bill using the AWS Simple Monthly Calculator \n(http://calculator.s3.amazonaws.com/index.html#s=DYNAMODB).\n\n### 4. Why DynamoDB for the credential store? Why not S3?\nDDB fits the application really well. Having very low latency fetches are really nice if credsmash is \nin the critical path of spinning up an application. Being able to turn throughput up or down based on\nload and requirements are also great things to have in a config management tool. Also, as credsmash gets \ninto more complex credential management functions, the query capabilities of DDB get super handy.\n\nThat said, S3 support may happen someday.\n\n### 5. Where can I learn more about use cases and context for something like credsmash?\nCheck out this blog post: http://blog.fugue.it/2015-04-21-aws-kms-secrets.html", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/3stack-software/credsmash", "keywords": "", "license": "Apache2", "maintainer": "Nathan Muir", "maintainer_email": "ndmuir@gmail.com", "name": "credsmash", "package_url": "https://pypi.org/project/credsmash/", "platform": "", "project_url": "https://pypi.org/project/credsmash/", "project_urls": { "Homepage": "https://github.com/3stack-software/credsmash" }, "release_url": "https://pypi.org/project/credsmash/2.3.1/", "requires_dist": null, "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*", "summary": "A utility for managing secrets in the cloud using AWS KMS and DynamoDB", "version": "2.3.1" }, "last_serial": 4933229, "releases": { "2.0.0": [ { "comment_text": "", "digests": { "md5": "c3f29f42b9b3baca4f0223f5989c6900", "sha256": "e439680bdb60e855e6029932d1d962ca1f0260cbdb5a56f530d479c735d2c5ef" }, "downloads": -1, "filename": "credsmash-2.0.0.tar.gz", "has_sig": false, "md5_digest": "c3f29f42b9b3baca4f0223f5989c6900", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10614, "upload_time": "2016-09-29T08:41:10", "url": "https://files.pythonhosted.org/packages/4a/f5/4a78683f8707234430d907a42f483aefac041a5aea32fc3ca0dfadfc4b18/credsmash-2.0.0.tar.gz" } ], "2.1.0": [ { "comment_text": "", "digests": { "md5": "295d4c8346318741f4699a3fbcb1a4a1", "sha256": "6167471a9592f37b847518161e069986f5e327a9a6c8f084967c45487ac49d50" }, "downloads": -1, "filename": "credsmash-2.1.0.tar.gz", "has_sig": false, "md5_digest": "295d4c8346318741f4699a3fbcb1a4a1", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12154, "upload_time": "2016-10-03T12:04:46", "url": "https://files.pythonhosted.org/packages/d5/92/f814411ea26234e92477c2b8316c58591e272138eb7c0e28c604ec64d5e4/credsmash-2.1.0.tar.gz" } ], "2.2.0": [ { "comment_text": "", "digests": { "md5": "6c506501f068656cd275a158cfdf97b8", "sha256": "fed391b5681b432efe70089f30c1fcc02a45e633d86ca8172bbccb0d3012e27e" }, "downloads": -1, "filename": "credsmash-2.2.0.tar.gz", "has_sig": false, "md5_digest": "6c506501f068656cd275a158cfdf97b8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12483, "upload_time": "2016-10-13T05:08:24", "url": "https://files.pythonhosted.org/packages/1c/49/56e3c54b81ac01615e9822432e7d82774ed60e6054d2bbf910c81335efe2/credsmash-2.2.0.tar.gz" } ], "2.2.1": [ { "comment_text": "", "digests": { "md5": "c72de251487ea55b483f057d29b36914", "sha256": "7e642ce281799e8de97a016916ff3f008f106c242a8baf34a5ec87ac8c8da06c" }, "downloads": -1, "filename": "credsmash-2.2.1.tar.gz", "has_sig": false, "md5_digest": "c72de251487ea55b483f057d29b36914", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12475, "upload_time": "2017-02-21T04:01:27", "url": "https://files.pythonhosted.org/packages/c0/ba/85dd6fe4c98cf2e20a948f5aedb05907b7bf860d926d9c856452b6b76900/credsmash-2.2.1.tar.gz" } ], "2.2.2": [ { "comment_text": "", "digests": { "md5": "dfc776c3e803d6e8b21c1b1ebbded5f3", "sha256": "ec1d61875880ea9012deaf81c1e9552910a7602040db595b55acf2153b838c1e" }, "downloads": -1, "filename": "credsmash-2.2.2.tar.gz", "has_sig": false, "md5_digest": "dfc776c3e803d6e8b21c1b1ebbded5f3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12478, "upload_time": "2017-02-21T04:57:11", "url": "https://files.pythonhosted.org/packages/4c/1c/e6663ecbaaef8993a4c29f1d3586b085c709b6c610eb80b89d86a73136d3/credsmash-2.2.2.tar.gz" } ], "2.2.3": [ { "comment_text": "", "digests": { "md5": "b9d7a44449c4574692066ccd1179ab9e", "sha256": "c7baccf29bbea09e7534695911e7c4722ec5d916dd4b4f6f9d287e373bc22656" }, "downloads": -1, "filename": "credsmash-2.2.3.tar.gz", "has_sig": false, "md5_digest": "b9d7a44449c4574692066ccd1179ab9e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12467, "upload_time": "2017-07-18T00:24:37", "url": "https://files.pythonhosted.org/packages/44/ac/064b6a2a70a00d95bd06eb38d49a21e3eb43e7d7d3fe40018b1285b44a94/credsmash-2.2.3.tar.gz" } ], "2.2.4": [ { "comment_text": "", "digests": { "md5": "55eea59717a7ce42cfd1c49b323b8bb8", "sha256": "49d9453abb302cad7c9906b427c5f563a40ef3484660eaba9c25f63ce903e496" }, "downloads": -1, "filename": "credsmash-2.2.4.tar.gz", "has_sig": false, "md5_digest": "55eea59717a7ce42cfd1c49b323b8bb8", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12402, "upload_time": "2017-10-11T23:22:10", "url": "https://files.pythonhosted.org/packages/cc/24/c941716a4571e61aa229b07239dfd950da049f9fa46ab50b8efea34ecb7a/credsmash-2.2.4.tar.gz" } ], "2.2.5": [ { "comment_text": "", "digests": { "md5": "3ced21248924c50311c80e21d83764ce", "sha256": "69709cb570299586fcf7d9c36c638ad2dcf874ed27d8366896eeff1c9d445f96" }, "downloads": -1, "filename": "credsmash-2.2.5.tar.gz", "has_sig": false, "md5_digest": "3ced21248924c50311c80e21d83764ce", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20532, "upload_time": "2018-08-22T07:37:03", "url": "https://files.pythonhosted.org/packages/fe/ec/20513c72c274af989b3e9fab09d1f4241406b3b9fc862401a8baf3df1b19/credsmash-2.2.5.tar.gz" } ], "2.3.0": [ { "comment_text": "", "digests": { "md5": "dc9072e18bb2350b2de8cb58dfa44abd", "sha256": "ff1aa7102e8daa99203d059aca058ab047811499d7531c564db2462875249190" }, "downloads": -1, "filename": "credsmash-2.3.0.tar.gz", "has_sig": false, "md5_digest": "dc9072e18bb2350b2de8cb58dfa44abd", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*", "size": 24943, "upload_time": "2019-03-13T05:44:53", "url": "https://files.pythonhosted.org/packages/74/58/5d7a618248a8956f355909f80b99b5c30063a7e6960b95a039c4b4512a9e/credsmash-2.3.0.tar.gz" } ], "2.3.1": [ { "comment_text": "", "digests": { "md5": "254ea11922c39915e85c27b50eee203c", "sha256": "668341af36742c8bd019255403f27afd5d17bff5c3b915a7dce087ae628be870" }, "downloads": -1, "filename": "credsmash-2.3.1.tar.gz", "has_sig": false, "md5_digest": "254ea11922c39915e85c27b50eee203c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*", "size": 24962, "upload_time": "2019-03-13T06:04:35", "url": "https://files.pythonhosted.org/packages/6f/53/e885f80cb615d21f2254b7d837a88f7e3f971a1b60ea538e5ea172f52022/credsmash-2.3.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "254ea11922c39915e85c27b50eee203c", "sha256": "668341af36742c8bd019255403f27afd5d17bff5c3b915a7dce087ae628be870" }, "downloads": -1, "filename": "credsmash-2.3.1.tar.gz", "has_sig": false, "md5_digest": "254ea11922c39915e85c27b50eee203c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*", "size": 24962, "upload_time": "2019-03-13T06:04:35", "url": "https://files.pythonhosted.org/packages/6f/53/e885f80cb615d21f2254b7d837a88f7e3f971a1b60ea538e5ea172f52022/credsmash-2.3.1.tar.gz" } ] }