# redstone - A Pythonic IBM Cloud SDK
[](https://pypi.org/project/redstone)
[](https://pepy.tech/project/redstone)
[](https://opensource.org/licenses/Apache-2.0)
[](https://travis-ci.com/IBM/redstone)
[](https://redstone-py.readthedocs.io/en/latest/?badge=latest)
Redstone is a Python library for interacting with IBM Cloud services.
It currently includes support for IBM KeyProtect, IBM Kubernetes Service (IKS), and some
platform services like ResourceController and IAM.
Contributions in the form of feedback, patches, or bugs are appreciated.
* [Installation](#installation)
* [Usage](#usage)
* [rs-crypto](#encrypting-data-using-redstonecrypto-with-keyprotect)
* [rs-keyprotect](#using-the-rs-keyprotect-cli)
# Installation
You can install `redstone` with:
```sh
$ pip3 install redstone
# alternatively, you can do a user install if you are not an admin on your box
$ pip3 install --user redstone
```
# Usage
A default session is created for you on first access, which can be used to access service interfaces scoped to that account.
Default sessions will read an API key from the conventional `IBMCLOUD_API_KEY` environment variable.
Using the default session to get a CIS (Cloud Internet Services) client:
```python
>>> import redstone
>>> import os
>>> cis = redstone.service("CIS", service_instance_id=os.environ.get("CIS_CRN"))
>>> cis
<redstone.client.CIS object at 0x...>
>>> sorted(map(lambda x: x.get("name"), cis.pools()))
['au-syd', 'eu-de', 'eu-de-ams', 'eu-de-fra', 'eu-de-private', 'eu-gb', 'eu-gb-private', 'eu-syd-private', 'jp-tok', 'jp-tok-02', 'jp-tok-04', 'preprod', 'private-jp-tok', 'private-us-south', 'us-east', 'us-east-private', 'us-south']
>>>
```
Build your own session for interacting with multiple regions and/or accounts within the same Python context:
```python
>>> production = redstone.Session(
... region="us-south",
... iam_api_key=os.environ.get("IBMCLOUD_API_KEY")
... )
>>> production
<redstone.Session object at 0x...>
>>> rc = production.service("ResourceController")
>>> rc
<redstone.client.ResourceController object at 0x...>
>>> instance_id, instance_crn = rc.create_instance(name="mykpinstance")
>>> instance_crn
'crn:v1:bluemix:public:kms:us-south:a/...::'
>>> kp = production.service("KeyProtect", service_instance_id=instance_id)
>>> key = kp.create(name="mykey")
>>> key.get("name")
'mykey'
>>> kp.delete(key.get("id"))
>>> rc.delete_instance(instance_crn)
>>>
```
# Encrypting data using redstone.crypto with KeyProtect
Redstone includes support for directly encrypting and decrypting files or other data using IBM KeyProtect as a key provider.
There are two ways to use the crypto functionality, a CLI tool and the python module.
## rs-crypto CLI tool
Upon installing the redstone module with pip, it will also install a command-line script under `rs-crypto` that can
be used to encrypt and decrypt.
The script will read the API key used to interact with KeyProtect from the `IBMCLOUD_API_KEY` environment variable.
Encrypting a file is straight forward with the `encrypt` commmand. The encrypted data will be printed to stdout, and
can be redirected to a file.
```sh
IBMCLOUD_API_KEY=... rs-crypto encrypt --key-crns "crn:v1... crn:v1..." my-super-secret-file.txt > my-encrypted-file
```
Decrypting is similar. Note that the tool will print raw bytes to stdout, so you will probably want
to redirect to a file if the original data was binary.
```sh
IBMCLOUD_API_KEY=... rs-crypto decrypt my-encrypted-file > my-decrypted-file
```
The output of encrypt can be fed directly back to decrypt.
```sh
# you can also pipe directly to stdin by specifying the file as '-'
echo "some-secret-data" | rs-crypto encrypt --key-crns "crn:v1... crn:v1..." - | rs-crypto decrypt -
```
## using redstone.crypto
The python module is designed to be easy to use, even for those not familiar with python.
```python
import os
import sys
from redstone import crypto
# NOTE: here we demonstrate how we can use several keys that come from different instances and even different regions
# only one of the keys needs to be available for the decrypt operation to succeed
crns = [
"crn:v1:bluemix:public:kms:us-south:a/...:415ba6f3-43f9-4996-0000-123456789:key:94e2639b-af2f-4f4f-a415-bb63820cf976",
"crn:v1:bluemix:public:kms:us-east:a/...:077a4670-c2f2-415c-0000-123456789:key:1f5ead7e-a1f4-4d15-9641-80e9aa5c7e12",
]
if not os.getenv("IBMCLOUD_API_KEY"):
print("Remember to set 'IBMCLOUD_API_KEY' as the internal client uses that for authentication", file=sys.stderr)
sys.exit(1)
# read bytes from stdin and encrypt
message, meta = crypto.encrypt(sys.stdin.buffer.read(), key_crns=crns)
print("Encrypted value: %r" % message)
message, meta = crypto.decrypt(message)
print("%r" % message)
print("%r" % meta)
```
## Finding Key CRNs
KeyProtect CRKs to be used for encryption are specified via `--key-crns` as a space separated list, or the `RSCRYPTO_KEY_CRNS` environment variable.
Key CRNs can be found via the IBM Cloud Console (KeyProtect UI) or the IBM Cloud CLI. (You will need the kp plugin.)
```sh
# Using the ic kp plugin to find a CRN
ic kp get -o json -i $instance_uuid $key_uuid
{
"id": "94e2639b-af2f-4f4f-a415-bb63820cf976",
"name": "the-one-key",
"type": "application/vnd.ibm.kms.key+json",
"extractable": false,
"state": 1,
"crn": "crn:v1:bluemix:public:kms:us-south:a/....:415ba6f3-43f9-4996-abcd-1234346:key:94e2639b-af2f-4f4f-a415-bb63820cf976"
}
```
# Using the rs-keyprotect CLI
rs-keyprotect is a quick stand-alone CLI utility for interacting with KeyProtect via terminal or shell scripts.
```sh
# set an API for the account you wish to interact with
export IBMCLOUD_API_KEY=...
# list KeyProtect instances in the account
rs-keyprotect list-instances
ID NAME REGION
07096bd5-6e6f-4b75-9978-9cbb18ce9a16 keyptest1 us-south
143ac075-31ad-4bcc-bc9f-c352ea6bd213 Key Protect-y6 us-south
# list the keys of an instance
rs-keyprotect -i fb680ac4-e2d7-40c3-8b64-be59b13236cd list
ID NAME EXTRACTABLE
52c3eea1-6db7-4dd8-8540-5d95af8c621b kpregress_at_pass_key False
e5931fa2-5830-4f12-9cfa-3d0099f79929 kpregress_at_pass_key False
```
For more usage, run `rs-keyprotect -h` and `rs-keyprotect <command> -h`
Raw data
{
"_id": null,
"home_page": "https://github.com/IBM/redstone",
"name": "redstone",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Mathew Odden",
"author_email": "mathewrodden@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1b/26/e1d2d9b3a0cdd8e27792ace2be7b884e3d7f06c7f87ed94a95aba3b11562/redstone-0.6.1.tar.gz",
"platform": null,
"description": "# redstone - A Pythonic IBM Cloud SDK\n\n[](https://pypi.org/project/redstone)\n[](https://pepy.tech/project/redstone)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://travis-ci.com/IBM/redstone)\n[](https://redstone-py.readthedocs.io/en/latest/?badge=latest)\n\nRedstone is a Python library for interacting with IBM Cloud services.\n\nIt currently includes support for IBM KeyProtect, IBM Kubernetes Service (IKS), and some\nplatform services like ResourceController and IAM.\n\nContributions in the form of feedback, patches, or bugs are appreciated. \n\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [rs-crypto](#encrypting-data-using-redstonecrypto-with-keyprotect)\n* [rs-keyprotect](#using-the-rs-keyprotect-cli)\n\n\n# Installation\n\nYou can install `redstone` with:\n\n```sh\n$ pip3 install redstone\n\n# alternatively, you can do a user install if you are not an admin on your box\n$ pip3 install --user redstone\n```\n\n# Usage\n\nA default session is created for you on first access, which can be used to access service interfaces scoped to that account.\nDefault sessions will read an API key from the conventional `IBMCLOUD_API_KEY` environment variable.\n\nUsing the default session to get a CIS (Cloud Internet Services) client:\n\n```python\n>>> import redstone\n>>> import os\n>>> cis = redstone.service(\"CIS\", service_instance_id=os.environ.get(\"CIS_CRN\"))\n>>> cis\n<redstone.client.CIS object at 0x...>\n>>> sorted(map(lambda x: x.get(\"name\"), cis.pools()))\n['au-syd', 'eu-de', 'eu-de-ams', 'eu-de-fra', 'eu-de-private', 'eu-gb', 'eu-gb-private', 'eu-syd-private', 'jp-tok', 'jp-tok-02', 'jp-tok-04', 'preprod', 'private-jp-tok', 'private-us-south', 'us-east', 'us-east-private', 'us-south']\n>>>\n```\n\nBuild your own session for interacting with multiple regions and/or accounts within the same Python context:\n\n```python\n>>> production = redstone.Session(\n... region=\"us-south\",\n... iam_api_key=os.environ.get(\"IBMCLOUD_API_KEY\")\n... )\n>>> production\n<redstone.Session object at 0x...>\n>>> rc = production.service(\"ResourceController\")\n>>> rc\n<redstone.client.ResourceController object at 0x...>\n>>> instance_id, instance_crn = rc.create_instance(name=\"mykpinstance\")\n>>> instance_crn\n'crn:v1:bluemix:public:kms:us-south:a/...::'\n>>> kp = production.service(\"KeyProtect\", service_instance_id=instance_id)\n>>> key = kp.create(name=\"mykey\")\n>>> key.get(\"name\")\n'mykey'\n>>> kp.delete(key.get(\"id\"))\n>>> rc.delete_instance(instance_crn)\n>>>\n```\n\n# Encrypting data using redstone.crypto with KeyProtect\n\nRedstone includes support for directly encrypting and decrypting files or other data using IBM KeyProtect as a key provider.\nThere are two ways to use the crypto functionality, a CLI tool and the python module.\n\n## rs-crypto CLI tool\n\nUpon installing the redstone module with pip, it will also install a command-line script under `rs-crypto` that can\nbe used to encrypt and decrypt.\n\nThe script will read the API key used to interact with KeyProtect from the `IBMCLOUD_API_KEY` environment variable.\n\nEncrypting a file is straight forward with the `encrypt` commmand. The encrypted data will be printed to stdout, and\ncan be redirected to a file.\n\n```sh\nIBMCLOUD_API_KEY=... rs-crypto encrypt --key-crns \"crn:v1... crn:v1...\" my-super-secret-file.txt > my-encrypted-file\n```\n\nDecrypting is similar. Note that the tool will print raw bytes to stdout, so you will probably want\nto redirect to a file if the original data was binary.\n\n```sh\nIBMCLOUD_API_KEY=... rs-crypto decrypt my-encrypted-file > my-decrypted-file\n```\n\nThe output of encrypt can be fed directly back to decrypt.\n\n```sh\n# you can also pipe directly to stdin by specifying the file as '-'\necho \"some-secret-data\" | rs-crypto encrypt --key-crns \"crn:v1... crn:v1...\" - | rs-crypto decrypt -\n```\n\n\n## using redstone.crypto\n\nThe python module is designed to be easy to use, even for those not familiar with python.\n\n```python\nimport os\nimport sys\n\nfrom redstone import crypto\n\n# NOTE: here we demonstrate how we can use several keys that come from different instances and even different regions\n# only one of the keys needs to be available for the decrypt operation to succeed\ncrns = [\n \"crn:v1:bluemix:public:kms:us-south:a/...:415ba6f3-43f9-4996-0000-123456789:key:94e2639b-af2f-4f4f-a415-bb63820cf976\",\n \"crn:v1:bluemix:public:kms:us-east:a/...:077a4670-c2f2-415c-0000-123456789:key:1f5ead7e-a1f4-4d15-9641-80e9aa5c7e12\",\n]\n\nif not os.getenv(\"IBMCLOUD_API_KEY\"):\n print(\"Remember to set 'IBMCLOUD_API_KEY' as the internal client uses that for authentication\", file=sys.stderr)\n sys.exit(1)\n\n# read bytes from stdin and encrypt\nmessage, meta = crypto.encrypt(sys.stdin.buffer.read(), key_crns=crns)\nprint(\"Encrypted value: %r\" % message)\n\nmessage, meta = crypto.decrypt(message)\n\nprint(\"%r\" % message)\nprint(\"%r\" % meta)\n```\n\n\n## Finding Key CRNs\n\nKeyProtect CRKs to be used for encryption are specified via `--key-crns` as a space separated list, or the `RSCRYPTO_KEY_CRNS` environment variable.\nKey CRNs can be found via the IBM Cloud Console (KeyProtect UI) or the IBM Cloud CLI. (You will need the kp plugin.)\n\n```sh\n# Using the ic kp plugin to find a CRN\nic kp get -o json -i $instance_uuid $key_uuid\n{\n \"id\": \"94e2639b-af2f-4f4f-a415-bb63820cf976\",\n \"name\": \"the-one-key\",\n \"type\": \"application/vnd.ibm.kms.key+json\",\n \"extractable\": false,\n \"state\": 1,\n \"crn\": \"crn:v1:bluemix:public:kms:us-south:a/....:415ba6f3-43f9-4996-abcd-1234346:key:94e2639b-af2f-4f4f-a415-bb63820cf976\"\n}\n```\n\n# Using the rs-keyprotect CLI\n\nrs-keyprotect is a quick stand-alone CLI utility for interacting with KeyProtect via terminal or shell scripts.\n\n```sh\n# set an API for the account you wish to interact with\nexport IBMCLOUD_API_KEY=...\n\n# list KeyProtect instances in the account\nrs-keyprotect list-instances\nID NAME REGION\n07096bd5-6e6f-4b75-9978-9cbb18ce9a16 keyptest1 us-south\n143ac075-31ad-4bcc-bc9f-c352ea6bd213 Key Protect-y6 us-south\n\n# list the keys of an instance\nrs-keyprotect -i fb680ac4-e2d7-40c3-8b64-be59b13236cd list\nID NAME EXTRACTABLE\n52c3eea1-6db7-4dd8-8540-5d95af8c621b kpregress_at_pass_key False \ne5931fa2-5830-4f12-9cfa-3d0099f79929 kpregress_at_pass_key False \n```\n\nFor more usage, run `rs-keyprotect -h` and `rs-keyprotect <command> -h`\n",
"bugtrack_url": null,
"license": null,
"summary": "A Pythonic IBM Cloud SDK",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/IBM/redstone"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b50e751a18416f6f5ba8e551c14800c02b598464bf0e77e79850bca2ff123df4",
"md5": "2ef95df0be450b41592bc70e79c493fc",
"sha256": "6bcaf4fcc314f755eb799fb1fdf08138c970b6778bf479f92ac6866d42bc12c8"
},
"downloads": -1,
"filename": "redstone-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ef95df0be450b41592bc70e79c493fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 35588,
"upload_time": "2025-01-08T21:38:13",
"upload_time_iso_8601": "2025-01-08T21:38:13.558074Z",
"url": "https://files.pythonhosted.org/packages/b5/0e/751a18416f6f5ba8e551c14800c02b598464bf0e77e79850bca2ff123df4/redstone-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b26e1d2d9b3a0cdd8e27792ace2be7b884e3d7f06c7f87ed94a95aba3b11562",
"md5": "45760baba4c9330c869a0a77f13dced8",
"sha256": "4e09cd33c9787b78fb73173592ca237c56bbb105f9077a314f341d51c4a14603"
},
"downloads": -1,
"filename": "redstone-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "45760baba4c9330c869a0a77f13dced8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 32398,
"upload_time": "2025-01-08T21:38:16",
"upload_time_iso_8601": "2025-01-08T21:38:16.025209Z",
"url": "https://files.pythonhosted.org/packages/1b/26/e1d2d9b3a0cdd8e27792ace2be7b884e3d7f06c7f87ed94a95aba3b11562/redstone-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 21:38:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM",
"github_project": "redstone",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.19"
]
]
},
{
"name": "requests",
"specs": []
},
{
"name": "cryptography",
"specs": []
}
],
"tox": true,
"lcname": "redstone"
}
JSON
