{"id":22253692,"url":"https://github.com/nitrokey/nethsm-sdk-py","last_synced_at":"2025-07-28T05:32:48.676Z","repository":{"id":196209053,"uuid":"694708963","full_name":"Nitrokey/nethsm-sdk-py","owner":"Nitrokey","description":" Client-side Python SDK for NetHSM","archived":false,"fork":false,"pushed_at":"2025-06-30T14:23:06.000Z","size":87258,"stargazers_count":2,"open_issues_count":12,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-18T07:42:22.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nitrokey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-21T14:32:56.000Z","updated_at":"2025-06-23T08:14:49.000Z","dependencies_parsed_at":"2024-05-16T08:54:25.550Z","dependency_job_id":null,"html_url":"https://github.com/Nitrokey/nethsm-sdk-py","commit_stats":null,"previous_names":["nitrokey/nethsm-sdk-py"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/Nitrokey/nethsm-sdk-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnethsm-sdk-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnethsm-sdk-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnethsm-sdk-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnethsm-sdk-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nitrokey","download_url":"https://codeload.github.com/Nitrokey/nethsm-sdk-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnethsm-sdk-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267468366,"owners_count":24092330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T07:19:30.072Z","updated_at":"2025-07-28T05:32:43.664Z","avatar_url":"https://github.com/Nitrokey.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nethsm-sdk-py\n\nPython client for NetHSM. NetHSM documentation available here: [NetHSM documentation](https://docs.nitrokey.com/nethsm/)\n\n[![codecov.io][codecov-badge]][codecov-url]\n\n[codecov-badge]: https://codecov.io/gh/nitrokey/nethsm-sdk-py/branch/main/graph/badge.svg\n[codecov-url]: https://app.codecov.io/gh/nitrokey/nethsm-sdk-py/tree/main\n\n## Usage\n\nInstallation:\n\n```sh\npip install nethsm\n```\n\nExample program:\n\n```py\nimport nethsm\n\nadmin_passphrase = \"adminadmin\"\nunlock_passphrase = \"unlockunlock\"\n\nwith nethsm.connect(\n    host=\"nethsmdemo.nitrokey.com\",\n    auth=nethsm.Authentication(username=\"admin\", password=admin_passphrase),\n) as client:\n    if client.get_state() == nethsm.State.UNPROVISIONED:\n        client.provision(\n            unlock_passphrase=unlock_passphrase,\n            admin_passphrase=admin_passphrase,\n        )\n\n    if client.get_state() == nethsm.State.LOCKED:\n        client.unlock(unlock_passphrase)\n\n    assert client.get_state() == nethsm.State.OPERATIONAL\n\n    client.generate_key(\n        type=nethsm.KeyType.RSA,\n        length=2048,\n        mechanisms=[\n            nethsm.KeyMechanism.RSA_SIGNATURE_PKCS1,\n            nethsm.KeyMechanism.RSA_DECRYPTION_PKCS1,\n            nethsm.KeyMechanism.RSA_SIGNATURE_PSS_SHA256,\n            nethsm.KeyMechanism.RSA_DECRYPTION_OAEP_SHA256, \n        ],\n    )\n\n    print(client.list_keys())\n```\n\n## Compatibility\n\nThe following table provides an overview of the SDK versions that added support for new NetHSM features:\n\n| SDK Version | NetHSM Version | New Features |\n| :---------: | :------------: | ------------ |\n| [v1.0.0][sdk-v1.0.0] | [v1.0][nethsm-v1.0] |  |\n| [v1.2.0][sdk-v1.2.0] | [v2.0][nethsm-v2.0] | Namespaces |\n\n[nethsm-v1.0]: https://github.com/Nitrokey/nethsm/releases/tag/v1.0\n[nethsm-v2.0]: https://github.com/Nitrokey/nethsm/releases/tag/v2.0\n[sdk-v1.0.0]: https://github.com/Nitrokey/nethsm-sdk-py/releases/tag/v1.0.0\n[sdk-v1.2.0]: https://github.com/Nitrokey/nethsm-sdk-py/releases/tag/v1.2.0\n\nNew features are added in a backwards-compatible way if possible.\nTrying to use them on older NetHSM versions may result in unexpected error messages.\n\n## Development\n\n### Setting Up The Environment\n\nUse `make init` to set up the development environment.\n\nYou can then run `make check` to run the checks on your changes and `make fix` to format the code.\n\n### Updating the client\n\nTo update the NetHSM HTTP client, you need to download the updated ``nethsm-api.yml`` OpenAPI specification. The easiest is to download it from the NetHSM demo server (``curl`` required):\n\n```sh\nmake nethsm-api.yaml --always-make\n```\n\nThen, run the generation script, docker is required:\n\n```sh\nmake nethsm-client\n```  \n\nBe sure to run the linter, tests and check that everything is working as expected after the update.\n\n### Custom functions\n\nThe generator doesn't support upload of binary files and custom `Content-Type` headers (fails to serialize).\nTo work around this, some functions are written manually, using `NetHSM._request()` to send the request.\n\nThe current list of such functions is:\n\n- `NetHSM.set_certificate()` : `/config/tls/cert.pem`\n\nAlso, the generator cannot deserialize responses with a header that is specified in the OpenAPI document.\nTherefore, the following functions manually deserialize the API response:\n\n- `NetHSM.add_key()`: `/keys`\n- `NetHSM.generate_key()`: `/keys/generate`\n- `NetHSM.add_user()`: `/users`\n\n### Publishing a new version\n\n- change `__version__` in `nethsm/__init__.py`. Example : 0.1.0\n- create a new tag, prepending `v` to the version. Example : v0.1.0\n- create a new release on GitHub to trigger the ci that will publish the new version.\n\n### Adding new tests\n\nTesting is done via `pytest`. A test is loaded when the name of the file starts with `test_` and the function doing the test is prefixed by `test`.\n\nPytest fixtures are used, to get a provisioned and initialized NetHSM object to interact with, use `nethsm` as a parameter of your test function. For an unprovisioned NetHSM use `nethsm_no_provision`.\n\nIf you want to force a reset (clearing the data) of the NetHSM instance, use `start_nethsm()`, it will kill and restart the process.\n\nIf you want to get debug logs when running the tests, run `pytest -s`.\n\nWhen a test is currently broken and expected to fail, decorate the test function with:\n\n```python\n@pytest.mark.xfail(reason=\"reason\")\n```\n\nYou can mark a test to be skipped:\n\n```python\n@pytest.mark.skip(reason=\"reason\")\n```\n\n#### Test modes\n\nBy default these tests assume that a docker daemon is running and that open ports on containers can be accessed via `127.0.0.1`, meaning it will not work if run in a container.\n\nIf you want to run these tests in a container, use the `docker.io/nitrokey/nethsm:testing` image and set the environment variable `TEST_MODE=ci`. Example:\n\n```sh\ndocker run -v \"$PWD:/nethsm\" -e FLIT_ROOT_INSTALL=1 -e TEST_MODE=ci -it --entrypoint /bin/sh nitrokey/nethsm:testing -c \"apk add make python3 \u0026\u0026 cd /nethsm \u0026\u0026 make init \u0026\u0026 make test\"\n```\n\n\u003e Be aware this command will create files owned by root in your working directory.\n\nThis CI mode manually start and stops the necessary processes to run a NetHSM instance, due to its design it may break when the container image is updated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnethsm-sdk-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitrokey%2Fnethsm-sdk-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnethsm-sdk-py/lists"}