# Ethereum Keys
A common API for Ethereum key operations with pluggable backends.
> This library and repository was previously located at https://github.com/pipermerriam/ethereum-keys. It was transferred to the Ethereum foundation github in November 2017 and renamed to `ethrpc-keys`. The PyPi package was also renamed from `ethereum-keys` to `ethrpc-keys`.
## Installation
```sh
pip install ethrpc-keys
```
## Development
```sh
pip install -e .[dev]
```
### Running the tests
You can run the tests with:
```sh
py.test tests
```
Or you can install `tox` to run the full test suite.
### Releasing
Pandoc is required for transforming the markdown README to the proper format to
render correctly on pypi.
For Debian-like systems:
```
apt install pandoc
```
Or on OSX:
```sh
brew install pandoc
```
To release a new version:
```sh
make release bump=$$VERSION_PART_TO_BUMP$$
```
#### How to bumpversion
The version format for this repo is `{major}.{minor}.{patch}` for stable, and
`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).
To issue the next version in line, specify which part to bump,
like `make release bump=minor` or `make release bump=devnum`.
If you are in a beta version, `make release bump=stage` will switch to a stable.
To issue an unstable version when the current version is stable, specify the
new version explicitly, like `make release bump="--new-version 2.0.0-alpha.1 devnum"`
## QuickStart
```python
>>> from ethrpc_keys import keys
>>> pk = keys.PrivateKey(b'\x01' * 32)
>>> signature = pk.sign_msg(b'a message')
>>> pk
'0x0101010101010101010101010101010101010101010101010101010101010101'
>>> pk.public_key
'0x1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1'
>>> signature
'0xccda990dba7864b79dc49158fea269338a1cf5747bc4c4bf1b96823e31a0997e7d1e65c06c5bf128b7109e1b4b9ba8d1305dc33f32f624695b2fa8e02c12c1e000'
>>> pk.public_key.to_checksum_address()
'0x1a642f0E3c3aF545E7AcBD38b07251B3990914F1'
>>> signature.verify_msg(b'a message', pk.public_key)
True
>>> signature.recover_public_key_from_msg(b'a message') == pk.public_key
True
```
## Documentation
### `KeyAPI(backend=None)`
The `KeyAPI` object is the primary API for interacting with the `ethrpc-keys`
libary. The object takes a single optional argument in its constructor which
designates what backend will be used for eliptical curve cryptography
operations. The built-in backends are:
* `ethrpc_keys.backends.NativeECCBackend`: A pure python implementation of the ECC operations.
* `ethrpc_keys.backends.CoinCurveECCBackend`: Uses the [`coincurve`](https://github.com/ofek/coincurve) library for ECC operations.
By default, `ethrpc-keys` will *try* to use the `CoinCurveECCBackend`,
falling back to the `NativeECCBackend` if the `coincurve` library is not
available.
> Note: The `coincurve` library is not automatically installed with `ethrpc-keys` and must be installed separately.
The `backend` argument can be given in any of the following forms.
* Instance of the backend class
* The backend class
* String with the dot-separated import path for the backend class.
```python
>>> from ethrpc_keys import KeyAPI
>>> from ethrpc_keys.backends import NativeECCBackend
# These are all the same
>>> keys = KeyAPI(NativeECCBackend)
>>> keys = KeyAPI(NativeECCBackend())
>>> keys = KeyAPI('ethrpc_keys.backends.NativeECCBackend')
# Or for the coincurve base backend
>>> keys = KeyAPI('ethrpc_keys.backends.CoinCurveECCBackend')
```
The backend can also be configured using the environment variable
`ECC_BACKEND_CLASS` which should be set to the dot-separated python import path
to the desired backend.
```python
>>> import os
>>> os.environ['ECC_BACKEND_CLASS'] = 'ethrpc_keys.backends.CoinCurveECCBackend'
```
### `KeyAPI.ecdsa_sign(message_hash, private_key) -> Signature`
This method returns a signature for the given `message_hash`, signed by the
provided `private_key`.
* `message_hash`: **must** be a byte string of length 32
* `private_key`: **must** be an instance of `PrivateKey`
### `KeyAPI.ecdsa_verify(message_hash, signature, public_key) -> bool`
Returns `True` or `False` based on whether the provided `signature` is a valid
signature for the provided `message_hash` and `public_key`.
* `message_hash`: **must** be a byte string of length 32
* `signature`: **must** be an instance of `Signature`
* `public_key`: **must** be an instance of `PublicKey`
### `KeyAPI.ecdsa_recover(message_hash, signature) -> PublicKey`
Returns the `PublicKey` instances recovered from the given `signature` and
`message_hash`.
* `message_hash`: **must** be a byte string of length 32
* `signature`: **must** be an instance of `Signature`
### `KeyAPI.private_key_to_public_key(private_key) -> PublicKey`
Returns the `PublicKey` instances computed from the given `private_key`
instance.
* `private_key`: **must** be an instance of `PublicKey`
### Common APIs for `PublicKey`, `PrivateKey` and `Signature`
There is a common API for the following objects.
* `PublicKey`
* `PrivateKey`
* `Signature`
Each of these objects has all of the following APIs.
* `obj.to_bytes()`: Returns the object in it's canonical `bytes` serialization.
* `obj.to_hex()`: Returns a text string of the hex encoded canonical representation.
### `KeyAPI.PublicKey(public_key_bytes)`
The `PublicKey` class takes a single argument which must be a bytes string with length 64.
> Note that there are two other common formats for public keys: 65 bytes with a leading `\x04` byte
> and 33 bytes starting with either `\x02` or `\x03`. To use the former with the `PublicKey` object,
> remove the first byte. For the latter, refer to `PublicKey.from_compressed_bytes`.
The following methods are available:
#### `PublicKey.from_compressed_bytes(compressed_bytes) -> PublicKey`
This `classmethod` returns a new `PublicKey` instance computed from its compressed representation.
* `compressed_bytes` **must** be a byte string of length 33 starting with `\x02` or `\x03`.
#### `PublicKey.from_private(private_key) -> PublicKey`
This `classmethod` returns a new `PublicKey` instance computed from the
given `private_key`.
* `private_key` may either be a byte string of length 32 or an instance of the `KeyAPI.PrivateKey` class.
#### `PublicKey.recover_from_msg(message, signature) -> PublicKey`
This `classmethod` returns a new `PublicKey` instance computed from the
provided `message` and `signature`.
* `message` **must** be a byte string
* `signature` **must** be an instance of `KeyAPI.Signature`
#### `PublicKey.recover_from_msg_hash(message_hash, signature) -> PublicKey`
Same as `PublicKey.recover_from_msg` except that `message_hash` should be the Keccak
hash of the `message`.
#### `PublicKey.verify_msg(message, signature) -> bool`
This method returns `True` or `False` based on whether the signature is a valid
for the given message.
#### `PublicKey.verify_msg_hash(message_hash, signature) -> bool`
Same as `PublicKey.verify_msg` except that `message_hash` should be the Keccak
hash of the `message`.
#### `PublicKey.to_compressed_bytes() -> bytes`
Returns the compressed representation of this public key.
#### `PublicKey.to_address() -> text`
Returns the hex encoded ethereum address for this public key.
#### `PublicKey.to_checksum_address() -> text`
Returns the ERC55 checksum formatted ethereum address for this public key.
#### `PublicKey.to_canonical_address() -> bytes`
Returns the 20-byte representation of the ethereum address for this public key.
### `KeyAPI.PrivateKey(private_key_bytes)`
The `PrivateKey` class takes a single argument which must be a bytes string with length 32.
The following methods and properties are available
#### `PrivateKey.public_key`
This *property* holds the `PublicKey` instance coresponding to this private key.
#### `PrivateKey.sign_msg(message) -> Signature`
This method returns a signature for the given `message` in the form of a
`Signature` instance
* `message` **must** be a byte string.
#### `PrivateKey.sign_msg_hash(message_hash) -> Signature`
Same as `PrivateKey.sign` except that `message_hash` should be the Keccak
hash of the `message`.
### `KeyAPI.Signature(signature_bytes=None, vrs=None)`
The `Signature` class can be instantiated in one of two ways.
* `signature_bytes`: a bytes string with length 65.
* `vrs`: a 3-tuple composed of the integers `v`, `r`, and `s`.
> Note: If using the `signature_bytes` to instantiate, the byte string should be encoded as `r_bytes | s_bytes | v_bytes` where `|` represents concatenation. `r_bytes` and `s_bytes` should be 32 bytes in length. `v_bytes` should be a single byte `\x00` or `\x01`.
Signatures are expected to use `1` or `0` for their `v` value.
The following methods and properties are available
#### `Signature.v`
This property returns the `v` value from the signature as an integer.
#### `Signature.r`
This property returns the `r` value from the signature as an integer.
#### `Signature.s`
This property returns the `s` value from the signature as an integer.
#### `Signature.vrs`
This property returns a 3-tuple of `(v, r, s)`.
#### `Signature.verify_msg(message, public_key) -> bool`
This method returns `True` or `False` based on whether the signature is a valid
for the given public key.
* `message`: **must** be a byte string.
* `public_key`: **must** be an instance of `PublicKey`
#### `Signature.verify_msg_hash(message_hash, public_key) -> bool`
Same as `Signature.verify_msg` except that `message_hash` should be the Keccak
hash of the `message`.
#### `Signature.recover_public_key_from_msg(message) -> PublicKey`
This method returns a `PublicKey` instance recovered from the signature.
* `message`: **must** be a byte string.
#### `Signature.recover_public_key_from_msg_hash(message_hash) -> PublicKey`
Same as `Signature.recover_public_key_from_msg` except that `message_hash`
should be the Keccak hash of the `message`.
### Exceptions
#### `eth_api.exceptions.ValidationError`
This error is raised during instantaition of any of the `PublicKey`,
`PrivateKey` or `Signature` classes if their constructor parameters are
invalid.
#### `eth_api.exceptions.BadSignature`
This error is raised from any of the `recover` or `verify` methods involving
signatures if the signature is invalid.
```
python3 setup.py check
python3 setup.py sdist build
twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ethereum/ethrpc-keys",
"name": "ethrpc-keys",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ethereum",
"author": "Piper Merriam",
"author_email": "pipermerriam@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/62/cb85c83495cd709d3340cc2c784a655d78aad89ae2f056f9d732f9a104ab/ethrpc_keys-0.5.7.tar.gz",
"platform": null,
"description": "# Ethereum Keys\n\n\nA common API for Ethereum key operations with pluggable backends.\n\n\n> This library and repository was previously located at https://github.com/pipermerriam/ethereum-keys. It was transferred to the Ethereum foundation github in November 2017 and renamed to `ethrpc-keys`. The PyPi package was also renamed from `ethereum-keys` to `ethrpc-keys`.\n\n## Installation\n\n```sh\npip install ethrpc-keys\n```\n\n## Development\n\n```sh\npip install -e .[dev]\n```\n\n\n### Running the tests\n\nYou can run the tests with:\n\n```sh\npy.test tests\n```\n\nOr you can install `tox` to run the full test suite.\n\n\n### Releasing\n\nPandoc is required for transforming the markdown README to the proper format to\nrender correctly on pypi.\n\nFor Debian-like systems:\n\n```\napt install pandoc\n```\n\nOr on OSX:\n\n```sh\nbrew install pandoc\n```\n\nTo release a new version:\n\n```sh\nmake release bump=$$VERSION_PART_TO_BUMP$$\n```\n\n\n#### How to bumpversion\n\nThe version format for this repo is `{major}.{minor}.{patch}` for stable, and\n`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).\n\nTo issue the next version in line, specify which part to bump,\nlike `make release bump=minor` or `make release bump=devnum`.\n\nIf you are in a beta version, `make release bump=stage` will switch to a stable.\n\nTo issue an unstable version when the current version is stable, specify the\nnew version explicitly, like `make release bump=\"--new-version 2.0.0-alpha.1 devnum\"`\n\n\n\n## QuickStart\n\n```python\n>>> from ethrpc_keys import keys\n>>> pk = keys.PrivateKey(b'\\x01' * 32)\n>>> signature = pk.sign_msg(b'a message')\n>>> pk\n'0x0101010101010101010101010101010101010101010101010101010101010101'\n>>> pk.public_key\n'0x1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1'\n>>> signature\n'0xccda990dba7864b79dc49158fea269338a1cf5747bc4c4bf1b96823e31a0997e7d1e65c06c5bf128b7109e1b4b9ba8d1305dc33f32f624695b2fa8e02c12c1e000'\n>>> pk.public_key.to_checksum_address()\n'0x1a642f0E3c3aF545E7AcBD38b07251B3990914F1'\n>>> signature.verify_msg(b'a message', pk.public_key)\nTrue\n>>> signature.recover_public_key_from_msg(b'a message') == pk.public_key\nTrue\n```\n\n\n## Documentation\n\n### `KeyAPI(backend=None)`\n\nThe `KeyAPI` object is the primary API for interacting with the `ethrpc-keys`\nlibary. The object takes a single optional argument in its constructor which\ndesignates what backend will be used for eliptical curve cryptography\noperations. The built-in backends are:\n\n* `ethrpc_keys.backends.NativeECCBackend`: A pure python implementation of the ECC operations.\n* `ethrpc_keys.backends.CoinCurveECCBackend`: Uses the [`coincurve`](https://github.com/ofek/coincurve) library for ECC operations.\n\nBy default, `ethrpc-keys` will *try* to use the `CoinCurveECCBackend`,\nfalling back to the `NativeECCBackend` if the `coincurve` library is not\navailable.\n\n> Note: The `coincurve` library is not automatically installed with `ethrpc-keys` and must be installed separately.\n\nThe `backend` argument can be given in any of the following forms.\n\n* Instance of the backend class\n* The backend class\n* String with the dot-separated import path for the backend class.\n\n```python\n>>> from ethrpc_keys import KeyAPI\n>>> from ethrpc_keys.backends import NativeECCBackend\n# These are all the same\n>>> keys = KeyAPI(NativeECCBackend)\n>>> keys = KeyAPI(NativeECCBackend())\n>>> keys = KeyAPI('ethrpc_keys.backends.NativeECCBackend')\n# Or for the coincurve base backend\n>>> keys = KeyAPI('ethrpc_keys.backends.CoinCurveECCBackend')\n```\n\nThe backend can also be configured using the environment variable\n`ECC_BACKEND_CLASS` which should be set to the dot-separated python import path\nto the desired backend.\n\n```python\n>>> import os\n>>> os.environ['ECC_BACKEND_CLASS'] = 'ethrpc_keys.backends.CoinCurveECCBackend'\n```\n\n\n### `KeyAPI.ecdsa_sign(message_hash, private_key) -> Signature`\n\nThis method returns a signature for the given `message_hash`, signed by the\nprovided `private_key`.\n\n* `message_hash`: **must** be a byte string of length 32\n* `private_key`: **must** be an instance of `PrivateKey`\n\n\n### `KeyAPI.ecdsa_verify(message_hash, signature, public_key) -> bool`\n\nReturns `True` or `False` based on whether the provided `signature` is a valid\nsignature for the provided `message_hash` and `public_key`.\n\n* `message_hash`: **must** be a byte string of length 32\n* `signature`: **must** be an instance of `Signature`\n* `public_key`: **must** be an instance of `PublicKey`\n\n\n### `KeyAPI.ecdsa_recover(message_hash, signature) -> PublicKey`\n\nReturns the `PublicKey` instances recovered from the given `signature` and\n`message_hash`.\n\n* `message_hash`: **must** be a byte string of length 32\n* `signature`: **must** be an instance of `Signature`\n\n\n### `KeyAPI.private_key_to_public_key(private_key) -> PublicKey`\n\nReturns the `PublicKey` instances computed from the given `private_key`\ninstance.\n\n* `private_key`: **must** be an instance of `PublicKey`\n\n\n### Common APIs for `PublicKey`, `PrivateKey` and `Signature`\n\nThere is a common API for the following objects.\n\n* `PublicKey`\n* `PrivateKey`\n* `Signature`\n\nEach of these objects has all of the following APIs.\n\n* `obj.to_bytes()`: Returns the object in it's canonical `bytes` serialization.\n* `obj.to_hex()`: Returns a text string of the hex encoded canonical representation.\n\n\n### `KeyAPI.PublicKey(public_key_bytes)`\n\nThe `PublicKey` class takes a single argument which must be a bytes string with length 64.\n\n> Note that there are two other common formats for public keys: 65 bytes with a leading `\\x04` byte\n> and 33 bytes starting with either `\\x02` or `\\x03`. To use the former with the `PublicKey` object,\n> remove the first byte. For the latter, refer to `PublicKey.from_compressed_bytes`.\n\nThe following methods are available:\n\n\n#### `PublicKey.from_compressed_bytes(compressed_bytes) -> PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from its compressed representation.\n\n* `compressed_bytes` **must** be a byte string of length 33 starting with `\\x02` or `\\x03`.\n\n\n#### `PublicKey.from_private(private_key) -> PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from the\ngiven `private_key`. \n\n* `private_key` may either be a byte string of length 32 or an instance of the `KeyAPI.PrivateKey` class.\n\n\n#### `PublicKey.recover_from_msg(message, signature) -> PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from the\nprovided `message` and `signature`.\n\n* `message` **must** be a byte string\n* `signature` **must** be an instance of `KeyAPI.Signature`\n\n\n#### `PublicKey.recover_from_msg_hash(message_hash, signature) -> PublicKey`\n\nSame as `PublicKey.recover_from_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n\n#### `PublicKey.verify_msg(message, signature) -> bool`\n\nThis method returns `True` or `False` based on whether the signature is a valid\nfor the given message.\n\n\n#### `PublicKey.verify_msg_hash(message_hash, signature) -> bool`\n\nSame as `PublicKey.verify_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n\n#### `PublicKey.to_compressed_bytes() -> bytes`\n\nReturns the compressed representation of this public key.\n\n\n#### `PublicKey.to_address() -> text`\n\nReturns the hex encoded ethereum address for this public key.\n\n\n#### `PublicKey.to_checksum_address() -> text`\n\nReturns the ERC55 checksum formatted ethereum address for this public key.\n\n\n#### `PublicKey.to_canonical_address() -> bytes`\n\nReturns the 20-byte representation of the ethereum address for this public key.\n\n\n### `KeyAPI.PrivateKey(private_key_bytes)`\n\nThe `PrivateKey` class takes a single argument which must be a bytes string with length 32.\n\nThe following methods and properties are available\n\n\n#### `PrivateKey.public_key`\n\nThis *property* holds the `PublicKey` instance coresponding to this private key.\n\n\n#### `PrivateKey.sign_msg(message) -> Signature`\n\nThis method returns a signature for the given `message` in the form of a\n`Signature` instance\n\n* `message` **must** be a byte string.\n\n\n#### `PrivateKey.sign_msg_hash(message_hash) -> Signature`\n\nSame as `PrivateKey.sign` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n\n### `KeyAPI.Signature(signature_bytes=None, vrs=None)`\n\nThe `Signature` class can be instantiated in one of two ways.\n\n* `signature_bytes`: a bytes string with length 65.\n* `vrs`: a 3-tuple composed of the integers `v`, `r`, and `s`.\n\n> Note: If using the `signature_bytes` to instantiate, the byte string should be encoded as `r_bytes | s_bytes | v_bytes` where `|` represents concatenation. `r_bytes` and `s_bytes` should be 32 bytes in length. `v_bytes` should be a single byte `\\x00` or `\\x01`.\n\nSignatures are expected to use `1` or `0` for their `v` value.\n\nThe following methods and properties are available\n\n\n#### `Signature.v`\n\nThis property returns the `v` value from the signature as an integer.\n\n\n#### `Signature.r`\n\nThis property returns the `r` value from the signature as an integer.\n\n\n#### `Signature.s`\n\nThis property returns the `s` value from the signature as an integer.\n\n\n#### `Signature.vrs`\n\nThis property returns a 3-tuple of `(v, r, s)`.\n\n\n#### `Signature.verify_msg(message, public_key) -> bool`\n\nThis method returns `True` or `False` based on whether the signature is a valid\nfor the given public key.\n\n* `message`: **must** be a byte string.\n* `public_key`: **must** be an instance of `PublicKey`\n\n\n#### `Signature.verify_msg_hash(message_hash, public_key) -> bool`\n\nSame as `Signature.verify_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n\n#### `Signature.recover_public_key_from_msg(message) -> PublicKey`\n\nThis method returns a `PublicKey` instance recovered from the signature.\n\n* `message`: **must** be a byte string.\n\n\n#### `Signature.recover_public_key_from_msg_hash(message_hash) -> PublicKey`\n\nSame as `Signature.recover_public_key_from_msg` except that `message_hash`\nshould be the Keccak hash of the `message`.\n\n\n### Exceptions\n\n#### `eth_api.exceptions.ValidationError`\n\nThis error is raised during instantaition of any of the `PublicKey`,\n`PrivateKey` or `Signature` classes if their constructor parameters are\ninvalid.\n\n\n#### `eth_api.exceptions.BadSignature`\n\nThis error is raised from any of the `recover` or `verify` methods involving\nsignatures if the signature is invalid.\n\n```\npython3 setup.py check\npython3 setup.py sdist build\ntwine upload dist/*\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Common API for Ethereum key operations.",
"version": "0.5.7",
"project_urls": {
"Homepage": "https://github.com/ethereum/ethrpc-keys"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c062cb85c83495cd709d3340cc2c784a655d78aad89ae2f056f9d732f9a104ab",
"md5": "9e219657a488fde2baf7659fbe00355c",
"sha256": "ac5241dda1980d81d2e115a2ea3389d95c70eba2e85fcbbdfdaa6666dffb4e9f"
},
"downloads": -1,
"filename": "ethrpc_keys-0.5.7.tar.gz",
"has_sig": false,
"md5_digest": "9e219657a488fde2baf7659fbe00355c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21103,
"upload_time": "2024-10-25T08:44:14",
"upload_time_iso_8601": "2024-10-25T08:44:14.261284Z",
"url": "https://files.pythonhosted.org/packages/c0/62/cb85c83495cd709d3340cc2c784a655d78aad89ae2f056f9d732f9a104ab/ethrpc_keys-0.5.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 08:44:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ethereum",
"github_project": "ethrpc-keys",
"github_not_found": true,
"lcname": "ethrpc-keys"
}
JSON
