| Name | ledgercomm JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | https://github.com/LedgerHQ/ledgercomm |
| Summary | Library to communicate with Ledger Nano S/X and Speculos |
| upload_time | 2024-01-12 12:51:09 |
| maintainer | |
| docs_url | None |
| author | Ledger |
| requires_python | >=3.8 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# LedgerCOMM
## Overview
Python library to send and receive [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit) through HID or TCP socket.
It can be used with a Ledger Nano S/X or with the [Speculos](https://github.com/LedgerHQ/speculos) emulator.
## Install
If you just want to communicate through TCP socket, there is no dependency
```bash
$ pip install ledgercomm
```
otherwise, [hidapi](https://github.com/trezor/cython-hidapi) must be installed as an extra dependency like this
```bash
$ pip install ledgercomm[hid]
```
## Getting started
### Library
```python
from ledgercomm import Transport
# Nano S/X using HID interface
transport = Transport(interface="hid", debug=True)
# or Speculos through TCP socket
transport = Transport(interface="tcp", server="127.0.0.1", port=9999, debug=True)
#
# send/recv APDUs
#
# send method for structured APDUs
transport.send(cla=0xe0, ins=0x03, p1=0, p2=0, cdata=b"") # send b"\xe0\x03\x00\x00\x00"
# or send_raw method for hexadecimal string
transport.send_raw("E003000000") # send b"\xe0\x03\x00\x00\x00"
# or with bytes type
transport.send_raw(b"\xe0\x03\x00\x00\x00")
# Waiting for a response (blocking IO)
sw, response = transport.recv() # type: int, bytes
#
# exchange APDUs (one time send/recv)
#
# exchange method for structured APDUs
sw, response = transport.exchange(cla=0xe0, ins=0x03, p1=0, p2=0, cdata=b"") # send b"\xe0\x03\x00\x00\x00"
# or exchange_raw method for hexadecimal string
sw, reponse = transport.exchange_raw("E003000000") # send b"\xe0\x03\x00\x00\x00"
# or with bytes type
sw, response = transport.exchange_raw(b"\xe0\x03\x00\x00\x00")
```
### CLI
#### Usage
When installed, `ledgercomm` provides a CLI tool named `ledgercomm-send`
```bash
$ ledgercomm-send --help
usage: ledgercomm-send [-h] [--hid] [--server SERVER] [--port PORT] [--startswith STARTSWITH]
{file,stdin,log} ...
positional arguments:
{file,stdin,log} sub-command help
file send APDUs from file
stdin send APDUs from stdin
log send APDUs from Ledger Live log file
optional arguments:
-h, --help show this help message and exit
--hid Use HID instead of TCP client
--server SERVER IP server of the TCP client (default: 127.0.0.1)
--port PORT Port of the TCP client (default: 9999)
--startswith STARTSWITH
Only send APDUs starting with STARTSWITH (default: None)
```
#### Example
If Speculos is launched with default parameters or your Nano S/X is plugged with correct udev rules, you can send APDUs from stdin
```bash
$ echo "E003000000" | ledgercomm-send stdin # Speculos
$ echo "E003000000" | ledgercomm-send --hid stdin # Nano S/X
```
Or you can replay APDUs using the following text file named `apdus.txt` with some condition
```text
# this line won't be send if you've the right STARTSWITH condition
=> E003000000
# another APDU to send
=> E004000000
```
then
```bash
$ ledgercomm-send --startswith "=>" file apdus.txt
```
Raw data
{
"_id": null,
"home_page": "https://github.com/LedgerHQ/ledgercomm",
"name": "ledgercomm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Ledger",
"author_email": "hello@ledger.fr",
"download_url": "https://files.pythonhosted.org/packages/93/8b/31d9445c092d5f44ba22c26452bd235fa1b2b3b15fd21e98e9c5cbf170ef/ledgercomm-1.2.1.tar.gz",
"platform": null,
"description": "# LedgerCOMM\n\n## Overview\n\nPython library to send and receive [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit) through HID or TCP socket.\nIt can be used with a Ledger Nano S/X or with the [Speculos](https://github.com/LedgerHQ/speculos) emulator.\n\n## Install\n\nIf you just want to communicate through TCP socket, there is no dependency\n\n```bash\n$ pip install ledgercomm\n```\n\notherwise, [hidapi](https://github.com/trezor/cython-hidapi) must be installed as an extra dependency like this\n\n```bash\n$ pip install ledgercomm[hid]\n```\n\n## Getting started\n\n### Library\n\n```python\nfrom ledgercomm import Transport\n\n# Nano S/X using HID interface\ntransport = Transport(interface=\"hid\", debug=True)\n# or Speculos through TCP socket\ntransport = Transport(interface=\"tcp\", server=\"127.0.0.1\", port=9999, debug=True)\n\n#\n# send/recv APDUs\n#\n\n# send method for structured APDUs\ntransport.send(cla=0xe0, ins=0x03, p1=0, p2=0, cdata=b\"\") # send b\"\\xe0\\x03\\x00\\x00\\x00\"\n# or send_raw method for hexadecimal string\ntransport.send_raw(\"E003000000\") # send b\"\\xe0\\x03\\x00\\x00\\x00\"\n# or with bytes type\ntransport.send_raw(b\"\\xe0\\x03\\x00\\x00\\x00\")\n\n# Waiting for a response (blocking IO)\nsw, response = transport.recv() # type: int, bytes\n\n#\n# exchange APDUs (one time send/recv)\n#\n\n# exchange method for structured APDUs\nsw, response = transport.exchange(cla=0xe0, ins=0x03, p1=0, p2=0, cdata=b\"\") # send b\"\\xe0\\x03\\x00\\x00\\x00\"\n# or exchange_raw method for hexadecimal string\nsw, reponse = transport.exchange_raw(\"E003000000\") # send b\"\\xe0\\x03\\x00\\x00\\x00\"\n# or with bytes type\nsw, response = transport.exchange_raw(b\"\\xe0\\x03\\x00\\x00\\x00\")\n\n```\n\n### CLI\n\n#### Usage\n\nWhen installed, `ledgercomm` provides a CLI tool named `ledgercomm-send`\n\n```bash\n$ ledgercomm-send --help\nusage: ledgercomm-send [-h] [--hid] [--server SERVER] [--port PORT] [--startswith STARTSWITH]\n {file,stdin,log} ...\n\npositional arguments:\n {file,stdin,log} sub-command help\n file send APDUs from file\n stdin send APDUs from stdin\n log send APDUs from Ledger Live log file\n\noptional arguments:\n -h, --help show this help message and exit\n --hid Use HID instead of TCP client\n --server SERVER IP server of the TCP client (default: 127.0.0.1)\n --port PORT Port of the TCP client (default: 9999)\n --startswith STARTSWITH\n Only send APDUs starting with STARTSWITH (default: None)\n```\n\n#### Example\n\nIf Speculos is launched with default parameters or your Nano S/X is plugged with correct udev rules, you can send APDUs from stdin\n\n```bash\n$ echo \"E003000000\" | ledgercomm-send stdin # Speculos\n$ echo \"E003000000\" | ledgercomm-send --hid stdin # Nano S/X\n```\n\nOr you can replay APDUs using the following text file named `apdus.txt` with some condition\n\n```text\n# this line won't be send if you've the right STARTSWITH condition\n=> E003000000\n# another APDU to send\n=> E004000000\n```\n\nthen\n\n```bash\n$ ledgercomm-send --startswith \"=>\" file apdus.txt\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Library to communicate with Ledger Nano S/X and Speculos",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/LedgerHQ/ledgercomm/issues",
"Homepage": "https://github.com/LedgerHQ/ledgercomm"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c607633e1da1b002822d18614e7faf924bc7c3064a11b1879cc0fd4a153d727c",
"md5": "ad0ff04fd955937c06367d9f8f62bb65",
"sha256": "8ffef5703355b8ec7b73bca325f70288f4d0dafcb299c09833de9c197fb6dd34"
},
"downloads": -1,
"filename": "ledgercomm-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad0ff04fd955937c06367d9f8f62bb65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11981,
"upload_time": "2024-01-12T12:51:08",
"upload_time_iso_8601": "2024-01-12T12:51:08.387252Z",
"url": "https://files.pythonhosted.org/packages/c6/07/633e1da1b002822d18614e7faf924bc7c3064a11b1879cc0fd4a153d727c/ledgercomm-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "938b31d9445c092d5f44ba22c26452bd235fa1b2b3b15fd21e98e9c5cbf170ef",
"md5": "54d803b9ef79cf04d9970666c6626fd4",
"sha256": "015cfc05f16b8c59f8cc1d9fc0b8935923f1fcc3806d33eeb6b0e055b44f5a91"
},
"downloads": -1,
"filename": "ledgercomm-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "54d803b9ef79cf04d9970666c6626fd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14245,
"upload_time": "2024-01-12T12:51:09",
"upload_time_iso_8601": "2024-01-12T12:51:09.950382Z",
"url": "https://files.pythonhosted.org/packages/93/8b/31d9445c092d5f44ba22c26452bd235fa1b2b3b15fd21e98e9c5cbf170ef/ledgercomm-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 12:51:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LedgerHQ",
"github_project": "ledgercomm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ledgercomm"
}
