# murmuration
encryption primitives for use with aws kms
## aes + galois counter mode encryption
```python
from murmuration import gcm
key = 'this is my secret encryption key'
plaintext = 'the quick brown fox jumps over the lazy dog'
ciphertext = gcm.encrypt(plaintext, key, 'header')
decrypted = gcm.decrypt(ciphertext, key)
assert decrypted == plaintext
```
## encryption using kms (for use with aws)
You can also use kms as an encryption / decryption service. This does
incur kms costs and require kms setup. The `region` and `profile` parameters
do not have to be specified. If they are not specified, the values will
be inferred [in the order specified by boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials):
> 1. Passing credentials as parameters in the `boto.client()` method
> 2. Passing credentials as parameters when creating a `Session` object
> 3. Environment variables
> 4. Shared credential file (`~/.aws/credentials`)
> 5. AWS config file (`~/.aws/config`)
> 6. Assume Role provider
> 7. Boto2 config file (`/etc/boto.cfg` and `~/.boto`)
> 8. Instance metadata service on an Amazon EC2 instance
> that has an IAM role configured.
```python
from murmuration import kms
plaintext = 'the quick brown fox jumps over the lazy dog'
key_alias = 'my kms key alias'
ciphertext = kms.encrypt(plaintext, key_alias, region='us-west-1', profile='company')
decrypted = kms.decrypt(ciphertext, region='us-west-1', profile='company')
assert decrypted == plaintext
```
## wrapped encryption using kms (for use with aws)
You can also use wrapped kms data keys for encryption to protect the underlying
kms key. Using this does functionality will incur kms costs and require kms
setup. The `region` and `profile` parameters do not have to be specified.
If they are not specified, the values will
be inferred [in the order specified by boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials):
> 1. Passing credentials as parameters in the `boto.client()` method
> 2. Passing credentials as parameters when creating a `Session` object
> 3. Environment variables
> 4. Shared credential file (`~/.aws/credentials`)
> 5. AWS config file (`~/.aws/config`)
> 6. Assume Role provider
> 7. Boto2 config file (`/etc/boto.cfg` and `~/.boto`)
> 8. Instance metadata service on an Amazon EC2 instance
> that has an IAM role configured.
```python
from murmuration import kms_wrapped
plaintext = 'the quick brown fox jumps over the lazy dog'
key_alias = 'my kms key alias'
ciphertext = kms_wrapped.encrypt(plaintext, key_alias, region='us-west-1', profile='company')
decrypted = kms_wrapped.decrypt(ciphertext, region='us-west-1', profile='company')
assert decrypted == plaintext
```
# contributing quick start
```bash
cd /path/to
git clone https://github.com/angry-penguins/murmuration
cd murmuration
make setup
```
to run tests, you will need to create a config file called `conf/test.yml`
```yaml
aws:
profile: an_existing_aws_profile
```
this profile will need to have a kms key that has been aliased to `dev`.
Once you have created that file, you can run tests using `make`:
```bash
make test
```
Raw data
{
"_id": null,
"home_page": "https://github.com/angry-penguins/murmuration",
"name": "murmuration",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "aws python encryption cryptography kms",
"author": "Preetam Shingavi",
"author_email": "p.shingavi@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/b7/49/431dfd5cc51b5aa18c317e2f9bad35b8540a191e9f539bc2817a092dea18/murmuration-1.4.tar.gz",
"platform": null,
"description": "# murmuration \n\nencryption primitives for use with aws kms\n\n## aes + galois counter mode encryption\n\n```python\nfrom murmuration import gcm\nkey = 'this is my secret encryption key'\nplaintext = 'the quick brown fox jumps over the lazy dog'\nciphertext = gcm.encrypt(plaintext, key, 'header')\ndecrypted = gcm.decrypt(ciphertext, key)\nassert decrypted == plaintext\n```\n\n## encryption using kms (for use with aws)\n\nYou can also use kms as an encryption / decryption service. This does\nincur kms costs and require kms setup. The `region` and `profile` parameters\ndo not have to be specified. If they are not specified, the values will\nbe inferred [in the order specified by boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials):\n\n\n> 1. Passing credentials as parameters in the `boto.client()` method\n> 2. Passing credentials as parameters when creating a `Session` object\n> 3. Environment variables\n> 4. Shared credential file (`~/.aws/credentials`)\n> 5. AWS config file (`~/.aws/config`)\n> 6. Assume Role provider\n> 7. Boto2 config file (`/etc/boto.cfg` and `~/.boto`)\n> 8. Instance metadata service on an Amazon EC2 instance \n> that has an IAM role configured.\n\n```python\nfrom murmuration import kms\nplaintext = 'the quick brown fox jumps over the lazy dog'\nkey_alias = 'my kms key alias'\nciphertext = kms.encrypt(plaintext, key_alias, region='us-west-1', profile='company')\ndecrypted = kms.decrypt(ciphertext, region='us-west-1', profile='company')\nassert decrypted == plaintext\n```\n\n## wrapped encryption using kms (for use with aws)\n\nYou can also use wrapped kms data keys for encryption to protect the underlying\nkms key. Using this does functionality will incur kms costs and require kms \nsetup. The `region` and `profile` parameters do not have to be specified. \nIf they are not specified, the values will\nbe inferred [in the order specified by boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#configuring-credentials):\n\n\n> 1. Passing credentials as parameters in the `boto.client()` method\n> 2. Passing credentials as parameters when creating a `Session` object\n> 3. Environment variables\n> 4. Shared credential file (`~/.aws/credentials`)\n> 5. AWS config file (`~/.aws/config`)\n> 6. Assume Role provider\n> 7. Boto2 config file (`/etc/boto.cfg` and `~/.boto`)\n> 8. Instance metadata service on an Amazon EC2 instance \n> that has an IAM role configured.\n\n```python\nfrom murmuration import kms_wrapped\nplaintext = 'the quick brown fox jumps over the lazy dog'\nkey_alias = 'my kms key alias'\nciphertext = kms_wrapped.encrypt(plaintext, key_alias, region='us-west-1', profile='company')\ndecrypted = kms_wrapped.decrypt(ciphertext, region='us-west-1', profile='company')\nassert decrypted == plaintext\n```\n\n# contributing quick start\n\n```bash\ncd /path/to\ngit clone https://github.com/angry-penguins/murmuration\ncd murmuration\nmake setup\n```\n\nto run tests, you will need to create a config file called `conf/test.yml`\n\n```yaml\naws:\n profile: an_existing_aws_profile\n```\n\nthis profile will need to have a kms key that has been aliased to `dev`. \n\nOnce you have created that file, you can run tests using `make`:\n\n```bash\nmake test\n```\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "encryption primitives for use with aws",
"version": "1.4",
"project_urls": {
"Homepage": "https://github.com/angry-penguins/murmuration"
},
"split_keywords": [
"aws",
"python",
"encryption",
"cryptography",
"kms"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b749431dfd5cc51b5aa18c317e2f9bad35b8540a191e9f539bc2817a092dea18",
"md5": "f64bc77e46a6ea9de66b6c19d80154bb",
"sha256": "d455c12a453d51f735a94b2414ae528c98c3d6514432870c4ab3f262c4091327"
},
"downloads": -1,
"filename": "murmuration-1.4.tar.gz",
"has_sig": false,
"md5_digest": "f64bc77e46a6ea9de66b6c19d80154bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7426,
"upload_time": "2024-01-10T05:03:56",
"upload_time_iso_8601": "2024-01-10T05:03:56.416849Z",
"url": "https://files.pythonhosted.org/packages/b7/49/431dfd5cc51b5aa18c317e2f9bad35b8540a191e9f539bc2817a092dea18/murmuration-1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-10 05:03:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "angry-penguins",
"github_project": "murmuration",
"github_not_found": true,
"lcname": "murmuration"
}
JSON
