# Yandex Lockbox Client
[](https://pypi.org/project/yc-lockbox/)
[](https://pypi.org/project/yc-lockbox/)
[](https://app.codecov.io/gh/akimrx/python-yc-lockbox)
[](https://github.com/akimrx/python-yc-lockbox)
This library is a simple client for working with **[Yandex Lockbox](https://cloud.yandex.ru/en/docs/lockbox/)** over [REST API](https://cloud.yandex.ru/en/docs/lockbox/api-ref/), simplifying work with secrets and allowing you to work with them in the OOP paradigm.
Supports two modes: synchronous and asynchronous.
**[Full library documentation link](https://akimrx.github.io/python-yc-lockbox/)**
**Supported Python versions**:
* 3.10
* 3.11
* 3.12
**Dependencies:**
* [Pydantic V2](https://github.com/pydantic/pydantic)
* [Crypthography](https://github.com/pyca/cryptography)
* [PyJWT](https://github.com/jpadilla/pyjwt)
* [Requests](https://github.com/psf/requests)
**Extra dependencies:**
* [aiohttp](https://github.com/aio-libs/aiohttp)
**Currently, the following operations are not supported by the library:**
* List secret access bindings
* Set secret access bindings
* Update secret access bindings
* List secret operations
**In the near future release:**
- [x] Tests
- [x] Async client implementation
- [ ] Implement access bindings methods and view operations
- [ ] Ansible action and lookup plugins
## Install
Installing via [pip](https://pypi.org/project/yc-lockbox/):
```
pip install yc-lockbox
```
Also, you can install from source with:
```
git clone https://github.com/akimrx/python-yc-lockbox
cd python-yc-lockbox
make install
```
For async mode support use
```
pip install yc-lockbox[aio]
```
## Usage
* **Authenticate via your [OAuth token](https://oauth.yandex.com/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb)**
```python
from yc_lockbox import YandexLockboxClient
lockbox = YandexLockboxClient("y0_xxxxxxxxxxxx")
```
* **Authenticate via [IAM token](https://cloud.yandex.com/en/docs/iam/operations/iam-token/create)**
> If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.
```python
from yc_lockbox import YandexLockboxClient
lockbox = YandexLockboxClient("t1.xxxxxx.xxxxxxx")
```
* **Authenticate using [service account key](https://cloud.yandex.com/en/docs/iam/operations/authorized-key/create#cli_1)**
```python
import json
from yc_lockbox import YandexLockboxClient
with open("/path/to/key.json", "r") as keyfile:
credentials = keyfile.read()
lockbox = YandexLockboxClient(credentials)
```
### Create a new secret
```python
from yc_lockbox import YandexLockboxClient, INewSecret, INewSecretPayloadEntry
lockbox = YandexLockboxClient("oauth_or_iam_token")
create_secret_operation = lockbox.create_secret(
INewSecret(
folder_id="b1xxxxxxxxxxxxxx",
name="my-secret",
version_payload_entries=[
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value".encode()),
],
)
)
if create_secret_operation.done:
new_secret = create_secret_operation.resource
print(new_secret.id)
new_secret.deactivate()
```
### Get secret from Lockbox
```python
from yc_lockbox import YandexLockboxClient, Secret
lockbox = YandexLockboxClient("oauth_or_iam_token")
secret: Secret = lockbox.get_secret("e6qxxxxxxxxxx")
print(secret.status, secret.name)
payload = secret.payload(version_id=secret.current_version.id) # id is optional, by default using current version
print(payload.entries) # list of SecretPayloadEntry objects
# Direct access
entry = payload["secret_entry_1"] # or payload.get("secret_entry_1")
print(entry.text_value) # return MASKED value like ***********
print(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()
```
### Add new version of secret
```python
from yc_lockbox import YandexLockboxClient, Secret, INewSecretVersion, INewSecretPayloadEntry
lockbox = YandexLockboxClient("oauth_or_iam_token")
secret: Secret = lockbox.get_secret("e6qxxxxxxxxxxxx")
secret.add_version(
INewSecretVersion(
description="a new version",
base_version_id=secret.current_version.id,
payload_entries= [
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value"),
]
)
)
# alternative
lockbox.add_secret_version(
"secret_id",
version=INewSecretVersion(
description="a new version",
base_version_id=secret.current_version.id,
payload_entries=[INewSecretPayloadEntry(...), INewSecretPayloadEntry(...)]
)
)
```
### Other operations with secret
```python
from yc_lockbox import YandexLockboxClient
lockbox = YandexLockboxClient("oauth_or_iam_token")
for secret in lockbox.list_secrets(folder_id="b1xxxxxxxxxx", iterator=True):
print(secret.name, secret.status)
secret.deactivate()
secret.activate()
for version in secret.list_versions(iterator=True): # if iterator=False returns paginated list with ``next_page_token``
if version.id != secret.current_version.id:
version.schedule_version_destruction()
version.cancel_version_destruction()
```
## Async mode
The client supports asynchronous mode using the aiohttp library. The signature of the methods does not differ from the synchronous implementation.
Just import async client:
```python
from yc_lockbox import AsyncYandexLockboxClient
lockbox = AsyncYandexLockboxClient("oauth_or_iam_token")
```
Alternative:
```python
from yc_lockbox import YandexLockboxFacade
lockbox = YandexLockboxFacade("oauth_or_iam_token", enable_async=True).client
```
Example usage:
```python
secret: Secret = await lockbox.get_secret("e6qxxxxxxxxxx")
payload = await secret.payload()
print(payload.entries) # list of SecretPayloadEntry objects
# Direct access
entry = payload["secret_entry_1"] # or payload.get("secret_entry_1")
print(entry.text_value) # return MASKED value like ***********
print(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()
# Async iterators
secret_versions = await secret.list_versions(iterator=True)
async for version in secret_versions:
if version.id != secret.current_version.id:
await version.schedule_version_destruction()
await version.cancel_version_destruction()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/akimrx/python-yc-lockbox",
"name": "yc-lockbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "yandex, cloud, vault, secrets, lockbox",
"author": "Akim Faskhutdinov",
"author_email": "akimstrong@yandex.ru",
"download_url": "https://files.pythonhosted.org/packages/bd/89/86c99496c7359560effe0c9eaaf01410897728027b13e75cb220f3c37dad/yc-lockbox-0.2.0.tar.gz",
"platform": "osx",
"description": "# Yandex Lockbox Client\n\n[](https://pypi.org/project/yc-lockbox/)\n[](https://pypi.org/project/yc-lockbox/)\n[](https://app.codecov.io/gh/akimrx/python-yc-lockbox)\n[](https://github.com/akimrx/python-yc-lockbox)\n\nThis library is a simple client for working with **[Yandex Lockbox](https://cloud.yandex.ru/en/docs/lockbox/)** over [REST API](https://cloud.yandex.ru/en/docs/lockbox/api-ref/), simplifying work with secrets and allowing you to work with them in the OOP paradigm.\n\nSupports two modes: synchronous and asynchronous.\n\n**[Full library documentation link](https://akimrx.github.io/python-yc-lockbox/)**\n\n**Supported Python versions**:\n\n* 3.10\n* 3.11\n* 3.12\n\n**Dependencies:**\n\n* [Pydantic V2](https://github.com/pydantic/pydantic)\n* [Crypthography](https://github.com/pyca/cryptography)\n* [PyJWT](https://github.com/jpadilla/pyjwt)\n* [Requests](https://github.com/psf/requests)\n\n\n**Extra dependencies:**\n\n* [aiohttp](https://github.com/aio-libs/aiohttp)\n\n\n**Currently, the following operations are not supported by the library:**\n\n* List secret access bindings\n* Set secret access bindings\n* Update secret access bindings\n* List secret operations\n\n\n**In the near future release:**\n\n- [x] Tests\n- [x] Async client implementation\n- [ ] Implement access bindings methods and view operations\n- [ ] Ansible action and lookup plugins\n\n\n## Install\n\nInstalling via [pip](https://pypi.org/project/yc-lockbox/):\n\n```\npip install yc-lockbox\n```\n\nAlso, you can install from source with:\n\n```\ngit clone https://github.com/akimrx/python-yc-lockbox\ncd python-yc-lockbox \nmake install\n```\n\nFor async mode support use\n\n```\npip install yc-lockbox[aio]\n```\n\n\n## Usage\n\n\n* **Authenticate via your [OAuth token](https://oauth.yandex.com/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb)**\n\n```python\nfrom yc_lockbox import YandexLockboxClient\n\nlockbox = YandexLockboxClient(\"y0_xxxxxxxxxxxx\")\n```\n\n* **Authenticate via [IAM token](https://cloud.yandex.com/en/docs/iam/operations/iam-token/create)**\n\n> If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.\n\n```python\nfrom yc_lockbox import YandexLockboxClient\n\nlockbox = YandexLockboxClient(\"t1.xxxxxx.xxxxxxx\")\n```\n\n\n\n* **Authenticate using [service account key](https://cloud.yandex.com/en/docs/iam/operations/authorized-key/create#cli_1)**\n\n```python\nimport json\nfrom yc_lockbox import YandexLockboxClient\n\nwith open(\"/path/to/key.json\", \"r\") as keyfile:\n credentials = keyfile.read()\n\nlockbox = YandexLockboxClient(credentials)\n```\n\n### Create a new secret\n\n```python\nfrom yc_lockbox import YandexLockboxClient, INewSecret, INewSecretPayloadEntry\n\nlockbox = YandexLockboxClient(\"oauth_or_iam_token\")\n\ncreate_secret_operation = lockbox.create_secret(\n INewSecret(\n folder_id=\"b1xxxxxxxxxxxxxx\",\n name=\"my-secret\",\n version_payload_entries=[\n INewSecretPayloadEntry(key=\"secret_entry_1\", text_value=\"secret_entry_text_value\"),\n INewSecretPayloadEntry(key=\"secret_entry_2\", binary_value=\"secret_entry_binary_value\".encode()),\n ],\n )\n)\n\nif create_secret_operation.done:\n new_secret = create_secret_operation.resource\n print(new_secret.id)\n new_secret.deactivate()\n```\n\n\n### Get secret from Lockbox\n\n```python\nfrom yc_lockbox import YandexLockboxClient, Secret\n\nlockbox = YandexLockboxClient(\"oauth_or_iam_token\")\n\nsecret: Secret = lockbox.get_secret(\"e6qxxxxxxxxxx\")\nprint(secret.status, secret.name)\n\npayload = secret.payload(version_id=secret.current_version.id) # id is optional, by default using current version\nprint(payload.entries) # list of SecretPayloadEntry objects\n\n# Direct access\n\nentry = payload[\"secret_entry_1\"] # or payload.get(\"secret_entry_1\")\n\nprint(entry.text_value) # return MASKED value like ***********\nprint(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()\n```\n\n\n### Add new version of secret\n\n```python\nfrom yc_lockbox import YandexLockboxClient, Secret, INewSecretVersion, INewSecretPayloadEntry\n\nlockbox = YandexLockboxClient(\"oauth_or_iam_token\")\n\nsecret: Secret = lockbox.get_secret(\"e6qxxxxxxxxxxxx\")\n\nsecret.add_version(\n INewSecretVersion(\n description=\"a new version\",\n base_version_id=secret.current_version.id,\n payload_entries= [\n INewSecretPayloadEntry(key=\"secret_entry_1\", text_value=\"secret_entry_text_value\"),\n INewSecretPayloadEntry(key=\"secret_entry_2\", binary_value=\"secret_entry_binary_value\"),\n ]\n )\n)\n\n# alternative\nlockbox.add_secret_version(\n \"secret_id\",\n version=INewSecretVersion(\n description=\"a new version\",\n base_version_id=secret.current_version.id,\n payload_entries=[INewSecretPayloadEntry(...), INewSecretPayloadEntry(...)]\n )\n)\n```\n\n\n### Other operations with secret\n\n```python\nfrom yc_lockbox import YandexLockboxClient\n\nlockbox = YandexLockboxClient(\"oauth_or_iam_token\")\n\n\nfor secret in lockbox.list_secrets(folder_id=\"b1xxxxxxxxxx\", iterator=True):\n print(secret.name, secret.status)\n\n secret.deactivate()\n secret.activate()\n\n for version in secret.list_versions(iterator=True): # if iterator=False returns paginated list with ``next_page_token``\n if version.id != secret.current_version.id:\n version.schedule_version_destruction()\n version.cancel_version_destruction()\n\n```\n\n## Async mode\n\nThe client supports asynchronous mode using the aiohttp library. The signature of the methods does not differ from the synchronous implementation.\n\n\nJust import async client:\n\n```python\n\nfrom yc_lockbox import AsyncYandexLockboxClient\n\nlockbox = AsyncYandexLockboxClient(\"oauth_or_iam_token\")\n```\n\nAlternative:\n\n```python\n\nfrom yc_lockbox import YandexLockboxFacade\n\nlockbox = YandexLockboxFacade(\"oauth_or_iam_token\", enable_async=True).client\n```\n\nExample usage:\n\n```python\nsecret: Secret = await lockbox.get_secret(\"e6qxxxxxxxxxx\")\npayload = await secret.payload()\nprint(payload.entries) # list of SecretPayloadEntry objects\n\n# Direct access\n\nentry = payload[\"secret_entry_1\"] # or payload.get(\"secret_entry_1\")\n\nprint(entry.text_value) # return MASKED value like ***********\nprint(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()\n\n# Async iterators\n\nsecret_versions = await secret.list_versions(iterator=True)\n\nasync for version in secret_versions:\n if version.id != secret.current_version.id:\n await version.schedule_version_destruction()\n await version.cancel_version_destruction()\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Yandex Lockbox client",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/akimrx/python-yc-lockbox"
},
"split_keywords": [
"yandex",
" cloud",
" vault",
" secrets",
" lockbox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cf0a4a3dcb8fb514e9ee305492edcda96a4a6cdb4d006decde55077a0ca094e0",
"md5": "118cafb5d789afcf2384beab4acdfdf5",
"sha256": "f9f0095ee4c9192b69879c66cc7818b412f15214d2a580c2b9dbfc09f07dc153"
},
"downloads": -1,
"filename": "yc_lockbox-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "118cafb5d789afcf2384beab4acdfdf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19745,
"upload_time": "2024-04-02T08:10:39",
"upload_time_iso_8601": "2024-04-02T08:10:39.367544Z",
"url": "https://files.pythonhosted.org/packages/cf/0a/4a3dcb8fb514e9ee305492edcda96a4a6cdb4d006decde55077a0ca094e0/yc_lockbox-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bd8986c99496c7359560effe0c9eaaf01410897728027b13e75cb220f3c37dad",
"md5": "e1d8d04c20e014cc68e8c78415f25842",
"sha256": "d5d676abbf03db476a83c49f94a63e33868b165173c4799edccd979eaff3393e"
},
"downloads": -1,
"filename": "yc-lockbox-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e1d8d04c20e014cc68e8c78415f25842",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19853,
"upload_time": "2024-04-02T08:10:40",
"upload_time_iso_8601": "2024-04-02T08:10:40.628877Z",
"url": "https://files.pythonhosted.org/packages/bd/89/86c99496c7359560effe0c9eaaf01410897728027b13e75cb220f3c37dad/yc-lockbox-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 08:10:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akimrx",
"github_project": "python-yc-lockbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "cryptography",
"specs": [
[
">=",
"42.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.0.0"
]
]
},
{
"name": "PyJWT",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.5.0"
]
]
},
{
"name": "requests",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.30.0"
]
]
}
],
"lcname": "yc-lockbox"
}
JSON
