Skip to content

Commit

Permalink
Update README.md (#126)
Browse files Browse the repository at this point in the history
* Update README.md

* Update README.md

* Update README.md
  • Loading branch information
kigawas authored Dec 13, 2019
1 parent a88862c commit b03c8d3
Showing 1 changed file with 35 additions and 39 deletions.
74 changes: 35 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ Elliptic Curve Integrated Encryption Scheme for secp256k1 in Python.

Other language versions:

- [TypeScript](https://github.com/ecies/js)
- [Rust](https://github.com/ecies/rs)
- [Golang](https://github.com/ecies/go)
- [TypeScript](https://github.com/ecies/js)
- [Rust](https://github.com/ecies/rs)
- [Golang](https://github.com/ecies/go)

You can also check a flask web backend demo [here](https://github.com/kigawas/eciespy-demo).

Expand Down Expand Up @@ -47,19 +47,19 @@ Or just use a builtin command `eciespy` in your favorite [command line](#command

Parameters:

- **receiver_pk** - Receiver's public key (hex str or bytes)
- **msg** - Data to encrypt
- **receiver_pk** - Receiver's public key (hex str or bytes)
- **msg** - Data to encrypt

Returns: **bytes**
Returns: **bytes**

### `ecies.decrypt(receiver_sk: Union[str, bytes], msg: bytes) -> bytes`

Parameters:

- **receiver_sk** - Receiver's private key (hex str or bytes)
- **msg** - Data to decrypt
- **receiver_sk** - Receiver's private key (hex str or bytes)
- **msg** - Data to decrypt

Returns: **bytes**
Returns: **bytes**

## Command Line Interface

Expand Down Expand Up @@ -96,27 +96,27 @@ Address: 0x47e801184B3a8ea8E6A4A7A4CFEfEcC76809Da72

### Encrypt with public key and decrypt with private key

```console
$ echo '0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d' > prv
$ echo '0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b' > pub
```bash
echo '0x95d3c5e483e9b1d4f5fc8e79b2deaf51362980de62dbb082a9a4257eef653d7d' > prv
echo '0x98afe4f150642cd05cc9d2fa36458ce0a58567daeaf5fde7333ba9b403011140a4e28911fcf83ab1f457a30b4959efc4b9306f514a4c3711a16a80e3b47eb58b' > pub
$ echo 'helloworld' | eciespy -e -k pub | eciespy -d -k prv
helloworld
$ echo 'data to encrypt' > data
$ eciespy -e -k pub -D data -O enc_data
echo 'data to encrypt' > data
eciespy -e -k pub -D data -O enc_data
$ eciespy -d -k prv -D enc_data
data to encrypt
$ rm prv pub data enc_data
rm prv pub data enc_data
```

## Mechanism and implementation details

This library combines `secp256k1` and `AES-256-GCM` (powered by [`coincurve`](https://github.com/ofek/coincurve) and [`pycryptodome`](https://github.com/Legrandin/pycryptodome)) to provide an API of encrypting with `secp256k1` public key and decrypting with `secp256k1`'s private key. It has two parts generally:

1. Use [ECDH](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie–Hellman) to exchange an AES session key;
1. Use [ECDH](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie–Hellman) to exchange an AES session key;

> Notice that the sender public key is generated every time when `ecies.encrypt` is invoked, thus, the AES session key varies.
2. Use this AES session key to encrypt/decrypt the data under `AES-256-GCM`.
2. Use this AES session key to encrypt/decrypt the data under `AES-256-GCM`.

Basically the encrypted data will be like this:

Expand Down Expand Up @@ -188,7 +188,7 @@ Mathematically, the elliptic curve cryptography is based on the fact that you ca

A point multiplying a scalar can be regarded that this point adds itself multiple times, and the point `B` can be converted to a readable public key in a compressed or uncompressed format.

- Compressed format (`x` coordinate only)
- Compressed format (`x` coordinate only)

```python
>>> point = (89565891926547004231252920425935692360644145829622209833684329913297188986597, 12158399299693830322967808612713398636155367887041628176798871954788371653930)
Expand All @@ -201,7 +201,7 @@ True
'02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5'
```

- Uncompressed format (`(x, y)` coordinate)
- Uncompressed format (`(x, y)` coordinate)

```python
>>> uncompressed_key_hex = '04' + hex(point[0])[2:] + hex(point[1])[2:]
Expand All @@ -216,16 +216,16 @@ The format is depicted by the image below from the [bitcoin book](https://github

> If you want to convert the compressed format to uncompressed, basically, you need to calculate `y` from `x` by solving the equation using [Cipolla's Algorithm](https://en.wikipedia.org/wiki/Cipolla's_algorithm):
>
> ![y^2=(x^3 + 7) mod p, where p=2^{256}-2^{32}-2^{9}-2^{8}-2^{7}-2^{6}-2^{4}-1](https://tex.s2cms.ru/svg/%20y%5E2%3D(x%5E3%20%2B%207)%20%5Cbmod%20p%2C%5C%20where%5C%20p%3D2%5E%7B256%7D-2%5E%7B32%7D-2%5E%7B9%7D-2%5E%7B8%7D-2%5E%7B7%7D-2%5E%7B6%7D-2%5E%7B4%7D-1%20)
> ![y^2=(x^3 + 7) mod p, where p=2^{256}-2^{32}-2^{9}-2^{8}-2^{7}-2^{6}-2^{4}-1](<https://tex.s2cms.ru/svg/%20y%5E2%3D(x%5E3%20%2B%207)%20%5Cbmod%20p%2C%5C%20where%5C%20p%3D2%5E%7B256%7D-2%5E%7B32%7D-2%5E%7B9%7D-2%5E%7B8%7D-2%5E%7B7%7D-2%5E%7B6%7D-2%5E%7B4%7D-1%20>)
>
> You can check the [bitcoin wiki](https://en.bitcoin.it/wiki/Secp256k1) and this thread on [bitcointalk.org](https://bitcointalk.org/index.php?topic=644919.msg7205689#msg7205689) for more details.
Then, the shared key between `k1` and `k2` is the `sha256` hash of the **compressed** ECDH public key. It's better to use the compressed format, since you can always get `x` from `x` or `(x, y)` without any calculation.

You may want to ask, what if we don't hash it? Briefly, hash can:

1. Make the shared key's length fixed;
2. Make it safer since hash functions can remove "weak bits" in the original computed key. Check the introduction section of this [paper](http://cacr.uwaterloo.ca/techreports/1998/corr98-05.pdf) for more details.
1. Make the shared key's length fixed;
2. Make it safer since hash functions can remove "weak bits" in the original computed key. Check the introduction section of this [paper](http://cacr.uwaterloo.ca/techreports/1998/corr98-05.pdf) for more details.

> Warning: According to some recent research, although widely used, the `sha256` key derivation function is [not secure enough](https://github.com/ecies/py/issues/82).
Expand All @@ -248,33 +248,29 @@ b'helloworld'
## Release Notes

### 0.3.2

- Fix CLI

### 0.3.1
### 0.3.1 ~ 0.3.3

- Support Python 3.8
- Bump dependencies
- Update documentation
- Support Python 3.8
- Bump dependencies
- Update documentation

### 0.3.0

- API change: use `HKDF-sha256` to derive shared keys instead of `sha256`
- API change: use `HKDF-sha256` to derive shared keys instead of `sha256`

### 0.2.0

- API change: `ecies.encrypt` and `ecies.decrypt` now can take both hex str and raw bytes
- Bump dependency versions
- Update documentation
- API change: `ecies.encrypt` and `ecies.decrypt` now can take both hex str and raw bytes
- Bump dependency versions
- Update documentation

### 0.1.1 ~ 0.1.9

- Bump dependency versions
- Update documentation
- Switch to Circle CI
- Change license to MIT
- Bump dependency versions
- Update documentation
- Switch to Circle CI
- Change license to MIT

### 0.1.0

- First beta version release
- First beta version release

0 comments on commit b03c8d3

Please sign in to comment.