path: root/python-redstone.spec

%global _empty_manifest_terminate_build 0
Name:		python-redstone
Version:	0.5.1
Release:	1
Summary:	A Pythonic IBM Cloud SDK
License:	Apache Software License
URL:		https://github.com/IBM/redstone
Source0:	https://mirrors.aliyun.com/pypi/web/packages/15/9b/dee7af125dcf12ec9e744e93e3928555d3a17fd32c88bd58bc0f1dd50179/redstone-0.5.1.tar.gz
BuildArch:	noarch

Requires:	python3-requests[security]
Requires:	python3-cryptography
Requires:	python3-sphinx
Requires:	python3-sphinx-rtd-theme

%description
# redstone - A Pythonic IBM Cloud SDK

[![PyPi](https://img.shields.io/pypi/v/redstone.svg)](https://pypi.org/project/redstone)
[![Downloads](https://static.pepy.tech/personalized-badge/redstone?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads)](https://pepy.tech/project/redstone)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://travis-ci.com/IBM/redstone.svg?branch=master)](https://travis-ci.com/IBM/redstone)
[![Documentation Status](https://readthedocs.org/projects/redstone-py/badge/?version=latest)](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`




%package -n python3-redstone
Summary:	A Pythonic IBM Cloud SDK
Provides:	python-redstone
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-redstone
# redstone - A Pythonic IBM Cloud SDK

[![PyPi](https://img.shields.io/pypi/v/redstone.svg)](https://pypi.org/project/redstone)
[![Downloads](https://static.pepy.tech/personalized-badge/redstone?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads)](https://pepy.tech/project/redstone)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://travis-ci.com/IBM/redstone.svg?branch=master)](https://travis-ci.com/IBM/redstone)
[![Documentation Status](https://readthedocs.org/projects/redstone-py/badge/?version=latest)](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`




%package help
Summary:	Development documents and examples for redstone
Provides:	python3-redstone-doc
%description help
# redstone - A Pythonic IBM Cloud SDK

[![PyPi](https://img.shields.io/pypi/v/redstone.svg)](https://pypi.org/project/redstone)
[![Downloads](https://static.pepy.tech/personalized-badge/redstone?period=total&units=international_system&left_color=grey&right_color=orange&left_text=Downloads)](https://pepy.tech/project/redstone)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://travis-ci.com/IBM/redstone.svg?branch=master)](https://travis-ci.com/IBM/redstone)
[![Documentation Status](https://readthedocs.org/projects/redstone-py/badge/?version=latest)](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`




%prep
%autosetup -n redstone-0.5.1

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-redstone -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Thu Jun 08 2023 Python_Bot <Python_Bot@openeuler.org> - 0.5.1-1
- Package Spec generated