# elliptic-curve cryptography
[](https://github.com/aldenml/ecc/actions/workflows/macos.yml)
[](https://github.com/aldenml/ecc/actions/workflows/linux.yml)
[](https://github.com/aldenml/ecc/actions/workflows/windows.yml)
[](https://badge.fury.io/py/libecc)
This is the python binding of the [ecc](https://github.com/aldenml/ecc) library.
### Features
- [OPRF](#oprf-oblivious-pseudo-random-functions)
- [OPAQUE](#opaque-the-opaque-asymmetric-pake-protocol)
- [Two-Round Threshold Schnorr Signatures with FROST](#two-round-threshold-schnorr-signatures-with-frost)
- [Ethereum BLS Signature](#ethereum-bls-signature)
- [BLS12-381 Pairing](#bls12-381-pairing)
- [Proxy Re-Encryption (PRE)](#proxy-re-encryption-pre)
- [Cryptographic primitives and utilities](#cryptographic-primitives-and-utilities)
### OPRF Oblivious pseudo-random functions
This is an implementation of [draft-irtf-cfrg-voprf-21](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-voprf-21)
ciphersuite **OPRF(ristretto255, SHA-512)** using `libsodium`.
An Oblivious Pseudorandom Function (OPRF) is a two-party protocol between client
and server for computing the output of a Pseudorandom Function (PRF). The server
provides the PRF secret key, and the client provides the PRF input. At the end
of the protocol, the client learns the PRF output without learning anything
about the PRF secret key, and the server learns neither the PRF input nor
output.
There are two variations of the basic protocol:
- VOPRF: is OPRF with the notion of verifiability. Clients can verify that the
server used a specific private key during the execution of the protocol.
- POPRF: is a partially-oblivious VOPRF that allows clients and servers to
provide public input to the PRF computation.
The OPRF flow is shown below (from the IRTF draft):
```
Client(input) Server(skS)
-------------------------------------------------------------------
blind, blindedElement = Blind(input)
blindedElement
---------->
evaluatedElement = BlindEvaluate(skS, blindedElement)
evaluatedElement
<----------
output = Finalize(input, blind, evaluatedElement)
```
For the advanced modes VOPRF and POPRF refer to the published draft.
### OPAQUE The OPAQUE Asymmetric PAKE Protocol
This is an implementation of [draft-irtf-cfrg-opaque-12](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-opaque-12)
using `libsodium`.
OPAQUE consists of two stages: registration and authenticated key
exchange. In the first stage, a client registers its password with
the server and stores its encrypted credentials on the server, but
the server never knows what the password it.
The registration flow is shown below (from the irtf draft):
```
creds parameters
| |
v v
Client Server
------------------------------------------------
registration request
------------------------->
registration response
<-------------------------
record
------------------------->
------------------------------------------------
| |
v v
export_key record
```
In the second stage, the client outputs two values, an "export_key" (matching
that from registration) and a "session_key". The server outputs a single value
"session_key" that matches that of the client.
The authenticated key exchange flow is shown below (from the irtf draft):
```
creds (parameters, record)
| |
v v
Client Server
------------------------------------------------
AKE message 1
------------------------->
AKE message 2
<-------------------------
AKE message 3
------------------------->
------------------------------------------------
| |
v v
(export_key, session_key) session_key
```
The public API for implementing the protocol is:
- Client
```
opaque_ristretto255_sha512_CreateRegistrationRequest
opaque_ristretto255_sha512_FinalizeRequest
opaque_ristretto255_sha512_3DH_ClientInit
opaque_ristretto255_sha512_3DH_ClientFinish
```
- Server
```
opaque_ristretto255_sha512_CreateRegistrationResponse
opaque_ristretto255_sha512_3DH_ServerInit
opaque_ristretto255_sha512_3DH_ServerFinish
```
### Two-Round Threshold Schnorr Signatures with FROST
This is an implementation of [draft-irtf-cfrg-frost-13](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-frost-13)
using `libsodium`.
The draft presents a two-round signing variant of FROST, a Flexible Round-Optimized Schnorr Threshold signature
scheme. FROST signatures can be issued after a threshold number of entities cooperate to issue a signature,
allowing for improved distribution of trust and redundancy with respect to a secret key.
Unlike signatures in a single-party setting, threshold signatures require cooperation among a threshold number
of signers each holding a share of a common private key. The security of threshold schemes in general assume
that an adversary can corrupt strictly fewer than a threshold number of participants.
This implementation follows the trusted dealer key generation documented in the Appendix B of the draft
using Shamir and Verifiable Secret Sharing.
### Ethereum BLS Signature
Ethereum uses BLS signatures as specified in the IETF
draft [draft-irtf-cfrg-bls-signature-05](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05)
ciphersuite `BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_`. This library provides the following API:
```
ecc_sign_eth_bls_KeyGen
ecc_sign_eth_bls_SkToPk
ecc_sign_eth_bls_KeyValidate
ecc_sign_eth_bls_Sign
ecc_sign_eth_bls_Verify
ecc_sign_eth_bls_Aggregate
ecc_sign_eth_bls_FastAggregateVerify
ecc_sign_eth_bls_AggregateVerify
```
BLS is a digital signature scheme with aggregation properties that can be applied to signatures
and public keys. For this reason, in the context of blockchains, BLS signatures are used for
authenticating transactions, votes during the consensus protocol, and to reduce the bandwidth
and storage requirements.
### BLS12-381 Pairing
In the context of pairing friendly elliptic curves, a pairing is a map `e: G1xG2 -> GT` such
that for each a, b, P and Q
```
e(a * P, b * Q) = e(P, Q)^(a * b)
```
You can use this to obtain such pairings:
```js
const libecc = await libecc_module();
const a = new Uint8Array(32);
const b = new Uint8Array(32);
libecc.ecc_bls12_381_scalar_random(a);
libecc.ecc_bls12_381_scalar_random(b);
const aP = new Uint8Array(96);
const bQ = new Uint8Array(192);
libecc.ecc_bls12_381_g1_scalarmult_base(aP, a); // a * P
libecc.ecc_bls12_381_g2_scalarmult_base(bQ, b); // b * Q
const pairing = new Uint8Array(576);
libecc.ecc_bls12_381_pairing(pairing, aP, bQ); // e(a * P, b * Q)
```
Read more at:<br/>
https://hackmd.io/@benjaminion/bls12-381 <br/>
https://en.wikipedia.org/wiki/Pairing-based_cryptography
### Proxy Re-Encryption (PRE)
With a pairing-friendly elliptic curve and a well-defined pairing operation,
you can implement a proxy re-encryption scheme. This library provides an
implementation using BLS12-381.
Example of how to use it:
```js
// client A setup public/private keys and signing keys
const keysA = await pre_schema1_KeyGen();
const signingA = await pre_schema1_SigningKeyGen();
// client B setup public/private keys (signing keys are not used here)
const keysB = await pre_schema1_KeyGen();
// proxy server setup signing keys
const signingProxy = await pre_schema1_SigningKeyGen();
// client A select a plaintext message, this message
// in itself is random, but can be used as a seed
// for symmetric encryption keys
const message = await pre_schema1_MessageGen();
// client A encrypts the message to itself, making it
// possible to send this ciphertext to the proxy.
const ciphertextLevel1 = await pre_schema1_Encrypt(message, keysA.pk, signingA);
// client A sends ciphertextLevel1 to the proxy server and
// eventually client A allows client B to see the encrypted
// message, in this case the proxy needs to re-encrypt
// ciphertextLevel1 (without ever knowing the plaintext).
// In order to do that, the client A needs to create a re-encryption
// key that the proxy can use to perform such operation.
// client A creates a re-encryption key that the proxy can use
// to re-encrypt the ciphertext (ciphertextLevel1) in order for
// client B be able to recover the original message
const reEncKey = await pre_schema1_ReKeyGen(keysA.sk, keysB.pk, signingA);
// the proxy re-encrypt the ciphertext ciphertextLevel1 with such
// a key that allows client B to recover the original message
const ciphertextLevel2 = await pre_schema1_ReEncrypt(
ciphertextLevel1,
reEncKey,
signingA.spk, keysB.pk,
signingProxy
);
// client B is able to decrypt ciphertextLevel2 and the result
// is the original plaintext message
const messageDecrypted = await pre_schema1_DecryptLevel2(
ciphertextLevel2,
keysB.sk, signingProxy.spk
);
// now both client A and client B share the same plaintext message
// messageDecrypted is equal to message
```
Read more at:<br/>
"A Fully Secure Unidirectional and Multi-user Proxy Re-encryption Scheme" by H. Wang and Z. Cao, 2009 <br/>
"A Multi-User CCA-Secure Proxy Re-Encryption Scheme" by Y. Cai and X. Liu, 2014 <br/>
"Cryptographically Enforced Orthogonal Access Control at Scale" by B. Wall and P. Walsh, 2018 <br/>
https://en.wikipedia.org/wiki/Proxy_re-encryption
### Cryptographic primitives and utilities
```
ecc_hash_sha256
ecc_hash_sha512
ecc_kdf_scrypt
ecc_kdf_argon2id
ecc_aead_chacha20poly1305_encrypt
ecc_aead_chacha20poly1305_decrypt
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aldenml/ecc",
"name": "libecc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "elliptic-curves,crypto,hash,sha256,sha512,ed25519,ristretto255,bls12-381,oprf,opaque,pake,apake,authentication,bls-signature,proxy-re-encryption,hkdf,threshold-cryptography,threshold-signature",
"author": "Alden Torres",
"author_email": "aldenml@gmail.com",
"download_url": "",
"platform": null,
"description": "# elliptic-curve cryptography\n\n[](https://github.com/aldenml/ecc/actions/workflows/macos.yml)\n[](https://github.com/aldenml/ecc/actions/workflows/linux.yml)\n[](https://github.com/aldenml/ecc/actions/workflows/windows.yml)\n[](https://badge.fury.io/py/libecc)\n\nThis is the python binding of the [ecc](https://github.com/aldenml/ecc) library.\n\n### Features\n\n- [OPRF](#oprf-oblivious-pseudo-random-functions)\n- [OPAQUE](#opaque-the-opaque-asymmetric-pake-protocol)\n- [Two-Round Threshold Schnorr Signatures with FROST](#two-round-threshold-schnorr-signatures-with-frost)\n- [Ethereum BLS Signature](#ethereum-bls-signature)\n- [BLS12-381 Pairing](#bls12-381-pairing)\n- [Proxy Re-Encryption (PRE)](#proxy-re-encryption-pre)\n- [Cryptographic primitives and utilities](#cryptographic-primitives-and-utilities)\n\n### OPRF Oblivious pseudo-random functions\n\nThis is an implementation of [draft-irtf-cfrg-voprf-21](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-voprf-21)\nciphersuite **OPRF(ristretto255, SHA-512)** using `libsodium`.\n\nAn Oblivious Pseudorandom Function (OPRF) is a two-party protocol between client\nand server for computing the output of a Pseudorandom Function (PRF). The server\nprovides the PRF secret key, and the client provides the PRF input. At the end\nof the protocol, the client learns the PRF output without learning anything\nabout the PRF secret key, and the server learns neither the PRF input nor\noutput.\n\nThere are two variations of the basic protocol:\n\n- VOPRF: is OPRF with the notion of verifiability. Clients can verify that the\n server used a specific private key during the execution of the protocol.\n- POPRF: is a partially-oblivious VOPRF that allows clients and servers to\n provide public input to the PRF computation.\n\nThe OPRF flow is shown below (from the IRTF draft):\n```\n Client(input) Server(skS)\n -------------------------------------------------------------------\n blind, blindedElement = Blind(input)\n\n blindedElement\n ---------->\n\n evaluatedElement = BlindEvaluate(skS, blindedElement)\n\n evaluatedElement\n <----------\n\n output = Finalize(input, blind, evaluatedElement)\n```\n\nFor the advanced modes VOPRF and POPRF refer to the published draft.\n\n### OPAQUE The OPAQUE Asymmetric PAKE Protocol\n\nThis is an implementation of [draft-irtf-cfrg-opaque-12](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-opaque-12)\nusing `libsodium`.\n\nOPAQUE consists of two stages: registration and authenticated key\nexchange. In the first stage, a client registers its password with\nthe server and stores its encrypted credentials on the server, but\nthe server never knows what the password it.\n\nThe registration flow is shown below (from the irtf draft):\n```\n creds parameters\n | |\n v v\n Client Server\n ------------------------------------------------\n registration request\n ------------------------->\n registration response\n <-------------------------\n record\n ------------------------->\n ------------------------------------------------\n | |\n v v\n export_key record\n```\n\nIn the second stage, the client outputs two values, an \"export_key\" (matching\nthat from registration) and a \"session_key\". The server outputs a single value\n\"session_key\" that matches that of the client.\n\nThe authenticated key exchange flow is shown below (from the irtf draft):\n```\n creds (parameters, record)\n | |\n v v\n Client Server\n ------------------------------------------------\n AKE message 1\n ------------------------->\n AKE message 2\n <-------------------------\n AKE message 3\n ------------------------->\n ------------------------------------------------\n | |\n v v\n (export_key, session_key) session_key\n```\n\nThe public API for implementing the protocol is:\n\n- Client\n```\nopaque_ristretto255_sha512_CreateRegistrationRequest\nopaque_ristretto255_sha512_FinalizeRequest\nopaque_ristretto255_sha512_3DH_ClientInit\nopaque_ristretto255_sha512_3DH_ClientFinish\n```\n\n- Server\n```\nopaque_ristretto255_sha512_CreateRegistrationResponse\nopaque_ristretto255_sha512_3DH_ServerInit\nopaque_ristretto255_sha512_3DH_ServerFinish\n```\n\n### Two-Round Threshold Schnorr Signatures with FROST\n\nThis is an implementation of [draft-irtf-cfrg-frost-13](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-frost-13)\nusing `libsodium`.\n\nThe draft presents a two-round signing variant of FROST, a Flexible Round-Optimized Schnorr Threshold signature\nscheme. FROST signatures can be issued after a threshold number of entities cooperate to issue a signature,\nallowing for improved distribution of trust and redundancy with respect to a secret key.\n\nUnlike signatures in a single-party setting, threshold signatures require cooperation among a threshold number\nof signers each holding a share of a common private key. The security of threshold schemes in general assume\nthat an adversary can corrupt strictly fewer than a threshold number of participants.\n\nThis implementation follows the trusted dealer key generation documented in the Appendix B of the draft\nusing Shamir and Verifiable Secret Sharing.\n\n### Ethereum BLS Signature\n\nEthereum uses BLS signatures as specified in the IETF\ndraft [draft-irtf-cfrg-bls-signature-05](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05)\nciphersuite `BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_`. This library provides the following API:\n\n```\necc_sign_eth_bls_KeyGen\necc_sign_eth_bls_SkToPk\necc_sign_eth_bls_KeyValidate\necc_sign_eth_bls_Sign\necc_sign_eth_bls_Verify\necc_sign_eth_bls_Aggregate\necc_sign_eth_bls_FastAggregateVerify\necc_sign_eth_bls_AggregateVerify\n```\n\nBLS is a digital signature scheme with aggregation properties that can be applied to signatures\nand public keys. For this reason, in the context of blockchains, BLS signatures are used for\nauthenticating transactions, votes during the consensus protocol, and to reduce the bandwidth\nand storage requirements.\n\n### BLS12-381 Pairing\n\nIn the context of pairing friendly elliptic curves, a pairing is a map `e: G1xG2 -> GT` such\nthat for each a, b, P and Q\n```\ne(a * P, b * Q) = e(P, Q)^(a * b)\n```\nYou can use this to obtain such pairings:\n```js\nconst libecc = await libecc_module();\n\nconst a = new Uint8Array(32);\nconst b = new Uint8Array(32);\nlibecc.ecc_bls12_381_scalar_random(a);\nlibecc.ecc_bls12_381_scalar_random(b);\n\nconst aP = new Uint8Array(96);\nconst bQ = new Uint8Array(192);\n\nlibecc.ecc_bls12_381_g1_scalarmult_base(aP, a); // a * P\nlibecc.ecc_bls12_381_g2_scalarmult_base(bQ, b); // b * Q\n\nconst pairing = new Uint8Array(576);\nlibecc.ecc_bls12_381_pairing(pairing, aP, bQ); // e(a * P, b * Q)\n```\n\nRead more at:<br/>\nhttps://hackmd.io/@benjaminion/bls12-381 <br/>\nhttps://en.wikipedia.org/wiki/Pairing-based_cryptography\n\n### Proxy Re-Encryption (PRE)\n\nWith a pairing-friendly elliptic curve and a well-defined pairing operation,\nyou can implement a proxy re-encryption scheme. This library provides an\nimplementation using BLS12-381.\n\nExample of how to use it:\n```js\n// client A setup public/private keys and signing keys\nconst keysA = await pre_schema1_KeyGen();\nconst signingA = await pre_schema1_SigningKeyGen();\n\n// client B setup public/private keys (signing keys are not used here)\nconst keysB = await pre_schema1_KeyGen();\n\n// proxy server setup signing keys\nconst signingProxy = await pre_schema1_SigningKeyGen();\n\n// client A select a plaintext message, this message\n// in itself is random, but can be used as a seed\n// for symmetric encryption keys\nconst message = await pre_schema1_MessageGen();\n\n// client A encrypts the message to itself, making it\n// possible to send this ciphertext to the proxy.\nconst ciphertextLevel1 = await pre_schema1_Encrypt(message, keysA.pk, signingA);\n\n// client A sends ciphertextLevel1 to the proxy server and\n// eventually client A allows client B to see the encrypted\n// message, in this case the proxy needs to re-encrypt\n// ciphertextLevel1 (without ever knowing the plaintext).\n// In order to do that, the client A needs to create a re-encryption\n// key that the proxy can use to perform such operation.\n\n// client A creates a re-encryption key that the proxy can use\n// to re-encrypt the ciphertext (ciphertextLevel1) in order for\n// client B be able to recover the original message\nconst reEncKey = await pre_schema1_ReKeyGen(keysA.sk, keysB.pk, signingA);\n\n// the proxy re-encrypt the ciphertext ciphertextLevel1 with such\n// a key that allows client B to recover the original message\nconst ciphertextLevel2 = await pre_schema1_ReEncrypt(\n ciphertextLevel1,\n reEncKey,\n signingA.spk, keysB.pk,\n signingProxy\n);\n\n// client B is able to decrypt ciphertextLevel2 and the result\n// is the original plaintext message\nconst messageDecrypted = await pre_schema1_DecryptLevel2(\n ciphertextLevel2,\n keysB.sk, signingProxy.spk\n);\n\n// now both client A and client B share the same plaintext message\n// messageDecrypted is equal to message\n```\n\nRead more at:<br/>\n\"A Fully Secure Unidirectional and Multi-user Proxy Re-encryption Scheme\" by H. Wang and Z. Cao, 2009 <br/>\n\"A Multi-User CCA-Secure Proxy Re-Encryption Scheme\" by Y. Cai and X. Liu, 2014 <br/>\n\"Cryptographically Enforced Orthogonal Access Control at Scale\" by B. Wall and P. Walsh, 2018 <br/>\nhttps://en.wikipedia.org/wiki/Proxy_re-encryption\n\n### Cryptographic primitives and utilities\n\n```\necc_hash_sha256\necc_hash_sha512\n\necc_kdf_scrypt\necc_kdf_argon2id\n\necc_aead_chacha20poly1305_encrypt\necc_aead_chacha20poly1305_decrypt\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "elliptic curves crypto functions",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/aldenml/ecc/issues",
"Homepage": "https://github.com/aldenml/ecc"
},
"split_keywords": [
"elliptic-curves",
"crypto",
"hash",
"sha256",
"sha512",
"ed25519",
"ristretto255",
"bls12-381",
"oprf",
"opaque",
"pake",
"apake",
"authentication",
"bls-signature",
"proxy-re-encryption",
"hkdf",
"threshold-cryptography",
"threshold-signature"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8bdcfc909160f4f7161ce4fb7d2709cbfbd02c0b1e881b4561cc32b0949781a",
"md5": "60a6dbce08baf8c5197d0194871f8693",
"sha256": "9368a3cd3e5b7fe7398d8a854794a6ecba838bb04880d2348886b3132af474c5"
},
"downloads": -1,
"filename": "libecc-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60a6dbce08baf8c5197d0194871f8693",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 1380161,
"upload_time": "2023-10-08T21:59:43",
"upload_time_iso_8601": "2023-10-08T21:59:43.152486Z",
"url": "https://files.pythonhosted.org/packages/f8/bd/cfc909160f4f7161ce4fb7d2709cbfbd02c0b1e881b4561cc32b0949781a/libecc-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-08 21:59:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aldenml",
"github_project": "ecc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "libecc"
}
JSON
