| Name | sbtse JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Library and tool to access Swissbit TSE |
| upload_time | 2024-11-03 15:29:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache-2.0 |
| keywords |
swissbit
tse
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pysbtse
Python bindings and command-line tool for the Swissbit TSE.
## Setup
Install ``sbtse`` like any Python package, e.g. with pip. Additionally, you need ``libWormAPI.so`` for your architecture
in your library path or your working directory. We are not allowed to distribute this library here, so please try to
find it on the internet or request it from a Swissbit TSE seller.
## Capabilities
This module includes an auto-generated ctypes wrapper for the `libWormAPI.so` from Swissbit SDK 5.9.1.
On top of that, it includes a high-level Python interface to work with the TSE.
The Python interface supports all features of the offline SDK except for:
- Online firmware updates and manual firmware transfer (bundled firmware updates are supported)
- Incremental TAR exports
- Export lifetime monitoring information
LAN TSE support is implemented but not tested.
## Command line usage
```
Usage: sbtse [OPTIONS] COMMAND [ARGS]...
Options:
--path DIRECTORY TSE mount point
--url TEXT LAN TSE URL
--api-key TEXT LAN TSE API Key
--tse TEXT LAN TSE serial number
--help Show this message and exit.
Commands:
config Manipulate TSE configuration
delete Delete stored data.
entries Query log entries
export Export stored data.
factory-reset Factory reset (development TSE only)
firmware-update Update firmware to version bundled with SDK.
info Show info and flash health status
pin Manage Admin PIN
puk Manage PUK
selftest Run self-test
serve Run local API server
setup Run setup procedure for a fresh TSE
time-admin-pin Manage Time Admin PIN
transaction Create and query transactions
```
Run ``sbtse --path /mnt/tse COMMAND --help`` for the options and subcommands of the commands.
## Python library usage
Example:
```python
from sbtse import worm, errors
client_id = "TEST"
admin_pin = "12345"
admin_puk = "123456"
time_admin_pin = "12345"
print("SDK version:", worm.get_version())
with worm.LocalWormContext("/mnt/tse/") as w:
info = w.info()
print("Info:", info)
print("Initial credentials:", w.derive_initial_credentials())
print("Running self test...")
try:
w.run_self_test(client_id)
except errors.WormErrorClientNotRegistered:
print("Not registered.")
if info["hasChangedAdminPin"]:
w.login_as_admin(admin_pin)
w.register_client(client_id)
else:
w.setup(client_id, admin_pin, admin_puk, time_admin_pin)
if w.bundled_firmware_update_available():
print("Updating firmware...")
w.bundled_firmware_update_apply()
print("Flash health:", w.flash_health())
w.login_as_time_admin(time_admin_pin)
w.update_time()
print("Registered clients:", w.list_registered_clients())
# Transaction handling
print("Performing transaction...")
tx = w.transaction_start(client_id, "", "")
print("Started transactions:", w.list_started_transactions())
print("Finished transaction:", w.transaction_finish(client_id, tx["transactionNumber"], "Foobar", "Kassenbeleg"))
# Export capabilities
print("Last transaction:", w.last_transaction())
for tx in w.iterate_entries():
print("Entry:", tx)
print("Certificate:", w.get_log_message_certificate())
print("Exporting TAR…")
with open("export.tar", "wb") as f:
w.export_tar(f)
print("Exporting filtered TAR…")
with open("export_tx_filtered.tar", "wb") as f:
w.export_tar(f, start_transaction=0, end_transaction=2, client_id=client_id)
```
The example does not show all features. Have a look at ``help(LocalWormContext)`` for a full list of methods.
For LAN TSE (untested):
```python
from sbtse import worm
with worm.LANWormContext("https://10.1.1.1:9000", "api_key") as w:
tses = w.list_connected_tses()
print("TSEs:", tses)
w.select_tse(tses[0])
with w.lock_tse():
w.setup(...)
...
```
## API Usage
The API is executed as a single-thread single-process worker to avoid concurrent access to the TSE which might be problematic.
However, this also means that the API might be slow to respond under concurrent access. This is intentional.
| Method | Path | Description |
| --- |--------------------------------------------------------------------------------|--------------------------------------------------|
| GET | [/info](#getinfo) | Retrieve information about the TSE |
| GET | [/health](#gethealth) | Retrieve health status information about the TSE |
| GET | [/certificate](#getcertificate) | Retrieve the certificate used for signing |
| POST | [/transactions/](#posttransactions) | Start a transcation |
| POST | [/transactions/{transaction_id}/update](#posttransactionstransaction_idupdate) | Update a transaction |
| POST | [/transactions/{transaction_id}/finish](#posttransactionstransaction_idfinish) | Finish a transaction |
### [GET] /info
Retrieve information about the TSE
#### Responses
- 200 Successful Response
`application/json`
```ts
{
isDevelopmentFirmware: boolean
capacity: integer
size: integer
hasValidTime: boolean
hasPassedSelfTest: boolean
isCtssInterfaceActive: boolean
isExportEnabledIfCspTestFails: boolean
initializationState: string
hasChangedPuk: boolean
hasChangedAdminPin: boolean
timeUntilNextSelfTest: integer
startedTransactions: integer
maxStartedTransactions: integer
createdSignatures: integer
maxSignatures: integer
remainingSignatures: integer
maxTimeSynchronizationDelay: integer
maxUpdateDelay: integer
tsePublicKey: string
timeUntilNextTimeSynchronization: integer
tseSerialNumberBytes: string
tseSerialNumberHex: string
tseDescription: string
registeredClients: integer
maxRegisteredClients: integer
certificateExpirationDate: string
tarExportSizeInSectors: integer
tarExportSize: integer
hardwareVersion: integer
softwareVersion: integer
formFactor: string
logTimeFormat: str
signatureAlgorithm: str
}
```
### [GET] /health
Retrieve health information about the TSE
#### Responses
- 200 Successful Response
`application/json`
```ts
{
uncorrectableEccErrors: integer
percentageRemainingSpareBlocks: integer
percentageRemainingEraseCounts: integer
percentageRemainingTenYearsDataRetention: integer
needsReplacement: boolean
}
```
### [GET] /certificate
Retrieve the certificate used for signing
### [POST] /transactions/
Start a transaction
#### Request body
- application/json
```ts
{
client_id: string
process_data: string
process_type: string
}
```
#### Responses
- 200 Successful Response
`application/json`
```ts
{
logTime: integer
serialNumberHex: string
signatureCounter: integer
transactionNumber: integer
signatureBase64: string
}
```
### [POST] /transactions/{transaction_id}/update
Update a transaction
#### Request body
- application/json
```ts
{
client_id: string
process_data: string
process_type: string
}
```
#### Responses
- 200 Successful Response
`application/json`
```ts
{
logTime: integer
serialNumberHex: string
signatureCounter: integer
transactionNumber: integer
signatureBase64: string
}
```
### [POST] /transactions/{transaction_id}/finish
Finish a transaction
#### Request body
- application/json
```ts
{
client_id: string
process_data: string
process_type: string
}
```
#### Responses
- 200 Successful Response
`application/json`
```ts
{
logTime: integer
serialNumberHex: string
signatureCounter: integer
transactionNumber: integer
signatureBase64: string
}
```
## License
The code in this library is licensed under the Apache 2.0 license.
Note that the binary library and documentation provided by Swissbit is provided under the "Swissbit Device Driver Adaptation & Distribution License" and therefore not shared in this repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "sbtse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "swissbit, tse",
"author": null,
"author_email": "Raphael Michel <mail@raphaelmichel.de>",
"download_url": "https://files.pythonhosted.org/packages/df/95/6b1a30b8e7ce8ef7d980863f18e810b8540e0f5dbe8ed347914ba0938059/sbtse-0.3.1.tar.gz",
"platform": null,
"description": "# pysbtse\n\nPython bindings and command-line tool for the Swissbit TSE. \n\n## Setup\n\nInstall ``sbtse`` like any Python package, e.g. with pip. Additionally, you need ``libWormAPI.so`` for your architecture\nin your library path or your working directory. We are not allowed to distribute this library here, so please try to\nfind it on the internet or request it from a Swissbit TSE seller.\n\n## Capabilities\n\nThis module includes an auto-generated ctypes wrapper for the `libWormAPI.so` from Swissbit SDK 5.9.1.\nOn top of that, it includes a high-level Python interface to work with the TSE.\nThe Python interface supports all features of the offline SDK except for:\n\n- Online firmware updates and manual firmware transfer (bundled firmware updates are supported)\n- Incremental TAR exports\n- Export lifetime monitoring information\n\nLAN TSE support is implemented but not tested.\n\n\n## Command line usage\n\n```\nUsage: sbtse [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --path DIRECTORY TSE mount point\n --url TEXT LAN TSE URL\n --api-key TEXT LAN TSE API Key\n --tse TEXT LAN TSE serial number\n --help Show this message and exit.\n\nCommands:\n config Manipulate TSE configuration\n delete Delete stored data.\n entries Query log entries\n export Export stored data.\n factory-reset Factory reset (development TSE only)\n firmware-update Update firmware to version bundled with SDK.\n info Show info and flash health status\n pin Manage Admin PIN\n puk Manage PUK\n selftest Run self-test\n serve Run local API server\n setup Run setup procedure for a fresh TSE\n time-admin-pin Manage Time Admin PIN\n transaction Create and query transactions\n```\n\nRun ``sbtse --path /mnt/tse COMMAND --help`` for the options and subcommands of the commands.\n\n## Python library usage\n\nExample:\n\n```python\nfrom sbtse import worm, errors\n\nclient_id = \"TEST\"\nadmin_pin = \"12345\"\nadmin_puk = \"123456\"\ntime_admin_pin = \"12345\"\n\nprint(\"SDK version:\", worm.get_version())\n\nwith worm.LocalWormContext(\"/mnt/tse/\") as w:\n info = w.info()\n print(\"Info:\", info)\n print(\"Initial credentials:\", w.derive_initial_credentials())\n print(\"Running self test...\")\n try:\n w.run_self_test(client_id)\n except errors.WormErrorClientNotRegistered:\n print(\"Not registered.\")\n if info[\"hasChangedAdminPin\"]:\n w.login_as_admin(admin_pin)\n w.register_client(client_id)\n else:\n w.setup(client_id, admin_pin, admin_puk, time_admin_pin)\n \n if w.bundled_firmware_update_available():\n print(\"Updating firmware...\")\n w.bundled_firmware_update_apply()\n \n print(\"Flash health:\", w.flash_health())\n w.login_as_time_admin(time_admin_pin)\n w.update_time()\n \n print(\"Registered clients:\", w.list_registered_clients())\n \n # Transaction handling\n print(\"Performing transaction...\")\n tx = w.transaction_start(client_id, \"\", \"\")\n print(\"Started transactions:\", w.list_started_transactions())\n print(\"Finished transaction:\", w.transaction_finish(client_id, tx[\"transactionNumber\"], \"Foobar\", \"Kassenbeleg\"))\n \n # Export capabilities\n print(\"Last transaction:\", w.last_transaction())\n for tx in w.iterate_entries():\n print(\"Entry:\", tx)\n print(\"Certificate:\", w.get_log_message_certificate())\n \n print(\"Exporting TAR\u2026\")\n with open(\"export.tar\", \"wb\") as f:\n w.export_tar(f)\n\n print(\"Exporting filtered TAR\u2026\")\n with open(\"export_tx_filtered.tar\", \"wb\") as f:\n w.export_tar(f, start_transaction=0, end_transaction=2, client_id=client_id)\n```\n\nThe example does not show all features. Have a look at ``help(LocalWormContext)`` for a full list of methods.\n\nFor LAN TSE (untested):\n\n```python\nfrom sbtse import worm\n\nwith worm.LANWormContext(\"https://10.1.1.1:9000\", \"api_key\") as w:\n tses = w.list_connected_tses()\n print(\"TSEs:\", tses)\n w.select_tse(tses[0])\n with w.lock_tse():\n w.setup(...)\n ...\n```\n\n## API Usage\n\nThe API is executed as a single-thread single-process worker to avoid concurrent access to the TSE which might be problematic.\nHowever, this also means that the API might be slow to respond under concurrent access. This is intentional.\n\n| Method | Path | Description |\n| --- |--------------------------------------------------------------------------------|--------------------------------------------------|\n| GET | [/info](#getinfo) | Retrieve information about the TSE |\n| GET | [/health](#gethealth) | Retrieve health status information about the TSE |\n| GET | [/certificate](#getcertificate) | Retrieve the certificate used for signing |\n| POST | [/transactions/](#posttransactions) | Start a transcation |\n| POST | [/transactions/{transaction_id}/update](#posttransactionstransaction_idupdate) | Update a transaction |\n| POST | [/transactions/{transaction_id}/finish](#posttransactionstransaction_idfinish) | Finish a transaction |\n\n### [GET] /info\n\nRetrieve information about the TSE\n\n#### Responses\n\n- 200 Successful Response\n\n`application/json`\n\n```ts\n{\n isDevelopmentFirmware: boolean\n capacity: integer\n size: integer\n hasValidTime: boolean\n hasPassedSelfTest: boolean\n isCtssInterfaceActive: boolean\n isExportEnabledIfCspTestFails: boolean\n initializationState: string\n hasChangedPuk: boolean\n hasChangedAdminPin: boolean\n timeUntilNextSelfTest: integer\n startedTransactions: integer\n maxStartedTransactions: integer\n createdSignatures: integer\n maxSignatures: integer\n remainingSignatures: integer\n maxTimeSynchronizationDelay: integer\n maxUpdateDelay: integer\n tsePublicKey: string\n timeUntilNextTimeSynchronization: integer\n tseSerialNumberBytes: string\n tseSerialNumberHex: string\n tseDescription: string\n registeredClients: integer\n maxRegisteredClients: integer\n certificateExpirationDate: string\n tarExportSizeInSectors: integer\n tarExportSize: integer\n hardwareVersion: integer\n softwareVersion: integer\n formFactor: string\n logTimeFormat: str\n signatureAlgorithm: str\n}\n```\n\n### [GET] /health\n\nRetrieve health information about the TSE\n\n#### Responses\n\n- 200 Successful Response\n\n`application/json`\n\n```ts\n{\n uncorrectableEccErrors: integer\n percentageRemainingSpareBlocks: integer\n percentageRemainingEraseCounts: integer\n percentageRemainingTenYearsDataRetention: integer\n needsReplacement: boolean\n}\n```\n\n### [GET] /certificate\n\nRetrieve the certificate used for signing\n\n### [POST] /transactions/\n\nStart a transaction\n\n#### Request body\n\n- application/json\n\n```ts\n{\n client_id: string\n process_data: string\n process_type: string\n}\n```\n\n#### Responses\n\n- 200 Successful Response\n\n`application/json`\n\n```ts\n{\n logTime: integer\n serialNumberHex: string\n signatureCounter: integer\n transactionNumber: integer\n signatureBase64: string\n}\n```\n\n### [POST] /transactions/{transaction_id}/update\n\nUpdate a transaction\n\n#### Request body\n\n- application/json\n\n```ts\n{\n client_id: string\n process_data: string\n process_type: string\n}\n```\n\n#### Responses\n\n- 200 Successful Response\n\n`application/json`\n\n```ts\n{\n logTime: integer\n serialNumberHex: string\n signatureCounter: integer\n transactionNumber: integer\n signatureBase64: string\n}\n```\n\n### [POST] /transactions/{transaction_id}/finish\n\nFinish a transaction\n\n#### Request body\n\n- application/json\n\n```ts\n{\n client_id: string\n process_data: string\n process_type: string\n}\n```\n\n#### Responses\n\n- 200 Successful Response\n\n`application/json`\n\n```ts\n{\n logTime: integer\n serialNumberHex: string\n signatureCounter: integer\n transactionNumber: integer\n signatureBase64: string\n}\n```\n\n\n## License\n\nThe code in this library is licensed under the Apache 2.0 license.\nNote that the binary library and documentation provided by Swissbit is provided under the \"Swissbit Device Driver Adaptation & Distribution License\" and therefore not shared in this repository.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Library and tool to access Swissbit TSE",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [
"swissbit",
" tse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "445c6fbeb8b6e39066b9d935203719152ef056b7ba125852c48e7e6997322f91",
"md5": "1ef510c9145c0143c0415bcce7e0d10a",
"sha256": "d742b5080499cba39287b8009d3f2b53ec67bf686974706c65f86ddd367a19ea"
},
"downloads": -1,
"filename": "sbtse-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ef510c9145c0143c0415bcce7e0d10a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34561,
"upload_time": "2024-11-03T15:29:36",
"upload_time_iso_8601": "2024-11-03T15:29:36.464793Z",
"url": "https://files.pythonhosted.org/packages/44/5c/6fbeb8b6e39066b9d935203719152ef056b7ba125852c48e7e6997322f91/sbtse-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df956b1a30b8e7ce8ef7d980863f18e810b8540e0f5dbe8ed347914ba0938059",
"md5": "60d7eccddda92b777ae5b1f7b12b3e6d",
"sha256": "78f433b1eea686da133cf8b25617b6eacfed9299ad86374fb5f05a70cd1c3262"
},
"downloads": -1,
"filename": "sbtse-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "60d7eccddda92b777ae5b1f7b12b3e6d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 35511,
"upload_time": "2024-11-03T15:29:41",
"upload_time_iso_8601": "2024-11-03T15:29:41.260947Z",
"url": "https://files.pythonhosted.org/packages/df/95/6b1a30b8e7ce8ef7d980863f18e810b8540e0f5dbe8ed347914ba0938059/sbtse-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 15:29:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sbtse"
}
