ledgercomm


Nameledgercomm JSON
Version 1.2.1 PyPI version JSON
download
home_pagehttps://github.com/LedgerHQ/ledgercomm
SummaryLibrary to communicate with Ledger Nano S/X and Speculos
upload_time2024-01-12 12:51:09
maintainer
docs_urlNone
authorLedger
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"
}
        
Elapsed time: 0.35398s