ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-11-04 11:15:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: Reverts formatting changes to external files, adds formatting changes to proto files (#5711)

Browse Source 
This change reverts the formatting applied to external files and adds formatting of proto files.

As clang-format will complain if a proto file is modified or moved, since the .clang-format file does not explicitly contain a section for proto files, the change has been included in this PR as well.
This commit is contained in:
Bart
2025-08-21 15:22:25 -04:00
committed by GitHub
parent f847e3287c
commit b13370ac0d
21 changed files with 5056 additions and 5181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.clang-format
View File

@@ -100,3 +100,8 @@ Language: JavaScript
--- ---
Language: Json Language: Json
IndentWidth: 2 IndentWidth: 2
---
Language: Proto
BasedOnStyle: Google
ColumnLimit: 0
IndentWidth: 2

2
external/antithesis-sdk/.clang-format → external/.clang-format vendored
View File

@@ -1,3 +1,3 @@
--- ---
DisableFormat: true DisableFormat: true
SortIncludes: false SortIncludes: Never

97
external/ed25519-donna/README.md vendored
View File

@@ -1,12 +1,12 @@
[ed25519](http://ed25519.cr.yp.to/) is an [ed25519](http://ed25519.cr.yp.to/) is an
[Elliptic Curve Digital Signature Algortithm](http://en.wikipedia.org/wiki/Elliptic_Curve_DSA), [Elliptic Curve Digital Signature Algortithm](http://en.wikipedia.org/wiki/Elliptic_Curve_DSA),
developed by [Dan Bernstein](http://cr.yp.to/djb.html), developed by [Dan Bernstein](http://cr.yp.to/djb.html),
[Niels Duif](http://www.nielsduif.nl/), [Niels Duif](http://www.nielsduif.nl/),
[Tanja Lange](http://hyperelliptic.org/tanja), [Tanja Lange](http://hyperelliptic.org/tanja),
[Peter Schwabe](http://www.cryptojedi.org/users/peter/), [Peter Schwabe](http://www.cryptojedi.org/users/peter/),
and [Bo-Yin Yang](http://www.iis.sinica.edu.tw/pages/byyang/). and [Bo-Yin Yang](http://www.iis.sinica.edu.tw/pages/byyang/).
This project provides performant, portable 32-bit & 64-bit implementations. All implementations are This project provides performant, portable 32-bit & 64-bit implementations. All implementations are
of course constant time in regard to secret data. of course constant time in regard to secret data.
#### Performance #### Performance
@@ -52,35 +52,35 @@ are made.
#### Compilation #### Compilation
No configuration is needed **if you are compiling against OpenSSL**. No configuration is needed **if you are compiling against OpenSSL**.
##### Hash Options ##### Hash Options
If you are not compiling aginst OpenSSL, you will need a hash function. If you are not compiling aginst OpenSSL, you will need a hash function.
To use a simple/**slow** implementation of SHA-512, use `-DED25519_REFHASH` when compiling `ed25519.c`. To use a simple/**slow** implementation of SHA-512, use `-DED25519_REFHASH` when compiling `ed25519.c`.
This should never be used except to verify the code works when OpenSSL is not available. This should never be used except to verify the code works when OpenSSL is not available.
To use a custom hash function, use `-DED25519_CUSTOMHASH` when compiling `ed25519.c` and put your To use a custom hash function, use `-DED25519_CUSTOMHASH` when compiling `ed25519.c` and put your
custom hash implementation in ed25519-hash-custom.h. The hash must have a 512bit digest and implement custom hash implementation in ed25519-hash-custom.h. The hash must have a 512bit digest and implement
struct ed25519_hash_context; struct ed25519_hash_context;
void ed25519_hash_init(ed25519_hash_context *ctx); void ed25519_hash_init(ed25519_hash_context *ctx);
void ed25519_hash_update(ed25519_hash_context *ctx, const uint8_t *in, size_t inlen); void ed25519_hash_update(ed25519_hash_context *ctx, const uint8_t *in, size_t inlen);
void ed25519_hash_final(ed25519_hash_context *ctx, uint8_t *hash); void ed25519_hash_final(ed25519_hash_context *ctx, uint8_t *hash);
void ed25519_hash(uint8_t *hash, const uint8_t *in, size_t inlen); void ed25519_hash(uint8_t *hash, const uint8_t *in, size_t inlen);
##### Random Options ##### Random Options
If you are not compiling aginst OpenSSL, you will need a random function for batch verification. If you are not compiling aginst OpenSSL, you will need a random function for batch verification.
To use a custom random function, use `-DED25519_CUSTOMRANDOM` when compiling `ed25519.c` and put your To use a custom random function, use `-DED25519_CUSTOMRANDOM` when compiling `ed25519.c` and put your
custom hash implementation in ed25519-randombytes-custom.h. The random function must implement: custom hash implementation in ed25519-randombytes-custom.h. The random function must implement:
void ED25519_FN(ed25519_randombytes_unsafe) (void *p, size_t len); void ED25519_FN(ed25519_randombytes_unsafe) (void *p, size_t len);
Use `-DED25519_TEST` when compiling `ed25519.c` to use a deterministically seeded, non-thread safe CSPRNG Use `-DED25519_TEST` when compiling `ed25519.c` to use a deterministically seeded, non-thread safe CSPRNG
variant of Bob Jenkins [ISAAC](http://en.wikipedia.org/wiki/ISAAC_%28cipher%29) variant of Bob Jenkins [ISAAC](http://en.wikipedia.org/wiki/ISAAC_%28cipher%29)
##### Minor options ##### Minor options
@@ -91,79 +91,80 @@ Use `-DED25519_FORCE_32BIT` to force the use of 32 bit routines even when compil
##### 32-bit ##### 32-bit
gcc ed25519.c -m32 -O3 -c gcc ed25519.c -m32 -O3 -c
##### 64-bit ##### 64-bit
gcc ed25519.c -m64 -O3 -c gcc ed25519.c -m64 -O3 -c
##### SSE2 ##### SSE2
gcc ed25519.c -m32 -O3 -c -DED25519_SSE2 -msse2 gcc ed25519.c -m32 -O3 -c -DED25519_SSE2 -msse2
gcc ed25519.c -m64 -O3 -c -DED25519_SSE2 gcc ed25519.c -m64 -O3 -c -DED25519_SSE2
clang and icc are also supported clang and icc are also supported
#### Usage #### Usage
To use the code, link against `ed25519.o -mbits` and: To use the code, link against `ed25519.o -mbits` and:
#include "ed25519.h" #include "ed25519.h"
Add `-lssl -lcrypto` when using OpenSSL (Some systems don't need -lcrypto? It might be trial and error). Add `-lssl -lcrypto` when using OpenSSL (Some systems don't need -lcrypto? It might be trial and error).
To generate a private key, simply generate 32 bytes from a secure To generate a private key, simply generate 32 bytes from a secure
cryptographic source: cryptographic source:
ed25519_secret_key sk; ed25519_secret_key sk;
randombytes(sk, sizeof(ed25519_secret_key)); randombytes(sk, sizeof(ed25519_secret_key));
To generate a public key: To generate a public key:
ed25519_public_key pk; ed25519_public_key pk;
ed25519_publickey(sk, pk); ed25519_publickey(sk, pk);
To sign a message: To sign a message:
ed25519_signature sig; ed25519_signature sig;
ed25519_sign(message, message_len, sk, pk, signature); ed25519_sign(message, message_len, sk, pk, signature);
To verify a signature: To verify a signature:
int valid = ed25519_sign_open(message, message_len, pk, signature) == 0; int valid = ed25519_sign_open(message, message_len, pk, signature) == 0;
To batch verify signatures: To batch verify signatures:
const unsigned char *mp[num] = {message1, message2..} const unsigned char *mp[num] = {message1, message2..}
size_t ml[num] = {message_len1, message_len2..} size_t ml[num] = {message_len1, message_len2..}
const unsigned char *pkp[num] = {pk1, pk2..} const unsigned char *pkp[num] = {pk1, pk2..}
const unsigned char *sigp[num] = {signature1, signature2..} const unsigned char *sigp[num] = {signature1, signature2..}
int valid[num] int valid[num]
/* valid[i] will be set to 1 if the individual signature was valid, 0 otherwise */ /* valid[i] will be set to 1 if the individual signature was valid, 0 otherwise */
int all_valid = ed25519_sign_open_batch(mp, ml, pkp, sigp, num, valid) == 0; int all_valid = ed25519_sign_open_batch(mp, ml, pkp, sigp, num, valid) == 0;
**Note**: Batch verification uses `ed25519_randombytes_unsafe`, implemented in **Note**: Batch verification uses `ed25519_randombytes_unsafe`, implemented in
`ed25519-randombytes.h`, to generate random scalars for the verification code. `ed25519-randombytes.h`, to generate random scalars for the verification code.
The default implementation now uses OpenSSLs `RAND_bytes`. The default implementation now uses OpenSSLs `RAND_bytes`.
Unlike the [SUPERCOP](http://bench.cr.yp.to/supercop.html) version, signatures are Unlike the [SUPERCOP](http://bench.cr.yp.to/supercop.html) version, signatures are
not appended to messages, and there is no need for padding in front of messages. not appended to messages, and there is no need for padding in front of messages.
Additionally, the secret key does not contain a copy of the public key, so it is Additionally, the secret key does not contain a copy of the public key, so it is
32 bytes instead of 64 bytes, and the public key must be provided to the signing 32 bytes instead of 64 bytes, and the public key must be provided to the signing
function. function.
##### Curve25519 ##### Curve25519
Curve25519 public keys can be generated thanks to Curve25519 public keys can be generated thanks to
[Adam Langley](http://www.imperialviolet.org/2013/05/10/fastercurve25519.html) [Adam Langley](http://www.imperialviolet.org/2013/05/10/fastercurve25519.html)
leveraging Ed25519's precomputed basepoint scalar multiplication. leveraging Ed25519's precomputed basepoint scalar multiplication.
curved25519_key sk, pk; curved25519_key sk, pk;
randombytes(sk, sizeof(curved25519_key)); randombytes(sk, sizeof(curved25519_key));
curved25519_scalarmult_basepoint(pk, sk); curved25519_scalarmult_basepoint(pk, sk);
Note the name is curved25519, a combination of curve and ed25519, to prevent Note the name is curved25519, a combination of curve and ed25519, to prevent
name clashes. Performance is slightly faster than short message ed25519 name clashes. Performance is slightly faster than short message ed25519
signing due to both using the same code for the scalar multiply. signing due to both using the same code for the scalar multiply.
@@ -179,4 +180,4 @@ with extreme values to ensure they function correctly. SSE2 is now supported.
#### Papers #### Papers
[Available on the Ed25519 website](http://ed25519.cr.yp.to/papers.html) [Available on the Ed25519 website](http://ed25519.cr.yp.to/papers.html)

99
external/ed25519-donna/fuzz/README.md vendored
View File

@@ -1,78 +1,78 @@
This code fuzzes ed25519-donna (and optionally ed25519-donna-sse2) against the ref10 implementations of This code fuzzes ed25519-donna (and optionally ed25519-donna-sse2) against the ref10 implementations of
[curve25519](https://github.com/floodyberry/supercop/tree/master/crypto_scalarmult/curve25519/ref10) and [curve25519](https://github.com/floodyberry/supercop/tree/master/crypto_scalarmult/curve25519/ref10) and
[ed25519](https://github.com/floodyberry/supercop/tree/master/crypto_sign/ed25519/ref10). [ed25519](https://github.com/floodyberry/supercop/tree/master/crypto_sign/ed25519/ref10).
Curve25519 tests that generating a public key from a secret key Curve25519 tests that generating a public key from a secret key
# Building # Building
## \*nix + PHP ## *nix + PHP
`php build-nix.php (required parameters) (optional parameters)` `php build-nix.php (required parameters) (optional parameters)`
Required parameters: Required parameters:
- `--function=[curve25519,ed25519]` * `--function=[curve25519,ed25519]`
- `--bits=[32,64]` * `--bits=[32,64]`
Optional parameters: Optional parameters:
- `--with-sse2` * `--with-sse2`
Also fuzz against ed25519-donna-sse2 Also fuzz against ed25519-donna-sse2
* `--with-openssl`
- `--with-openssl` Build with OpenSSL's SHA-512.
Build with OpenSSL's SHA-512. Default: Reference SHA-512 implementation (slow!)
Default: Reference SHA-512 implementation (slow!) * `--compiler=[gcc,clang,icc]`
- `--compiler=[gcc,clang,icc]` Default: gcc
Default: gcc * `--no-asm`
- `--no-asm` Do not use platform specific assembler
Do not use platform specific assembler
example: example:
php build-nix.php --bits=64 --function=ed25519 --with-sse2 --compiler=icc php build-nix.php --bits=64 --function=ed25519 --with-sse2 --compiler=icc
## Windows ## Windows
Create a project with access to the ed25519 files. Create a project with access to the ed25519 files.
If you are not using OpenSSL, add the `ED25519_REFHASH` define to the projects If you are not using OpenSSL, add the `ED25519_REFHASH` define to the projects
"Properties/Preprocessor/Preprocessor Definitions" option "Properties/Preprocessor/Preprocessor Definitions" option
Add the following files to the project: Add the following files to the project:
- `fuzz/curve25519-ref10.c` * `fuzz/curve25519-ref10.c`
- `fuzz/ed25519-ref10.c` * `fuzz/ed25519-ref10.c`
- `fuzz/ed25519-donna.c` * `fuzz/ed25519-donna.c`
- `fuzz/ed25519-donna-sse2.c` (optional) * `fuzz/ed25519-donna-sse2.c` (optional)
- `fuzz-[curve25519/ed25519].c` (depending on which you want to fuzz) * `fuzz-[curve25519/ed25519].c` (depending on which you want to fuzz)
If you are also fuzzing against ed25519-donna-sse2, add the `ED25519_SSE2` define for `fuzz-[curve25519/ed25519].c` under If you are also fuzzing against ed25519-donna-sse2, add the `ED25519_SSE2` define for `fuzz-[curve25519/ed25519].c` under
its "Properties/Preprocessor/Preprocessor Definitions" option. its "Properties/Preprocessor/Preprocessor Definitions" option.
# Running # Running
If everything agrees, the program will only output occasional status dots (every 0x1000 passes) If everything agrees, the program will only output occasional status dots (every 0x1000 passes)
and a 64bit progress count (every 0x20000 passes): and a 64bit progress count (every 0x20000 passes):
fuzzing: ref10 curved25519 curved25519-sse2 fuzzing: ref10 curved25519 curved25519-sse2
................................ [0000000000020000] ................................ [0000000000020000]
................................ [0000000000040000] ................................ [0000000000040000]
................................ [0000000000060000] ................................ [0000000000060000]
................................ [0000000000080000] ................................ [0000000000080000]
................................ [00000000000a0000] ................................ [00000000000a0000]
................................ [00000000000c0000] ................................ [00000000000c0000]
If any of the implementations do not agree with the ref10 implementation, the program will dump If any of the implementations do not agree with the ref10 implementation, the program will dump
the random data that was used, the data generated by the ref10 implementation, and diffs of the the random data that was used, the data generated by the ref10 implementation, and diffs of the
ed25519-donna data against the ref10 data. ed25519-donna data against the ref10 data.
## Example errors ## Example errors
@@ -83,21 +83,21 @@ These are example error dumps (with intentionally introduced errors).
Random data: Random data:
- sk, or Secret Key * sk, or Secret Key
- m, or Message * m, or Message
Generated data: Generated data:
- pk, or Public Key * pk, or Public Key
- sig, or Signature * sig, or Signature
- valid, or if the signature of the message is valid with the public key * valid, or if the signature of the message is valid with the public key
Dump: Dump:
sk: sk:
0x3b,0xb7,0x17,0x7a,0x66,0xdc,0xb7,0x9a,0x90,0x25,0x07,0x99,0x96,0xf3,0x92,0xef, 0x3b,0xb7,0x17,0x7a,0x66,0xdc,0xb7,0x9a,0x90,0x25,0x07,0x99,0x96,0xf3,0x92,0xef,
0x78,0xf8,0xad,0x6c,0x35,0x87,0x81,0x67,0x03,0xe6,0x95,0xba,0x06,0x18,0x7c,0x9c, 0x78,0xf8,0xad,0x6c,0x35,0x87,0x81,0x67,0x03,0xe6,0x95,0xba,0x06,0x18,0x7c,0x9c,
m: m:
0x7c,0x8d,0x3d,0xe1,0x92,0xee,0x7a,0xb8,0x4d,0xc9,0xfb,0x02,0x34,0x1e,0x5a,0x91, 0x7c,0x8d,0x3d,0xe1,0x92,0xee,0x7a,0xb8,0x4d,0xc9,0xfb,0x02,0x34,0x1e,0x5a,0x91,
0xee,0x01,0xa6,0xb8,0xab,0x37,0x3f,0x3d,0x6d,0xa2,0x47,0xe3,0x27,0x93,0x7c,0xb7, 0xee,0x01,0xa6,0xb8,0xab,0x37,0x3f,0x3d,0x6d,0xa2,0x47,0xe3,0x27,0x93,0x7c,0xb7,
@@ -107,66 +107,67 @@ Dump:
0x63,0x14,0xe0,0x81,0x52,0xec,0xcd,0xcf,0x70,0x54,0x7d,0xa3,0x49,0x8b,0xf0,0x89, 0x63,0x14,0xe0,0x81,0x52,0xec,0xcd,0xcf,0x70,0x54,0x7d,0xa3,0x49,0x8b,0xf0,0x89,
0x70,0x07,0x12,0x2a,0xd9,0xaa,0x16,0x01,0xb2,0x16,0x3a,0xbb,0xfc,0xfa,0x13,0x5b, 0x70,0x07,0x12,0x2a,0xd9,0xaa,0x16,0x01,0xb2,0x16,0x3a,0xbb,0xfc,0xfa,0x13,0x5b,
0x69,0x83,0x92,0x70,0x95,0x76,0xa0,0x8e,0x16,0x79,0xcc,0xaa,0xb5,0x7c,0xf8,0x7a, 0x69,0x83,0x92,0x70,0x95,0x76,0xa0,0x8e,0x16,0x79,0xcc,0xaa,0xb5,0x7c,0xf8,0x7a,
ref10: ref10:
pk: pk:
0x71,0xb0,0x5e,0x62,0x1b,0xe3,0xe7,0x36,0x91,0x8b,0xc0,0x13,0x36,0x0c,0xc9,0x04, 0x71,0xb0,0x5e,0x62,0x1b,0xe3,0xe7,0x36,0x91,0x8b,0xc0,0x13,0x36,0x0c,0xc9,0x04,
0x16,0xf5,0xff,0x48,0x0c,0x83,0x6b,0x88,0x53,0xa2,0xc6,0x0f,0xf7,0xac,0x42,0x04, 0x16,0xf5,0xff,0x48,0x0c,0x83,0x6b,0x88,0x53,0xa2,0xc6,0x0f,0xf7,0xac,0x42,0x04,
sig: sig:
0x3e,0x05,0xc5,0x37,0x16,0x0b,0x29,0x30,0x89,0xa3,0xe7,0x83,0x08,0x16,0xdd,0x96, 0x3e,0x05,0xc5,0x37,0x16,0x0b,0x29,0x30,0x89,0xa3,0xe7,0x83,0x08,0x16,0xdd,0x96,
0x02,0xfa,0x0d,0x44,0x2c,0x43,0xaa,0x80,0x93,0x04,0x58,0x22,0x09,0xbf,0x11,0xa5, 0x02,0xfa,0x0d,0x44,0x2c,0x43,0xaa,0x80,0x93,0x04,0x58,0x22,0x09,0xbf,0x11,0xa5,
0xcc,0xa5,0x3c,0x9f,0xa0,0xa4,0x64,0x5a,0x4a,0xdb,0x20,0xfb,0xc7,0x9b,0xfd,0x3f, 0xcc,0xa5,0x3c,0x9f,0xa0,0xa4,0x64,0x5a,0x4a,0xdb,0x20,0xfb,0xc7,0x9b,0xfd,0x3f,
0x08,0xae,0xc4,0x3c,0x1e,0xd8,0xb6,0xb4,0xd2,0x6d,0x80,0x92,0xcb,0x71,0xf3,0x02, 0x08,0xae,0xc4,0x3c,0x1e,0xd8,0xb6,0xb4,0xd2,0x6d,0x80,0x92,0xcb,0x71,0xf3,0x02,
valid: yes valid: yes
ed25519-donna: ed25519-donna:
pk diff: pk diff:
____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____, ____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,
____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____, ____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,
sig diff: sig diff:
0x2c,0xb9,0x25,0x14,0xd0,0x94,0xeb,0xfe,0x46,0x02,0xc2,0xe8,0xa3,0xeb,0xbf,0xb5, 0x2c,0xb9,0x25,0x14,0xd0,0x94,0xeb,0xfe,0x46,0x02,0xc2,0xe8,0xa3,0xeb,0xbf,0xb5,
0x72,0x84,0xbf,0xc1,0x8a,0x32,0x30,0x99,0xf7,0x58,0xfe,0x06,0xa8,0xdc,0xdc,0xab, 0x72,0x84,0xbf,0xc1,0x8a,0x32,0x30,0x99,0xf7,0x58,0xfe,0x06,0xa8,0xdc,0xdc,0xab,
0xb5,0x57,0x03,0x33,0x87,0xce,0x54,0x55,0x6a,0x69,0x8a,0xc4,0xb7,0x2a,0xed,0x97, 0xb5,0x57,0x03,0x33,0x87,0xce,0x54,0x55,0x6a,0x69,0x8a,0xc4,0xb7,0x2a,0xed,0x97,
0xb4,0x68,0xe7,0x52,0x7a,0x07,0x55,0x3b,0xa2,0x94,0xd6,0x5e,0xa1,0x61,0x80,0x08, 0xb4,0x68,0xe7,0x52,0x7a,0x07,0x55,0x3b,0xa2,0x94,0xd6,0x5e,0xa1,0x61,0x80,0x08,
valid: no valid: no
In this case, the generated public key matches, but the generated signature is completely In this case, the generated public key matches, but the generated signature is completely
different and does not validate. different and does not validate.
### Curve25519 ### Curve25519
Random data: Random data:
- sk, or Secret Key * sk, or Secret Key
Generated data: Generated data:
- pk, or Public Key * pk, or Public Key
Dump: Dump:
sk: sk:
0x44,0xec,0x0b,0x0e,0xa2,0x0e,0x9c,0x5b,0x8c,0xce,0x7b,0x1d,0x68,0xae,0x0f,0x9e, 0x44,0xec,0x0b,0x0e,0xa2,0x0e,0x9c,0x5b,0x8c,0xce,0x7b,0x1d,0x68,0xae,0x0f,0x9e,
0x81,0xe2,0x04,0x76,0xda,0x87,0xa4,0x9e,0xc9,0x4f,0x3b,0xf9,0xc3,0x89,0x63,0x70, 0x81,0xe2,0x04,0x76,0xda,0x87,0xa4,0x9e,0xc9,0x4f,0x3b,0xf9,0xc3,0x89,0x63,0x70,
ref10: ref10:
0x24,0x55,0x55,0xc0,0xf9,0x80,0xaf,0x02,0x43,0xee,0x8c,0x7f,0xc1,0xad,0x90,0x95, 0x24,0x55,0x55,0xc0,0xf9,0x80,0xaf,0x02,0x43,0xee,0x8c,0x7f,0xc1,0xad,0x90,0x95,
0x57,0x91,0x14,0x2e,0xf2,0x14,0x22,0x80,0xdd,0x4e,0x3c,0x85,0x71,0x84,0x8c,0x62, 0x57,0x91,0x14,0x2e,0xf2,0x14,0x22,0x80,0xdd,0x4e,0x3c,0x85,0x71,0x84,0x8c,0x62,
curved25519 diff: curved25519 diff:
0x12,0xd1,0x61,0x2b,0x16,0xb3,0xd8,0x29,0xf8,0xa3,0xba,0x70,0x4e,0x49,0x4f,0x43, 0x12,0xd1,0x61,0x2b,0x16,0xb3,0xd8,0x29,0xf8,0xa3,0xba,0x70,0x4e,0x49,0x4f,0x43,
0xa1,0x3c,0x6b,0x42,0x11,0x61,0xcc,0x30,0x87,0x73,0x46,0xfb,0x85,0xc7,0x9a,0x35, 0xa1,0x3c,0x6b,0x42,0x11,0x61,0xcc,0x30,0x87,0x73,0x46,0xfb,0x85,0xc7,0x9a,0x35,
curved25519-sse2 diff: curved25519-sse2 diff:
____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____, ____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,
____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____, ____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,____,
In this case, curved25519 is totally wrong, while curved25519-sse2 matches the reference
implementation. In this case, curved25519 is totally wrong, while curved25519-sse2 matches the reference
implementation.

144
external/secp256k1/CHANGELOG.md vendored
View File

@@ -8,189 +8,153 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [0.6.0] - 2024-11-04 ## [0.6.0] - 2024-11-04
#### Added #### Added
- New module `musig` implements the MuSig2 multisignature scheme according to the [BIP 327 specification](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki). See:
- New module `musig` implements the MuSig2 multisignature scheme according to the [BIP 327 specification](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki). See: - Header file `include/secp256k1_musig.h` which defines the new API.
- Header file `include/secp256k1_musig.h` which defines the new API. - Document `doc/musig.md` for further notes on API usage.
- Document `doc/musig.md` for further notes on API usage. - Usage example `examples/musig.c`.
- Usage example `examples/musig.c`. - New CMake variable `SECP256K1_APPEND_LDFLAGS` for appending linker flags to the build command.
- New CMake variable `SECP256K1_APPEND_LDFLAGS` for appending linker flags to the build command.
#### Changed #### Changed
- API functions now use a significantly more robust method to clear secrets from the stack before returning. However, secret clearing remains a best-effort security measure and cannot guarantee complete removal.
- API functions now use a significantly more robust method to clear secrets from the stack before returning. However, secret clearing remains a best-effort security measure and cannot guarantee complete removal. - Any type `secp256k1_foo` can now be forward-declared using `typedef struct secp256k1_foo secp256k1_foo;` (or also `struct secp256k1_foo;` in C++).
- Any type `secp256k1_foo` can now be forward-declared using `typedef struct secp256k1_foo secp256k1_foo;` (or also `struct secp256k1_foo;` in C++). - Organized CMake build artifacts into dedicated directories (`bin/` for executables, `lib/` for libraries) to improve build output structure and Windows shared library compatibility.
- Organized CMake build artifacts into dedicated directories (`bin/` for executables, `lib/` for libraries) to improve build output structure and Windows shared library compatibility.
#### Removed #### Removed
- Removed the `secp256k1_scratch_space` struct and its associated functions `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` because the scratch space was unused in the API.
- Removed the `secp256k1_scratch_space` struct and its associated functions `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` because the scratch space was unused in the API.
#### ABI Compatibility #### ABI Compatibility
The symbols `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` were removed. The symbols `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` were removed.
Otherwise, the library maintains backward compatibility with versions 0.3.x through 0.5.x. Otherwise, the library maintains backward compatibility with versions 0.3.x through 0.5.x.
## [0.5.1] - 2024-08-01 ## [0.5.1] - 2024-08-01
#### Added #### Added
- Added usage example for an ElligatorSwift key exchange.
- Added usage example for an ElligatorSwift key exchange.
#### Changed #### Changed
- The default size of the precomputed table for signing was changed from 22 KiB to 86 KiB. The size can be changed with the configure option `--ecmult-gen-kb` (`SECP256K1_ECMULT_GEN_KB` for CMake).
- The default size of the precomputed table for signing was changed from 22 KiB to 86 KiB. The size can be changed with the configure option `--ecmult-gen-kb` (`SECP256K1_ECMULT_GEN_KB` for CMake). - "auto" is no longer an accepted value for the `--with-ecmult-window` and `--with-ecmult-gen-kb` configure options (this also applies to `SECP256K1_ECMULT_WINDOW_SIZE` and `SECP256K1_ECMULT_GEN_KB` in CMake). To achieve the same configuration as previously provided by the "auto" value, omit setting the configure option explicitly.
- "auto" is no longer an accepted value for the `--with-ecmult-window` and `--with-ecmult-gen-kb` configure options (this also applies to `SECP256K1_ECMULT_WINDOW_SIZE` and `SECP256K1_ECMULT_GEN_KB` in CMake). To achieve the same configuration as previously provided by the "auto" value, omit setting the configure option explicitly.
#### Fixed #### Fixed
- Fixed compilation when the extrakeys module is disabled.
- Fixed compilation when the extrakeys module is disabled.
#### ABI Compatibility #### ABI Compatibility
The ABI is backward compatible with versions 0.5.0, 0.4.x and 0.3.x. The ABI is backward compatible with versions 0.5.0, 0.4.x and 0.3.x.
## [0.5.0] - 2024-05-06 ## [0.5.0] - 2024-05-06
#### Added #### Added
- New function `secp256k1_ec_pubkey_sort` that sorts public keys using lexicographic (of compressed serialization) order.
- New function `secp256k1_ec_pubkey_sort` that sorts public keys using lexicographic (of compressed serialization) order.
#### Changed #### Changed
- The implementation of the point multiplication algorithm used for signing and public key generation was changed, resulting in improved performance for those operations.
- The implementation of the point multiplication algorithm used for signing and public key generation was changed, resulting in improved performance for those operations. - The related configure option `--ecmult-gen-precision` was replaced with `--ecmult-gen-kb` (`SECP256K1_ECMULT_GEN_KB` for CMake).
- The related configure option `--ecmult-gen-precision` was replaced with `--ecmult-gen-kb` (`SECP256K1_ECMULT_GEN_KB` for CMake). - This changes the supported precomputed table sizes for these operations. The new supported sizes are 2 KiB, 22 KiB, or 86 KiB (while the old supported sizes were 32 KiB, 64 KiB, or 512 KiB).
- This changes the supported precomputed table sizes for these operations. The new supported sizes are 2 KiB, 22 KiB, or 86 KiB (while the old supported sizes were 32 KiB, 64 KiB, or 512 KiB).
#### ABI Compatibility #### ABI Compatibility
The ABI is backward compatible with versions 0.4.x and 0.3.x. The ABI is backward compatible with versions 0.4.x and 0.3.x.
## [0.4.1] - 2023-12-21 ## [0.4.1] - 2023-12-21
#### Changed #### Changed
- The point multiplication algorithm used for ECDH operations (module `ecdh`) was replaced with a slightly faster one.
- The point multiplication algorithm used for ECDH operations (module `ecdh`) was replaced with a slightly faster one. - Optional handwritten x86_64 assembly for field operations was removed because modern C compilers are able to output more efficient assembly. This change results in a significant speedup of some library functions when handwritten x86_64 assembly is enabled (`--with-asm=x86_64` in GNU Autotools, `-DSECP256K1_ASM=x86_64` in CMake), which is the default on x86_64. Benchmarks with GCC 10.5.0 show a 10% speedup for `secp256k1_ecdsa_verify` and `secp256k1_schnorrsig_verify`.
- Optional handwritten x86_64 assembly for field operations was removed because modern C compilers are able to output more efficient assembly. This change results in a significant speedup of some library functions when handwritten x86_64 assembly is enabled (`--with-asm=x86_64` in GNU Autotools, `-DSECP256K1_ASM=x86_64` in CMake), which is the default on x86_64. Benchmarks with GCC 10.5.0 show a 10% speedup for `secp256k1_ecdsa_verify` and `secp256k1_schnorrsig_verify`.
#### ABI Compatibility #### ABI Compatibility
The ABI is backward compatible with versions 0.4.0 and 0.3.x. The ABI is backward compatible with versions 0.4.0 and 0.3.x.
## [0.4.0] - 2023-09-04 ## [0.4.0] - 2023-09-04
#### Added #### Added
- New module `ellswift` implements ElligatorSwift encoding for public keys and x-only Diffie-Hellman key exchange for them.
- New module `ellswift` implements ElligatorSwift encoding for public keys and x-only Diffie-Hellman key exchange for them. ElligatorSwift permits representing secp256k1 public keys as 64-byte arrays which cannot be distinguished from uniformly random. See:
ElligatorSwift permits representing secp256k1 public keys as 64-byte arrays which cannot be distinguished from uniformly random. See: - Header file `include/secp256k1_ellswift.h` which defines the new API.
- Header file `include/secp256k1_ellswift.h` which defines the new API. - Document `doc/ellswift.md` which explains the mathematical background of the scheme.
- Document `doc/ellswift.md` which explains the mathematical background of the scheme. - The [paper](https://eprint.iacr.org/2022/759) on which the scheme is based.
- The [paper](https://eprint.iacr.org/2022/759) on which the scheme is based. - We now test the library with unreleased development snapshots of GCC and Clang. This gives us an early chance to catch miscompilations and constant-time issues introduced by the compiler (such as those that led to the previous two releases).
- We now test the library with unreleased development snapshots of GCC and Clang. This gives us an early chance to catch miscompilations and constant-time issues introduced by the compiler (such as those that led to the previous two releases).
#### Fixed #### Fixed
- Fixed symbol visibility in Windows DLL builds, where three internal library symbols were wrongly exported.
- Fixed symbol visibility in Windows DLL builds, where three internal library symbols were wrongly exported.
#### Changed #### Changed
- When consuming libsecp256k1 as a static library on Windows, the user must now define the `SECP256K1_STATIC` macro before including `secp256k1.h`.
- When consuming libsecp256k1 as a static library on Windows, the user must now define the `SECP256K1_STATIC` macro before including `secp256k1.h`.
#### ABI Compatibility #### ABI Compatibility
This release is backward compatible with the ABI of 0.3.0, 0.3.1, and 0.3.2. Symbol visibility is now believed to be handled properly on supported platforms and is now considered to be part of the ABI. Please report any improperly exported symbols as a bug. This release is backward compatible with the ABI of 0.3.0, 0.3.1, and 0.3.2. Symbol visibility is now believed to be handled properly on supported platforms and is now considered to be part of the ABI. Please report any improperly exported symbols as a bug.
## [0.3.2] - 2023-05-13 ## [0.3.2] - 2023-05-13
We strongly recommend updating to 0.3.2 if you use or plan to use GCC >=13 to compile libsecp256k1. When in doubt, check the GCC version using `gcc -v`. We strongly recommend updating to 0.3.2 if you use or plan to use GCC >=13 to compile libsecp256k1. When in doubt, check the GCC version using `gcc -v`.
#### Security #### Security
- Module `ecdh`: Fix "constant-timeness" issue with GCC 13.1 (and potentially future versions of GCC) that could leave applications using libsecp256k1's ECDH module vulnerable to a timing side-channel attack. The fix avoids secret-dependent control flow during ECDH computations when libsecp256k1 is compiled with GCC 13.1.
- Module `ecdh`: Fix "constant-timeness" issue with GCC 13.1 (and potentially future versions of GCC) that could leave applications using libsecp256k1's ECDH module vulnerable to a timing side-channel attack. The fix avoids secret-dependent control flow during ECDH computations when libsecp256k1 is compiled with GCC 13.1.
#### Fixed #### Fixed
- Fixed an old bug that permitted compilers to potentially output bad assembly code on x86_64. In theory, it could lead to a crash or a read of unrelated memory, but this has never been observed on any compilers so far.
- Fixed an old bug that permitted compilers to potentially output bad assembly code on x86_64. In theory, it could lead to a crash or a read of unrelated memory, but this has never been observed on any compilers so far.
#### Changed #### Changed
- Various improvements and changes to CMake builds. CMake builds remain experimental.
- Various improvements and changes to CMake builds. CMake builds remain experimental. - Made API versioning consistent with GNU Autotools builds.
- Made API versioning consistent with GNU Autotools builds. - Switched to `BUILD_SHARED_LIBS` variable for controlling whether to build a static or a shared library.
- Switched to `BUILD_SHARED_LIBS` variable for controlling whether to build a static or a shared library. - Added `SECP256K1_INSTALL` variable for the controlling whether to install the build artefacts.
- Added `SECP256K1_INSTALL` variable for the controlling whether to install the build artefacts. - Renamed asm build option `arm` to `arm32`. Use `--with-asm=arm32` instead of `--with-asm=arm` (GNU Autotools), and `-DSECP256K1_ASM=arm32` instead of `-DSECP256K1_ASM=arm` (CMake).
- Renamed asm build option `arm` to `arm32`. Use `--with-asm=arm32` instead of `--with-asm=arm` (GNU Autotools), and `-DSECP256K1_ASM=arm32` instead of `-DSECP256K1_ASM=arm` (CMake).
#### ABI Compatibility #### ABI Compatibility
The ABI is compatible with versions 0.3.0 and 0.3.1. The ABI is compatible with versions 0.3.0 and 0.3.1.
## [0.3.1] - 2023-04-10 ## [0.3.1] - 2023-04-10
We strongly recommend updating to 0.3.1 if you use or plan to use Clang >=14 to compile libsecp256k1, e.g., Xcode >=14 on macOS has Clang >=14. When in doubt, check the Clang version using `clang -v`. We strongly recommend updating to 0.3.1 if you use or plan to use Clang >=14 to compile libsecp256k1, e.g., Xcode >=14 on macOS has Clang >=14. When in doubt, check the Clang version using `clang -v`.
#### Security #### Security
- Fix "constant-timeness" issue with Clang >=14 that could leave applications using libsecp256k1 vulnerable to a timing side-channel attack. The fix avoids secret-dependent control flow and secret-dependent memory accesses in conditional moves of memory objects when libsecp256k1 is compiled with Clang >=14.
- Fix "constant-timeness" issue with Clang >=14 that could leave applications using libsecp256k1 vulnerable to a timing side-channel attack. The fix avoids secret-dependent control flow and secret-dependent memory accesses in conditional moves of memory objects when libsecp256k1 is compiled with Clang >=14.
#### Added #### Added
- Added tests against [Project Wycheproof's](https://github.com/google/wycheproof/) set of ECDSA test vectors (Bitcoin "low-S" variant), a fixed set of test cases designed to trigger various edge cases.
- Added tests against [Project Wycheproof's](https://github.com/google/wycheproof/) set of ECDSA test vectors (Bitcoin "low-S" variant), a fixed set of test cases designed to trigger various edge cases.
#### Changed #### Changed
- Increased minimum required CMake version to 3.13. CMake builds remain experimental.
- Increased minimum required CMake version to 3.13. CMake builds remain experimental.
#### ABI Compatibility #### ABI Compatibility
The ABI is compatible with version 0.3.0. The ABI is compatible with version 0.3.0.
## [0.3.0] - 2023-03-08 ## [0.3.0] - 2023-03-08
#### Added #### Added
- Added experimental support for CMake builds. Traditional GNU Autotools builds (`./configure` and `make`) remain fully supported.
- Added experimental support for CMake builds. Traditional GNU Autotools builds (`./configure` and `make`) remain fully supported. - Usage examples: Added a recommended method for securely clearing sensitive data, e.g., secret keys, from memory.
- Usage examples: Added a recommended method for securely clearing sensitive data, e.g., secret keys, from memory. - Tests: Added a new test binary `noverify_tests`. This binary runs the tests without some additional checks present in the ordinary `tests` binary and is thereby closer to production binaries. The `noverify_tests` binary is automatically run as part of the `make check` target.
- Tests: Added a new test binary `noverify_tests`. This binary runs the tests without some additional checks present in the ordinary `tests` binary and is thereby closer to production binaries. The `noverify_tests` binary is automatically run as part of the `make check` target.
#### Fixed #### Fixed
- Fixed declarations of API variables for MSVC (`__declspec(dllimport)`). This fixes MSVC builds of programs which link against a libsecp256k1 DLL dynamically and use API variables (and not only API functions). Unfortunately, the MSVC linker now will emit warning `LNK4217` when trying to link against libsecp256k1 statically. Pass `/ignore:4217` to the linker to suppress this warning.
- Fixed declarations of API variables for MSVC (`__declspec(dllimport)`). This fixes MSVC builds of programs which link against a libsecp256k1 DLL dynamically and use API variables (and not only API functions). Unfortunately, the MSVC linker now will emit warning `LNK4217` when trying to link against libsecp256k1 statically. Pass `/ignore:4217` to the linker to suppress this warning.
#### Changed #### Changed
- Forbade cloning or destroying `secp256k1_context_static`. Create a new context instead of cloning the static context. (If this change breaks your code, your code is probably wrong.)
- Forbade cloning or destroying `secp256k1_context_static`. Create a new context instead of cloning the static context. (If this change breaks your code, your code is probably wrong.) - Forbade randomizing (copies of) `secp256k1_context_static`. Randomizing a copy of `secp256k1_context_static` did not have any effect and did not provide defense-in-depth protection against side-channel attacks. Create a new context if you want to benefit from randomization.
- Forbade randomizing (copies of) `secp256k1_context_static`. Randomizing a copy of `secp256k1_context_static` did not have any effect and did not provide defense-in-depth protection against side-channel attacks. Create a new context if you want to benefit from randomization.
#### Removed #### Removed
- Removed the configuration header `src/libsecp256k1-config.h`. We recommend passing flags to `./configure` or `cmake` to set configuration options (see `./configure --help` or `cmake -LH`). If you cannot or do not want to use one of the supported build systems, pass configuration flags such as `-DSECP256K1_ENABLE_MODULE_SCHNORRSIG` manually to the compiler (see the file `configure.ac` for supported flags).
- Removed the configuration header `src/libsecp256k1-config.h`. We recommend passing flags to `./configure` or `cmake` to set configuration options (see `./configure --help` or `cmake -LH`). If you cannot or do not want to use one of the supported build systems, pass configuration flags such as `-DSECP256K1_ENABLE_MODULE_SCHNORRSIG` manually to the compiler (see the file `configure.ac` for supported flags).
#### ABI Compatibility #### ABI Compatibility
Due to changes in the API regarding `secp256k1_context_static` described above, the ABI is *not* compatible with previous versions.
Due to changes in the API regarding `secp256k1_context_static` described above, the ABI is _not_ compatible with previous versions.
## [0.2.0] - 2022-12-12 ## [0.2.0] - 2022-12-12
#### Added #### Added
- Added usage examples for common use cases in a new `examples/` directory.
- Added usage examples for common use cases in a new `examples/` directory. - Added `secp256k1_selftest`, to be used in conjunction with `secp256k1_context_static`.
- Added `secp256k1_selftest`, to be used in conjunction with `secp256k1_context_static`. - Added support for 128-bit wide multiplication on MSVC for x86_64 and arm64, giving roughly a 20% speedup on those platforms.
- Added support for 128-bit wide multiplication on MSVC for x86_64 and arm64, giving roughly a 20% speedup on those platforms.
#### Changed #### Changed
- Enabled modules `schnorrsig`, `extrakeys` and `ecdh` by default in `./configure`.
- Enabled modules `schnorrsig`, `extrakeys` and `ecdh` by default in `./configure`. - The `secp256k1_nonce_function_rfc6979` nonce function, used by default by `secp256k1_ecdsa_sign`, now reduces the message hash modulo the group order to match the specification. This only affects improper use of ECDSA signing API.
- The `secp256k1_nonce_function_rfc6979` nonce function, used by default by `secp256k1_ecdsa_sign`, now reduces the message hash modulo the group order to match the specification. This only affects improper use of ECDSA signing API.
#### Deprecated #### Deprecated
- Deprecated context flags `SECP256K1_CONTEXT_VERIFY` and `SECP256K1_CONTEXT_SIGN`. Use `SECP256K1_CONTEXT_NONE` instead.
- Deprecated context flags `SECP256K1_CONTEXT_VERIFY` and `SECP256K1_CONTEXT_SIGN`. Use `SECP256K1_CONTEXT_NONE` instead. - Renamed `secp256k1_context_no_precomp` to `secp256k1_context_static`.
- Renamed `secp256k1_context_no_precomp` to `secp256k1_context_static`. - Module `schnorrsig`: renamed `secp256k1_schnorrsig_sign` to `secp256k1_schnorrsig_sign32`.
- Module `schnorrsig`: renamed `secp256k1_schnorrsig_sign` to `secp256k1_schnorrsig_sign32`.
#### ABI Compatibility #### ABI Compatibility
Since this is the first release, we do not compare application binary interfaces. Since this is the first release, we do not compare application binary interfaces.
However, there are earlier unreleased versions of libsecp256k1 that are _not_ ABI compatible with this version. However, there are earlier unreleased versions of libsecp256k1 that are *not* ABI compatible with this version.
## [0.1.0] - 2013-03-05 to 2021-12-25 ## [0.1.0] - 2013-03-05 to 2021-12-25

6
external/secp256k1/CMakePresets.json vendored
View File

@@ -1,9 +1,5 @@
{ {
"cmakeMinimumRequired": { "cmakeMinimumRequired": {"major": 3, "minor": 21, "patch": 0},
"major": 3,
"minor": 21,
"patch": 0
},
"version": 3, "version": 3,
"configurePresets": [ "configurePresets": [
{ {

74
external/secp256k1/CONTRIBUTING.md vendored
View File

@@ -12,15 +12,15 @@ The libsecp256k1 project welcomes contributions in the form of new functionality
It is the responsibility of the contributors to convince the maintainers that the proposed functionality is within the project's scope, high-quality and maintainable. It is the responsibility of the contributors to convince the maintainers that the proposed functionality is within the project's scope, high-quality and maintainable.
Contributors are recommended to provide the following in addition to the new code: Contributors are recommended to provide the following in addition to the new code:
- **Specification:** * **Specification:**
A specification can help significantly in reviewing the new code as it provides documentation and context. A specification can help significantly in reviewing the new code as it provides documentation and context.
It may justify various design decisions, give a motivation and outline security goals. It may justify various design decisions, give a motivation and outline security goals.
If the specification contains pseudocode, a reference implementation or test vectors, these can be used to compare with the proposed libsecp256k1 code. If the specification contains pseudocode, a reference implementation or test vectors, these can be used to compare with the proposed libsecp256k1 code.
- **Security Arguments:** * **Security Arguments:**
In addition to a defining the security goals, it should be argued that the new functionality meets these goals. In addition to a defining the security goals, it should be argued that the new functionality meets these goals.
Depending on the nature of the new functionality, a wide range of security arguments are acceptable, ranging from being "obviously secure" to rigorous proofs of security. Depending on the nature of the new functionality, a wide range of security arguments are acceptable, ranging from being "obviously secure" to rigorous proofs of security.
- **Relevance Arguments:** * **Relevance Arguments:**
The relevance of the new functionality for the Bitcoin ecosystem should be argued by outlining clear use cases. The relevance of the new functionality for the Bitcoin ecosystem should be argued by outlining clear use cases.
These are not the only factors taken into account when considering to add new functionality. These are not the only factors taken into account when considering to add new functionality.
The proposed new libsecp256k1 code must be of high quality, including API documentation and tests, as well as featuring a misuse-resistant API design. The proposed new libsecp256k1 code must be of high quality, including API documentation and tests, as well as featuring a misuse-resistant API design.
@@ -44,36 +44,36 @@ The Contributor Workflow & Peer Review in libsecp256k1 are similar to Bitcoin Co
In addition, libsecp256k1 tries to maintain the following coding conventions: In addition, libsecp256k1 tries to maintain the following coding conventions:
- No runtime heap allocation (e.g., no `malloc`) unless explicitly requested by the caller (via `secp256k1_context_create` or `secp256k1_scratch_space_create`, for example). Moreover, it should be possible to use the library without any heap allocations. * No runtime heap allocation (e.g., no `malloc`) unless explicitly requested by the caller (via `secp256k1_context_create` or `secp256k1_scratch_space_create`, for example). Moreover, it should be possible to use the library without any heap allocations.
- The tests should cover all lines and branches of the library (see [Test coverage](#coverage)). * The tests should cover all lines and branches of the library (see [Test coverage](#coverage)).
- Operations involving secret data should be tested for being constant time with respect to the secrets (see [src/ctime_tests.c](src/ctime_tests.c)). * Operations involving secret data should be tested for being constant time with respect to the secrets (see [src/ctime_tests.c](src/ctime_tests.c)).
- Local variables containing secret data should be cleared explicitly to try to delete secrets from memory. * Local variables containing secret data should be cleared explicitly to try to delete secrets from memory.
- Use `secp256k1_memcmp_var` instead of `memcmp` (see [#823](https://github.com/bitcoin-core/secp256k1/issues/823)). * Use `secp256k1_memcmp_var` instead of `memcmp` (see [#823](https://github.com/bitcoin-core/secp256k1/issues/823)).
- As a rule of thumb, the default values for configuration options should target standard desktop machines and align with Bitcoin Core's defaults, and the tests should mostly exercise the default configuration (see [#1549](https://github.com/bitcoin-core/secp256k1/issues/1549#issuecomment-2200559257)). * As a rule of thumb, the default values for configuration options should target standard desktop machines and align with Bitcoin Core's defaults, and the tests should mostly exercise the default configuration (see [#1549](https://github.com/bitcoin-core/secp256k1/issues/1549#issuecomment-2200559257)).
#### Style conventions #### Style conventions
- Commits should be atomic and diffs should be easy to read. For this reason, do not mix any formatting fixes or code moves with actual code changes. Make sure each individual commit is hygienic: that it builds successfully on its own without warnings, errors, regressions, or test failures. * Commits should be atomic and diffs should be easy to read. For this reason, do not mix any formatting fixes or code moves with actual code changes. Make sure each individual commit is hygienic: that it builds successfully on its own without warnings, errors, regressions, or test failures.
- New code should adhere to the style of existing, in particular surrounding, code. Other than that, we do not enforce strict rules for code formatting. * New code should adhere to the style of existing, in particular surrounding, code. Other than that, we do not enforce strict rules for code formatting.
- The code conforms to C89. Most notably, that means that only `/* ... */` comments are allowed (no `//` line comments). Moreover, any declarations in a `{ ... }` block (e.g., a function) must appear at the beginning of the block before any statements. When you would like to declare a variable in the middle of a block, you can open a new block: * The code conforms to C89. Most notably, that means that only `/* ... */` comments are allowed (no `//` line comments). Moreover, any declarations in a `{ ... }` block (e.g., a function) must appear at the beginning of the block before any statements. When you would like to declare a variable in the middle of a block, you can open a new block:
```C ```C
void secp256k_foo(void) { void secp256k_foo(void) {
unsigned int x; /* declaration */ unsigned int x; /* declaration */
int y = 2*x; /* declaration */ int y = 2*x; /* declaration */
x = 17; /* statement */ x = 17; /* statement */
{ {
int a, b; /* declaration */ int a, b; /* declaration */
a = x + y; /* statement */ a = x + y; /* statement */
secp256k_bar(x, &b); /* statement */ secp256k_bar(x, &b); /* statement */
} }
} }
``` ```
- Use `unsigned int` instead of just `unsigned`. * Use `unsigned int` instead of just `unsigned`.
- Use `void *ptr` instead of `void* ptr`. * Use `void *ptr` instead of `void* ptr`.
- Arguments of the publicly-facing API must have a specific order defined in [include/secp256k1.h](include/secp256k1.h). * Arguments of the publicly-facing API must have a specific order defined in [include/secp256k1.h](include/secp256k1.h).
- User-facing comment lines in headers should be limited to 80 chars if possible. * User-facing comment lines in headers should be limited to 80 chars if possible.
- All identifiers in file scope should start with `secp256k1_`. * All identifiers in file scope should start with `secp256k1_`.
- Avoid trailing whitespace. * Avoid trailing whitespace.
### Tests ### Tests
@@ -101,7 +101,7 @@ To create a HTML report with coloured and annotated source code:
#### Exhaustive tests #### Exhaustive tests
There are tests of several functions in which a small group replaces secp256k1. There are tests of several functions in which a small group replaces secp256k1.
These tests are _exhaustive_ since they provide all elements and scalars of the small group as input arguments (see [src/tests_exhaustive.c](src/tests_exhaustive.c)). These tests are *exhaustive* since they provide all elements and scalars of the small group as input arguments (see [src/tests_exhaustive.c](src/tests_exhaustive.c)).
### Benchmarks ### Benchmarks

130
external/secp256k1/README.md vendored
View File

@@ -1,4 +1,5 @@
# libsecp256k1 libsecp256k1
============
![Dependencies: None](https://img.shields.io/badge/dependencies-none-success) ![Dependencies: None](https://img.shields.io/badge/dependencies-none-success)
[![irc.libera.chat #secp256k1](https://img.shields.io/badge/irc.libera.chat-%23secp256k1-success)](https://web.libera.chat/#secp256k1) [![irc.libera.chat #secp256k1](https://img.shields.io/badge/irc.libera.chat-%23secp256k1-success)](https://web.libera.chat/#secp256k1)
@@ -8,59 +9,60 @@ High-performance high-assurance C library for digital signatures and other crypt
This library is intended to be the highest quality publicly available library for cryptography on the secp256k1 curve. However, the primary focus of its development has been for usage in the Bitcoin system and usage unlike Bitcoin's may be less well tested, verified, or suffer from a less well thought out interface. Correct usage requires some care and consideration that the library is fit for your application's purpose. This library is intended to be the highest quality publicly available library for cryptography on the secp256k1 curve. However, the primary focus of its development has been for usage in the Bitcoin system and usage unlike Bitcoin's may be less well tested, verified, or suffer from a less well thought out interface. Correct usage requires some care and consideration that the library is fit for your application's purpose.
Features: Features:
* secp256k1 ECDSA signing/verification and key generation.
* Additive and multiplicative tweaking of secret/public keys.
* Serialization/parsing of secret keys, public keys, signatures.
* Constant time, constant memory access signing and public key generation.
* Derandomized ECDSA (via RFC6979 or with a caller provided function.)
* Very efficient implementation.
* Suitable for embedded systems.
* No runtime dependencies.
* Optional module for public key recovery.
* Optional module for ECDH key exchange.
* Optional module for Schnorr signatures according to [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
* Optional module for ElligatorSwift key exchange according to [BIP-324](https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki).
* Optional module for MuSig2 Schnorr multi-signatures according to [BIP-327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki).
- secp256k1 ECDSA signing/verification and key generation. Implementation details
- Additive and multiplicative tweaking of secret/public keys. ----------------------
- Serialization/parsing of secret keys, public keys, signatures.
- Constant time, constant memory access signing and public key generation.
- Derandomized ECDSA (via RFC6979 or with a caller provided function.)
- Very efficient implementation.
- Suitable for embedded systems.
- No runtime dependencies.
- Optional module for public key recovery.
- Optional module for ECDH key exchange.
- Optional module for Schnorr signatures according to [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
- Optional module for ElligatorSwift key exchange according to [BIP-324](https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki).
- Optional module for MuSig2 Schnorr multi-signatures according to [BIP-327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki).
## Implementation details * General
* No runtime heap allocation.
* Extensive testing infrastructure.
* Structured to facilitate review and analysis.
* Intended to be portable to any system with a C89 compiler and uint64_t support.
* No use of floating types.
* Expose only higher level interfaces to minimize the API surface and improve application security. ("Be difficult to use insecurely.")
* Field operations
* Optimized implementation of arithmetic modulo the curve's field size (2^256 - 0x1000003D1).
* Using 5 52-bit limbs
* Using 10 26-bit limbs (including hand-optimized assembly for 32-bit ARM, by Wladimir J. van der Laan).
* This is an experimental feature that has not received enough scrutiny to satisfy the standard of quality of this library but is made available for testing and review by the community.
* Scalar operations
* Optimized implementation without data-dependent branches of arithmetic modulo the curve's order.
* Using 4 64-bit limbs (relying on __int128 support in the compiler).
* Using 8 32-bit limbs.
* Modular inverses (both field elements and scalars) based on [safegcd](https://gcd.cr.yp.to/index.html) with some modifications, and a variable-time variant (by Peter Dettman).
* Group operations
* Point addition formula specifically simplified for the curve equation (y^2 = x^3 + 7).
* Use addition between points in Jacobian and affine coordinates where possible.
* Use a unified addition/doubling formula where necessary to avoid data-dependent branches.
* Point/x comparison without a field inversion by comparison in the Jacobian coordinate space.
* Point multiplication for verification (a*P + b*G).
* Use wNAF notation for point multiplicands.
* Use a much larger window for multiples of G, using precomputed multiples.
* Use Shamir's trick to do the multiplication with the public key and the generator simultaneously.
* Use secp256k1's efficiently-computable endomorphism to split the P multiplicand into 2 half-sized ones.
* Point multiplication for signing
* Use a precomputed table of multiples of powers of 16 multiplied with the generator, so general multiplication becomes a series of additions.
* Intended to be completely free of timing sidechannels for secret-key operations (on reasonable hardware/toolchains)
* Access the table with branch-free conditional moves so memory access is uniform.
* No data-dependent branches
* Optional runtime blinding which attempts to frustrate differential power analysis.
* The precomputed tables add and eventually subtract points for which no known scalar (secret key) is known, preventing even an attacker with control over the secret key used to control the data internally.
- General Building with Autotools
- No runtime heap allocation. -----------------------
- Extensive testing infrastructure.
- Structured to facilitate review and analysis.
- Intended to be portable to any system with a C89 compiler and uint64_t support.
- No use of floating types.
- Expose only higher level interfaces to minimize the API surface and improve application security. ("Be difficult to use insecurely.")
- Field operations
- Optimized implementation of arithmetic modulo the curve's field size (2^256 - 0x1000003D1).
- Using 5 52-bit limbs
- Using 10 26-bit limbs (including hand-optimized assembly for 32-bit ARM, by Wladimir J. van der Laan).
- This is an experimental feature that has not received enough scrutiny to satisfy the standard of quality of this library but is made available for testing and review by the community.
- Scalar operations
- Optimized implementation without data-dependent branches of arithmetic modulo the curve's order.
- Using 4 64-bit limbs (relying on \_\_int128 support in the compiler).
- Using 8 32-bit limbs.
- Modular inverses (both field elements and scalars) based on [safegcd](https://gcd.cr.yp.to/index.html) with some modifications, and a variable-time variant (by Peter Dettman).
- Group operations
- Point addition formula specifically simplified for the curve equation (y^2 = x^3 + 7).
- Use addition between points in Jacobian and affine coordinates where possible.
- Use a unified addition/doubling formula where necessary to avoid data-dependent branches.
- Point/x comparison without a field inversion by comparison in the Jacobian coordinate space.
- Point multiplication for verification (a*P + b*G).
- Use wNAF notation for point multiplicands.
- Use a much larger window for multiples of G, using precomputed multiples.
- Use Shamir's trick to do the multiplication with the public key and the generator simultaneously.
- Use secp256k1's efficiently-computable endomorphism to split the P multiplicand into 2 half-sized ones.
- Point multiplication for signing
- Use a precomputed table of multiples of powers of 16 multiplied with the generator, so general multiplication becomes a series of additions.
- Intended to be completely free of timing sidechannels for secret-key operations (on reasonable hardware/toolchains)
- Access the table with branch-free conditional moves so memory access is uniform.
- No data-dependent branches
- Optional runtime blinding which attempts to frustrate differential power analysis.
- The precomputed tables add and eventually subtract points for which no known scalar (secret key) is known, preventing even an attacker with control over the secret key used to control the data internally.
## Building with Autotools
$ ./autogen.sh $ ./autogen.sh
$ ./configure $ ./configure
@@ -70,7 +72,8 @@ Features:
To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags. To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags.
## Building with CMake (experimental) Building with CMake (experimental)
----------------------------------
To maintain a pristine source tree, CMake encourages to perform an out-of-source build by using a separate dedicated build tree. To maintain a pristine source tree, CMake encourages to perform an out-of-source build by using a separate dedicated build tree.
@@ -106,19 +109,18 @@ In "Developer Command Prompt for VS 2022":
>cmake -G "Visual Studio 17 2022" -A x64 -S . -B build >cmake -G "Visual Studio 17 2022" -A x64 -S . -B build
>cmake --build build --config RelWithDebInfo >cmake --build build --config RelWithDebInfo
## Usage examples Usage examples
-----------
Usage examples can be found in the [examples](examples) directory. To compile them you need to configure with `--enable-examples`. Usage examples can be found in the [examples](examples) directory. To compile them you need to configure with `--enable-examples`.
* [ECDSA example](examples/ecdsa.c)
- [ECDSA example](examples/ecdsa.c) * [Schnorr signatures example](examples/schnorr.c)
- [Schnorr signatures example](examples/schnorr.c) * [Deriving a shared secret (ECDH) example](examples/ecdh.c)
- [Deriving a shared secret (ECDH) example](examples/ecdh.c) * [ElligatorSwift key exchange example](examples/ellswift.c)
- [ElligatorSwift key exchange example](examples/ellswift.c)
To compile the Schnorr signature and ECDH examples, you also need to configure with `--enable-module-schnorrsig` and `--enable-module-ecdh`. To compile the Schnorr signature and ECDH examples, you also need to configure with `--enable-module-schnorrsig` and `--enable-module-ecdh`.
## Benchmark Benchmark
------------
If configured with `--enable-benchmark` (which is the default), binaries for benchmarking the libsecp256k1 functions will be present in the root directory after the build. If configured with `--enable-benchmark` (which is the default), binaries for benchmarking the libsecp256k1 functions will be present in the root directory after the build.
To print the benchmark result to the command line: To print the benchmark result to the command line:
@@ -129,10 +131,12 @@ To create a CSV file for the benchmark result :
$ ./bench_name | sed '2d;s/ \{1,\}//g' > bench_name.csv $ ./bench_name | sed '2d;s/ \{1,\}//g' > bench_name.csv
## Reporting a vulnerability Reporting a vulnerability
------------
See [SECURITY.md](SECURITY.md) See [SECURITY.md](SECURITY.md)
## Contributing to libsecp256k1 Contributing to libsecp256k1
------------
See [CONTRIBUTING.md](CONTRIBUTING.md) See [CONTRIBUTING.md](CONTRIBUTING.md)

10
external/secp256k1/SECURITY.md vendored
View File

@@ -6,10 +6,10 @@ To report security issues send an email to secp256k1-security@bitcoincore.org (n
The following keys may be used to communicate sensitive information to developers: The following keys may be used to communicate sensitive information to developers:
| Name | Fingerprint | | Name | Fingerprint |
| ------------- | ------------------------------------------------- | |------|-------------|
| Pieter Wuille | 133E AC17 9436 F14A 5CF1 B794 860F EB80 4E66 9320 | | Pieter Wuille | 133E AC17 9436 F14A 5CF1 B794 860F EB80 4E66 9320 |
| Jonas Nick | 36C7 1A37 C9D9 88BD E825 08D9 B1A7 0E4F 8DCD 0366 | | Jonas Nick | 36C7 1A37 C9D9 88BD E825 08D9 B1A7 0E4F 8DCD 0366 |
| Tim Ruffing | 09E0 3F87 1092 E40E 106E 902B 33BC 86AB 80FF 5516 | | Tim Ruffing | 09E0 3F87 1092 E40E 106E 902B 33BC 86AB 80FF 5516 |
You can import a key by running the following command with that individual’s fingerprint: `gpg --keyserver hkps://keys.openpgp.org --recv-keys "<fingerprint>"` Ensure that you put quotes around fingerprints containing spaces. You can import a key by running the following command with that individual’s fingerprint: `gpg --keyserver hkps://keys.openpgp.org --recv-keys "<fingerprint>"` Ensure that you put quotes around fingerprints containing spaces.

410
external/secp256k1/doc/ellswift.md vendored
View File

@@ -5,17 +5,17 @@ construction in the
["SwiftEC: Shallue–van de Woestijne Indifferentiable Function To Elliptic Curves"](https://eprint.iacr.org/2022/759) ["SwiftEC: Shallue–van de Woestijne Indifferentiable Function To Elliptic Curves"](https://eprint.iacr.org/2022/759)
paper by Jorge Chávez-Saab, Francisco Rodríguez-Henríquez, and Mehdi Tibouchi. paper by Jorge Chávez-Saab, Francisco Rodríguez-Henríquez, and Mehdi Tibouchi.
- [1. Introduction](#1-introduction) * [1. Introduction](#1-introduction)
- [2. The decoding function](#2-the-decoding-function) * [2. The decoding function](#2-the-decoding-function)
- [2.1 Decoding for `secp256k1`](#21-decoding-for-secp256k1) + [2.1 Decoding for `secp256k1`](#21-decoding-for-secp256k1)
- [3. The encoding function](#3-the-encoding-function) * [3. The encoding function](#3-the-encoding-function)
- [3.1 Switching to _v, w_ coordinates](#31-switching-to-v-w-coordinates) + [3.1 Switching to *v, w* coordinates](#31-switching-to-v-w-coordinates)
- [3.2 Avoiding computing all inverses](#32-avoiding-computing-all-inverses) + [3.2 Avoiding computing all inverses](#32-avoiding-computing-all-inverses)
- [3.3 Finding the inverse](#33-finding-the-inverse) + [3.3 Finding the inverse](#33-finding-the-inverse)
- [3.4 Dealing with special cases](#34-dealing-with-special-cases) + [3.4 Dealing with special cases](#34-dealing-with-special-cases)
- [3.5 Encoding for `secp256k1`](#35-encoding-for-secp256k1) + [3.5 Encoding for `secp256k1`](#35-encoding-for-secp256k1)
- [4. Encoding and decoding full _(x, y)_ coordinates](#4-encoding-and-decoding-full-x-y-coordinates) * [4. Encoding and decoding full *(x, y)* coordinates](#4-encoding-and-decoding-full-x-y-coordinates)
- [4.1 Full _(x, y)_ coordinates for `secp256k1`](#41-full-x-y-coordinates-for-secp256k1) + [4.1 Full *(x, y)* coordinates for `secp256k1`](#41-full-x-y-coordinates-for-secp256k1)
## 1. Introduction ## 1. Introduction
@@ -34,14 +34,13 @@ are taken modulo $p$), and then evaluating $F_u(t)$, which for every $u$ and $t$
x-coordinate on the curve. The functions $F_u$ will be defined in [Section 2](#2-the-decoding-function). x-coordinate on the curve. The functions $F_u$ will be defined in [Section 2](#2-the-decoding-function).
**Encoding** a given $x$ coordinate is conceptually done as follows: **Encoding** a given $x$ coordinate is conceptually done as follows:
* Loop:
* Pick a uniformly random field element $u.$
* Compute the set $L = F_u^{-1}(x)$ of $t$ values for which $F_u(t) = x$, which may have up to *8* elements.
* With probability $1 - \dfrac{\\#L}{8}$, restart the loop.
* Select a uniformly random $t \in L$ and return $(u, t).$
- Loop: This is the *ElligatorSwift* algorithm, here given for just x-coordinates. An extension to full
- Pick a uniformly random field element $u.$
- Compute the set $L = F_u^{-1}(x)$ of $t$ values for which $F_u(t) = x$, which may have up to _8_ elements.
- With probability $1 - \dfrac{\\#L}{8}$, restart the loop.
- Select a uniformly random $t \in L$ and return $(u, t).$
This is the _ElligatorSwift_ algorithm, here given for just x-coordinates. An extension to full
$(x, y)$ points will be given in [Section 4](#4-encoding-and-decoding-full-x-y-coordinates). $(x, y)$ points will be given in [Section 4](#4-encoding-and-decoding-full-x-y-coordinates).
The algorithm finds a uniformly random $(u, t)$ among (almost all) those The algorithm finds a uniformly random $(u, t)$ among (almost all) those
for which $F_u(t) = x.$ Section 3.2 in the paper proves that the number of such encodings for for which $F_u(t) = x.$ Section 3.2 in the paper proves that the number of such encodings for
@@ -51,40 +50,37 @@ almost all x-coordinates on the curve (all but at most 39) is close to two times
## 2. The decoding function ## 2. The decoding function
First some definitions: First some definitions:
* $\mathbb{F}$ is the finite field of size $q$, of characteristic 5 or more, and $q \equiv 1 \mod 3.$
- $\mathbb{F}$ is the finite field of size $q$, of characteristic 5 or more, and $q \equiv 1 \mod 3.$ * For `secp256k1`, $q = 2^{256} - 2^{32} - 977$, which satisfies that requirement.
- For `secp256k1`, $q = 2^{256} - 2^{32} - 977$, which satisfies that requirement. * Let $E$ be the elliptic curve of points $(x, y) \in \mathbb{F}^2$ for which $y^2 = x^3 + ax + b$, with $a$ and $b$
- Let $E$ be the elliptic curve of points $(x, y) \in \mathbb{F}^2$ for which $y^2 = x^3 + ax + b$, with $a$ and $b$
public constants, for which $\Delta_E = -16(4a^3 + 27b^2)$ is a square, and at least one of $(-b \pm \sqrt{-3 \Delta_E} / 36)/2$ is a square. public constants, for which $\Delta_E = -16(4a^3 + 27b^2)$ is a square, and at least one of $(-b \pm \sqrt{-3 \Delta_E} / 36)/2$ is a square.
This implies that the order of $E$ is either odd, or a multiple of _4_. This implies that the order of $E$ is either odd, or a multiple of *4*.
If $a=0$, this condition is always fulfilled. If $a=0$, this condition is always fulfilled.
- For `secp256k1`, $a=0$ and $b=7.$ * For `secp256k1`, $a=0$ and $b=7.$
- Let the function $g(x) = x^3 + ax + b$, so the $E$ curve equation is also $y^2 = g(x).$ * Let the function $g(x) = x^3 + ax + b$, so the $E$ curve equation is also $y^2 = g(x).$
- Let the function $h(x) = 3x^3 + 4a.$ * Let the function $h(x) = 3x^3 + 4a.$
- Define $V$ as the set of solutions $(x_1, x_2, x_3, z)$ to $z^2 = g(x_1)g(x_2)g(x_3).$ * Define $V$ as the set of solutions $(x_1, x_2, x_3, z)$ to $z^2 = g(x_1)g(x_2)g(x_3).$
- Define $S_u$ as the set of solutions $(X, Y)$ to $X^2 + h(u)Y^2 = -g(u)$ and $Y \neq 0.$ * Define $S_u$ as the set of solutions $(X, Y)$ to $X^2 + h(u)Y^2 = -g(u)$ and $Y \neq 0.$
- $P_u$ is a function from $\mathbb{F}$ to $S_u$ that will be defined below. * $P_u$ is a function from $\mathbb{F}$ to $S_u$ that will be defined below.
- $\psi_u$ is a function from $S_u$ to $V$ that will be defined below. * $\psi_u$ is a function from $S_u$ to $V$ that will be defined below.
**Note**: In the paper: **Note**: In the paper:
* $F_u$ corresponds to $F_{0,u}$ there.
- $F_u$ corresponds to $F_{0,u}$ there. * $P_u(t)$ is called $P$ there.
- $P_u(t)$ is called $P$ there. * All $S_u$ sets together correspond to $S$ there.
- All $S_u$ sets together correspond to $S$ there. * All $\psi_u$ functions together (operating on elements of $S$) correspond to $\psi$ there.
- All $\psi_u$ functions together (operating on elements of $S$) correspond to $\psi$ there.
Note that for $V$, the left hand side of the equation $z^2$ is square, and thus the right Note that for $V$, the left hand side of the equation $z^2$ is square, and thus the right
hand must also be square. As multiplying non-squares results in a square in $\mathbb{F}$, hand must also be square. As multiplying non-squares results in a square in $\mathbb{F}$,
out of the three right-hand side factors an even number must be non-squares. out of the three right-hand side factors an even number must be non-squares.
This implies that exactly _1_ or exactly _3_ out of This implies that exactly *1* or exactly *3* out of
$\\{g(x_1), g(x_2), g(x_3)\\}$ must be square, and thus that for any $(x_1,x_2,x_3,z) \in V$, $\\{g(x_1), g(x_2), g(x_3)\\}$ must be square, and thus that for any $(x_1,x_2,x_3,z) \in V$,
at least one of $\\{x_1, x_2, x_3\\}$ must be a valid x-coordinate on $E.$ There is one exception at least one of $\\{x_1, x_2, x_3\\}$ must be a valid x-coordinate on $E.$ There is one exception
to this, namely when $z=0$, but even then one of the three values is a valid x-coordinate. to this, namely when $z=0$, but even then one of the three values is a valid x-coordinate.
**Define** the decoding function $F_u(t)$ as: **Define** the decoding function $F_u(t)$ as:
* Let $(x_1, x_2, x_3, z) = \psi_u(P_u(t)).$
- Let $(x_1, x_2, x_3, z) = \psi_u(P_u(t)).$ * Return the first element $x$ of $(x_3, x_2, x_1)$ which is a valid x-coordinate on $E$ (i.e., $g(x)$ is square).
- Return the first element $x$ of $(x_3, x_2, x_1)$ which is a valid x-coordinate on $E$ (i.e., $g(x)$ is square).
$P_u(t) = (X(u, t), Y(u, t))$, where: $P_u(t) = (X(u, t), Y(u, t))$, where:
@@ -102,13 +98,12 @@ Y(u, t) & = & \left\\{\begin{array}{ll}
$$ $$
$P_u(t)$ is defined: $P_u(t)$ is defined:
* For $a=0$, unless:
- For $a=0$, unless: * $u = 0$ or $t = 0$ (division by zero)
- $u = 0$ or $t = 0$ (division by zero) * $g(u) = -t^2$ (would give $Y=0$).
- $g(u) = -t^2$ (would give $Y=0$). * For $a \neq 0$, unless:
- For $a \neq 0$, unless: * $X_0(u) = 0$ or $h(u)t^2 = -1$ (division by zero)
- $X_0(u) = 0$ or $h(u)t^2 = -1$ (division by zero) * $Y_0(u) (1 - h(u)t^2) = 2X_0(u)t$ (would give $Y=0$).
- $Y_0(u) (1 - h(u)t^2) = 2X_0(u)t$ (would give $Y=0$).
The functions $X_0(u)$ and $Y_0(u)$ are defined in Appendix A of the paper, and depend on various properties of $E.$ The functions $X_0(u)$ and $Y_0(u)$ are defined in Appendix A of the paper, and depend on various properties of $E.$
@@ -128,22 +123,20 @@ $$
Put together and specialized for $a=0$ curves, decoding $(u, t)$ to an x-coordinate is: Put together and specialized for $a=0$ curves, decoding $(u, t)$ to an x-coordinate is:
**Define** $F_u(t)$ as: **Define** $F_u(t)$ as:
* Let $X = \dfrac{u^3 + b - t^2}{2t}.$
- Let $X = \dfrac{u^3 + b - t^2}{2t}.$ * Let $Y = \dfrac{X + t}{u\sqrt{-3}}.$
- Let $Y = \dfrac{X + t}{u\sqrt{-3}}.$ * Return the first $x$ in $(u + 4Y^2, \dfrac{-X}{2Y} - \dfrac{u}{2}, \dfrac{X}{2Y} - \dfrac{u}{2})$ for which $g(x)$ is square.
- Return the first $x$ in $(u + 4Y^2, \dfrac{-X}{2Y} - \dfrac{u}{2}, \dfrac{X}{2Y} - \dfrac{u}{2})$ for which $g(x)$ is square.
To make sure that every input decodes to a valid x-coordinate, we remap the inputs in case To make sure that every input decodes to a valid x-coordinate, we remap the inputs in case
$P_u$ is not defined (when $u=0$, $t=0$, or $g(u) = -t^2$): $P_u$ is not defined (when $u=0$, $t=0$, or $g(u) = -t^2$):
**Define** $F_u(t)$ as: **Define** $F_u(t)$ as:
* Let $u'=u$ if $u \neq 0$; $1$ otherwise (guaranteeing $u' \neq 0$).
- Let $u'=u$ if $u \neq 0$; $1$ otherwise (guaranteeing $u' \neq 0$). * Let $t'=t$ if $t \neq 0$; $1$ otherwise (guaranteeing $t' \neq 0$).
- Let $t'=t$ if $t \neq 0$; $1$ otherwise (guaranteeing $t' \neq 0$). * Let $t''=t'$ if $g(u') \neq -t'^2$; $2t'$ otherwise (guaranteeing $t'' \neq 0$ and $g(u') \neq -t''^2$).
- Let $t''=t'$ if $g(u') \neq -t'^2$; $2t'$ otherwise (guaranteeing $t'' \neq 0$ and $g(u') \neq -t''^2$). * Let $X = \dfrac{u'^3 + b - t''^2}{2t''}.$
- Let $X = \dfrac{u'^3 + b - t''^2}{2t''}.$ * Let $Y = \dfrac{X + t''}{u'\sqrt{-3}}.$
- Let $Y = \dfrac{X + t''}{u'\sqrt{-3}}.$ * Return the first $x$ in $(u' + 4Y^2, \dfrac{-X}{2Y} - \dfrac{u'}{2}, \dfrac{X}{2Y} - \dfrac{u'}{2})$ for which $x^3 + b$ is square.
- Return the first $x$ in $(u' + 4Y^2, \dfrac{-X}{2Y} - \dfrac{u'}{2}, \dfrac{X}{2Y} - \dfrac{u'}{2})$ for which $x^3 + b$ is square.
The choices here are not strictly necessary. Just returning a fixed constant in any of the undefined cases would suffice, The choices here are not strictly necessary. Just returning a fixed constant in any of the undefined cases would suffice,
but the approach here is simple enough and gives fairly uniform output even in these cases. but the approach here is simple enough and gives fairly uniform output even in these cases.
@@ -157,11 +150,10 @@ in `secp256k1_ellswift_xswiftec_var` (which outputs the actual x-coordinate).
## 3. The encoding function ## 3. The encoding function
To implement $F_u^{-1}(x)$, the function to find the set of inverses $t$ for which $F_u(t) = x$, we have to reverse the process: To implement $F_u^{-1}(x)$, the function to find the set of inverses $t$ for which $F_u(t) = x$, we have to reverse the process:
* Find all the $(X, Y) \in S_u$ that could have given rise to $x$, through the $x_1$, $x_2$, or $x_3$ formulas in $\psi_u.$
- Find all the $(X, Y) \in S_u$ that could have given rise to $x$, through the $x_1$, $x_2$, or $x_3$ formulas in $\psi_u.$ * Map those $(X, Y)$ solutions to $t$ values using $P_u^{-1}(X, Y).$
- Map those $(X, Y)$ solutions to $t$ values using $P_u^{-1}(X, Y).$ * For each of the found $t$ values, verify that $F_u(t) = x.$
- For each of the found $t$ values, verify that $F_u(t) = x.$ * Return the remaining $t$ values.
- Return the remaining $t$ values.
The function $P_u^{-1}$, which finds $t$ given $(X, Y) \in S_u$, is significantly simpler than $P_u:$ The function $P_u^{-1}$, which finds $t$ given $(X, Y) \in S_u$, is significantly simpler than $P_u:$
@@ -193,14 +185,13 @@ precedence over both. Because of this, the $g(-u-x)$ being square test for $x_1$
values round-trip back to the input $x$ correctly. This is the reason for choosing the $(x_3, x_2, x_1)$ precedence order in the decoder; values round-trip back to the input $x$ correctly. This is the reason for choosing the $(x_3, x_2, x_1)$ precedence order in the decoder;
any order which does not place $x_3$ first requires more complicated round-trip checks in the encoder. any order which does not place $x_3$ first requires more complicated round-trip checks in the encoder.
### 3.1 Switching to _v, w_ coordinates ### 3.1 Switching to *v, w* coordinates
Before working out the formulas for all this, we switch to different variables for $S_u.$ Let $v = (X/Y - u)/2$, and Before working out the formulas for all this, we switch to different variables for $S_u.$ Let $v = (X/Y - u)/2$, and
$w = 2Y.$ Or in the other direction, $X = w(u/2 + v)$ and $Y = w/2:$ $w = 2Y.$ Or in the other direction, $X = w(u/2 + v)$ and $Y = w/2:$
* $S_u'$ becomes the set of $(v, w)$ for which $w^2 (u^2 + uv + v^2 + a) = -g(u)$ and $w \neq 0.$
- $S_u'$ becomes the set of $(v, w)$ for which $w^2 (u^2 + uv + v^2 + a) = -g(u)$ and $w \neq 0.$ * For $a=0$ curves, $P_u^{-1}$ can be stated for $(v,w)$ as $P_u^{'-1}(v, w) = w\left(\frac{\sqrt{-3}-1}{2}u - v\right).$
- For $a=0$ curves, $P_u^{-1}$ can be stated for $(v,w)$ as $P_u^{'-1}(v, w) = w\left(\frac{\sqrt{-3}-1}{2}u - v\right).$ * $\psi_u$ can be stated for $(v, w)$ as $\psi_u'(v, w) = (x_1, x_2, x_3, z)$, where
- $\psi_u$ can be stated for $(v, w)$ as $\psi_u'(v, w) = (x_1, x_2, x_3, z)$, where
$$ $$
\begin{array}{lcl} \begin{array}{lcl}
@@ -213,37 +204,34 @@ $$
We can now write the expressions for finding $(v, w)$ given $x$ explicitly, by solving each of the $\\{x_1, x_2, x_3\\}$ We can now write the expressions for finding $(v, w)$ given $x$ explicitly, by solving each of the $\\{x_1, x_2, x_3\\}$
expressions for $v$ or $w$, and using the $S_u'$ equation to find the other variable: expressions for $v$ or $w$, and using the $S_u'$ equation to find the other variable:
* Assuming $x = x_1$, we find $v = x$ and $w = \pm\sqrt{-g(u)/(u^2 + uv + v^2 + a)}$ (two solutions).
- Assuming $x = x_1$, we find $v = x$ and $w = \pm\sqrt{-g(u)/(u^2 + uv + v^2 + a)}$ (two solutions). * Assuming $x = x_2$, we find $v = -u-x$ and $w = \pm\sqrt{-g(u)/(u^2 + uv + v^2 + a)}$ (two solutions).
- Assuming $x = x_2$, we find $v = -u-x$ and $w = \pm\sqrt{-g(u)/(u^2 + uv + v^2 + a)}$ (two solutions). * Assuming $x = x_3$, we find $w = \pm\sqrt{x-u}$ and $v = -u/2 \pm \sqrt{-w^2(4g(u) + w^2h(u))}/(2w^2)$ (four solutions).
- Assuming $x = x_3$, we find $w = \pm\sqrt{x-u}$ and $v = -u/2 \pm \sqrt{-w^2(4g(u) + w^2h(u))}/(2w^2)$ (four solutions).
### 3.2 Avoiding computing all inverses ### 3.2 Avoiding computing all inverses
The _ElligatorSwift_ algorithm as stated in Section 1 requires the computation of $L = F_u^{-1}(x)$ (the The *ElligatorSwift* algorithm as stated in Section 1 requires the computation of $L = F_u^{-1}(x)$ (the
set of all $t$ such that $(u, t)$ decode to $x$) in full. This is unnecessary. set of all $t$ such that $(u, t)$ decode to $x$) in full. This is unnecessary.
Observe that the procedure of restarting with probability $(1 - \frac{\\#L}{8})$ and otherwise returning a Observe that the procedure of restarting with probability $(1 - \frac{\\#L}{8})$ and otherwise returning a
uniformly random element from $L$ is actually equivalent to always padding $L$ with $\bot$ values up to length 8, uniformly random element from $L$ is actually equivalent to always padding $L$ with $\bot$ values up to length 8,
picking a uniformly random element from that, restarting whenever $\bot$ is picked: picking a uniformly random element from that, restarting whenever $\bot$ is picked:
**Define** _ElligatorSwift(x)_ as: **Define** *ElligatorSwift(x)* as:
* Loop:
- Loop: * Pick a uniformly random field element $u.$
- Pick a uniformly random field element $u.$ * Compute the set $L = F_u^{-1}(x).$
- Compute the set $L = F_u^{-1}(x).$ * Let $T$ be the 8-element vector consisting of the elements of $L$, plus $8 - \\#L$ times $\\{\bot\\}.$
- Let $T$ be the 8-element vector consisting of the elements of $L$, plus $8 - \\#L$ times $\\{\bot\\}.$ * Select a uniformly random $t \in T.$
- Select a uniformly random $t \in T.$ * If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
- If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
Now notice that the order of elements in $T$ does not matter, as all we do is pick a uniformly Now notice that the order of elements in $T$ does not matter, as all we do is pick a uniformly
random element in it, so we do not need to have all $\bot$ values at the end. random element in it, so we do not need to have all $\bot$ values at the end.
As we have 8 distinct formulas for finding $(v, w)$ (taking the variants due to $\pm$ into account), As we have 8 distinct formulas for finding $(v, w)$ (taking the variants due to $\pm$ into account),
we can associate every index in $T$ with exactly one of those formulas, making sure that: we can associate every index in $T$ with exactly one of those formulas, making sure that:
* Formulas that yield no solutions (due to division by zero or non-existing square roots) or invalid solutions are made to return $\bot.$
- Formulas that yield no solutions (due to division by zero or non-existing square roots) or invalid solutions are made to return $\bot.$ * For the $x_1$ and $x_2$ cases, if $g(-u-x)$ is a square, $\bot$ is returned instead (the round-trip check).
- For the $x_1$ and $x_2$ cases, if $g(-u-x)$ is a square, $\bot$ is returned instead (the round-trip check). * In case multiple formulas would return the same non- $\bot$ result, all but one of those must be turned into $\bot$ to avoid biasing those.
- In case multiple formulas would return the same non- $\bot$ result, all but one of those must be turned into $\bot$ to avoid biasing those.
The last condition above only occurs with negligible probability for cryptographically-sized curves, but is interesting The last condition above only occurs with negligible probability for cryptographically-sized curves, but is interesting
to take into account as it allows exhaustive testing in small groups. See [Section 3.4](#34-dealing-with-special-cases) to take into account as it allows exhaustive testing in small groups. See [Section 3.4](#34-dealing-with-special-cases)
@@ -252,13 +240,12 @@ for an analysis of all the negligible cases.
If we define $T = (G_{0,u}(x), G_{1,u}(x), \ldots, G_{7,u}(x))$, with each $G_{i,u}$ matching one of the formulas, If we define $T = (G_{0,u}(x), G_{1,u}(x), \ldots, G_{7,u}(x))$, with each $G_{i,u}$ matching one of the formulas,
the loop can be simplified to only compute one of the inverses instead of all of them: the loop can be simplified to only compute one of the inverses instead of all of them:
**Define** _ElligatorSwift(x)_ as: **Define** *ElligatorSwift(x)* as:
* Loop:
- Loop: * Pick a uniformly random field element $u.$
- Pick a uniformly random field element $u.$ * Pick a uniformly random integer $c$ in $[0,8).$
- Pick a uniformly random integer $c$ in $[0,8).$ * Let $t = G_{c,u}(x).$
- Let $t = G_{c,u}(x).$ * If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
- If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
This is implemented in `secp256k1_ellswift_xelligatorswift_var`. This is implemented in `secp256k1_ellswift_xelligatorswift_var`.
@@ -269,19 +256,18 @@ Those are then repeated as $c=4$ through $c=7$ for the other sign of $w$ (noting
Ignoring the negligible cases, we get: Ignoring the negligible cases, we get:
**Define** $G_{c,u}(x)$ as: **Define** $G_{c,u}(x)$ as:
* If $c \in \\{0, 1, 4, 5\\}$ (for $x_1$ and $x_2$ formulas):
- If $c \in \\{0, 1, 4, 5\\}$ (for $x_1$ and $x_2$ formulas): * If $g(-u-x)$ is square, return $\bot$ (as $x_3$ would be valid and take precedence).
- If $g(-u-x)$ is square, return $\bot$ (as $x_3$ would be valid and take precedence). * If $c \in \\{0, 4\\}$ (the $x_1$ formula) let $v = x$, otherwise let $v = -u-x$ (the $x_2$ formula)
- If $c \in \\{0, 4\\}$ (the $x_1$ formula) let $v = x$, otherwise let $v = -u-x$ (the $x_2$ formula) * Let $s = -g(u)/(u^2 + uv + v^2 + a)$ (using $s = w^2$ in what follows).
- Let $s = -g(u)/(u^2 + uv + v^2 + a)$ (using $s = w^2$ in what follows). * Otherwise, when $c \in \\{2, 3, 6, 7\\}$ (for $x_3$ formulas):
- Otherwise, when $c \in \\{2, 3, 6, 7\\}$ (for $x_3$ formulas): * Let $s = x-u.$
- Let $s = x-u.$ * Let $r = \sqrt{-s(4g(u) + sh(u))}.$
- Let $r = \sqrt{-s(4g(u) + sh(u))}.$ * Let $v = (r/s - u)/2$ if $c \in \\{3, 7\\}$; $(-r/s - u)/2$ otherwise.
- Let $v = (r/s - u)/2$ if $c \in \\{3, 7\\}$; $(-r/s - u)/2$ otherwise. * Let $w = \sqrt{s}.$
- Let $w = \sqrt{s}.$ * Depending on $c:$
- Depending on $c:$ * If $c \in \\{0, 1, 2, 3\\}:$ return $P_u^{'-1}(v, w).$
- If $c \in \\{0, 1, 2, 3\\}:$ return $P_u^{'-1}(v, w).$ * If $c \in \\{4, 5, 6, 7\\}:$ return $P_u^{'-1}(v, -w).$
- If $c \in \\{4, 5, 6, 7\\}:$ return $P_u^{'-1}(v, -w).$
Whenever a square root of a non-square is taken, $\bot$ is returned; for both square roots this happens with roughly Whenever a square root of a non-square is taken, $\bot$ is returned; for both square roots this happens with roughly
50% on random inputs. Similarly, when a division by 0 would occur, $\bot$ is returned as well; this will only happen 50% on random inputs. Similarly, when a division by 0 would occur, $\bot$ is returned as well; this will only happen
@@ -298,21 +284,20 @@ transformation. Furthermore, that transformation has no effect on $s$ in the fir
as $u^2 + ux + x^2 + a = u^2 + u(-u-x) + (-u-x)^2 + a.$ Thus we can extract it out and move it down: as $u^2 + ux + x^2 + a = u^2 + u(-u-x) + (-u-x)^2 + a.$ Thus we can extract it out and move it down:
**Define** $G_{c,u}(x)$ as: **Define** $G_{c,u}(x)$ as:
* If $c \in \\{0, 1, 4, 5\\}:$
- If $c \in \\{0, 1, 4, 5\\}:$ * If $g(-u-x)$ is square, return $\bot.$
- If $g(-u-x)$ is square, return $\bot.$ * Let $s = -g(u)/(u^2 + ux + x^2 + a).$
- Let $s = -g(u)/(u^2 + ux + x^2 + a).$ * Let $v = x.$
- Let $v = x.$ * Otherwise, when $c \in \\{2, 3, 6, 7\\}:$
- Otherwise, when $c \in \\{2, 3, 6, 7\\}:$ * Let $s = x-u.$
- Let $s = x-u.$ * Let $r = \sqrt{-s(4g(u) + sh(u))}.$
- Let $r = \sqrt{-s(4g(u) + sh(u))}.$ * Let $v = (r/s - u)/2.$
- Let $v = (r/s - u)/2.$ * Let $w = \sqrt{s}.$
- Let $w = \sqrt{s}.$ * Depending on $c:$
- Depending on $c:$ * If $c \in \\{0, 2\\}:$ return $P_u^{'-1}(v, w).$
- If $c \in \\{0, 2\\}:$ return $P_u^{'-1}(v, w).$ * If $c \in \\{1, 3\\}:$ return $P_u^{'-1}(-u-v, w).$
- If $c \in \\{1, 3\\}:$ return $P_u^{'-1}(-u-v, w).$ * If $c \in \\{4, 6\\}:$ return $P_u^{'-1}(v, -w).$
- If $c \in \\{4, 6\\}:$ return $P_u^{'-1}(v, -w).$ * If $c \in \\{5, 7\\}:$ return $P_u^{'-1}(-u-v, -w).$
- If $c \in \\{5, 7\\}:$ return $P_u^{'-1}(-u-v, -w).$
This shows there will always be exactly 0, 4, or 8 $t$ values for a given $(u, x)$ input. This shows there will always be exactly 0, 4, or 8 $t$ values for a given $(u, x)$ input.
There can be 0, 1, or 2 $(v, w)$ pairs before invoking $P_u^{'-1}$, and each results in 4 distinct $t$ values. There can be 0, 1, or 2 $(v, w)$ pairs before invoking $P_u^{'-1}$, and each results in 4 distinct $t$ values.
@@ -325,60 +310,58 @@ we analyse them here. They generally fall into two categories: cases in which th
do not decode back to $x$ (or at least cannot guarantee that they do), and cases in which the encoder might produce the same do not decode back to $x$ (or at least cannot guarantee that they do), and cases in which the encoder might produce the same
$t$ value for multiple $c$ inputs (thereby biasing that encoding): $t$ value for multiple $c$ inputs (thereby biasing that encoding):
- In the branch for $x_1$ and $x_2$ (where $c \in \\{0, 1, 4, 5\\}$): * In the branch for $x_1$ and $x_2$ (where $c \in \\{0, 1, 4, 5\\}$):
- When $g(u) = 0$, we would have $s=w=Y=0$, which is not on $S_u.$ This is only possible on even-ordered curves. * When $g(u) = 0$, we would have $s=w=Y=0$, which is not on $S_u.$ This is only possible on even-ordered curves.
Excluding this also removes the one condition under which the simplified check for $x_3$ on the curve Excluding this also removes the one condition under which the simplified check for $x_3$ on the curve
fails (namely when $g(x_1)=g(x_2)=0$ but $g(x_3)$ is not square). fails (namely when $g(x_1)=g(x_2)=0$ but $g(x_3)$ is not square).
This does exclude some valid encodings: when both $g(u)=0$ and $u^2+ux+x^2+a=0$ (also implying $g(x)=0$), This does exclude some valid encodings: when both $g(u)=0$ and $u^2+ux+x^2+a=0$ (also implying $g(x)=0$),
the $S_u'$ equation degenerates to $0 = 0$, and many valid $t$ values may exist. Yet, these cannot be targeted uniformly by the the $S_u'$ equation degenerates to $0 = 0$, and many valid $t$ values may exist. Yet, these cannot be targeted uniformly by the
encoder anyway as there will generally be more than 8. encoder anyway as there will generally be more than 8.
- When $g(x) = 0$, the same $t$ would be produced as in the $x_3$ branch (where $c \in \\{2, 3, 6, 7\\}$) which we give precedence * When $g(x) = 0$, the same $t$ would be produced as in the $x_3$ branch (where $c \in \\{2, 3, 6, 7\\}$) which we give precedence
as it can deal with $g(u)=0$. as it can deal with $g(u)=0$.
This is again only possible on even-ordered curves. This is again only possible on even-ordered curves.
- In the branch for $x_3$ (where $c \in \\{2, 3, 6, 7\\}$): * In the branch for $x_3$ (where $c \in \\{2, 3, 6, 7\\}$):
- When $s=0$, a division by zero would occur. * When $s=0$, a division by zero would occur.
- When $v = -u-v$ and $c \in \\{3, 7\\}$, the same $t$ would be returned as in the $c \in \\{2, 6\\}$ cases. * When $v = -u-v$ and $c \in \\{3, 7\\}$, the same $t$ would be returned as in the $c \in \\{2, 6\\}$ cases.
It is equivalent to checking whether $r=0$. It is equivalent to checking whether $r=0$.
This cannot occur in the $x_1$ or $x_2$ branches, as it would trigger the $g(-u-x)$ is square condition. This cannot occur in the $x_1$ or $x_2$ branches, as it would trigger the $g(-u-x)$ is square condition.
A similar concern for $w = -w$ does not exist, as $w=0$ is already impossible in both branches: in the first A similar concern for $w = -w$ does not exist, as $w=0$ is already impossible in both branches: in the first
it requires $g(u)=0$ which is already outlawed on even-ordered curves and impossible on others; in the second it would trigger division by zero. it requires $g(u)=0$ which is already outlawed on even-ordered curves and impossible on others; in the second it would trigger division by zero.
- Curve-specific special cases also exist that need to be rejected, because they result in $(u,t)$ which is invalid to the decoder, or because of division by zero in the encoder: * Curve-specific special cases also exist that need to be rejected, because they result in $(u,t)$ which is invalid to the decoder, or because of division by zero in the encoder:
- For $a=0$ curves, when $u=0$ or when $t=0$. The latter can only be reached by the encoder when $g(u)=0$, which requires an even-ordered curve. * For $a=0$ curves, when $u=0$ or when $t=0$. The latter can only be reached by the encoder when $g(u)=0$, which requires an even-ordered curve.
- For $a \neq 0$ curves, when $X_0(u)=0$, when $h(u)t^2 = -1$, or when $w(u + 2v) = 2X_0(u)$ while also either $w \neq 2Y_0(u)$ or $h(u)=0$. * For $a \neq 0$ curves, when $X_0(u)=0$, when $h(u)t^2 = -1$, or when $w(u + 2v) = 2X_0(u)$ while also either $w \neq 2Y_0(u)$ or $h(u)=0$.
**Define** a version of $G_{c,u}(x)$ which deals with all these cases: **Define** a version of $G_{c,u}(x)$ which deals with all these cases:
* If $a=0$ and $u=0$, return $\bot.$
- If $a=0$ and $u=0$, return $\bot.$ * If $a \neq 0$ and $X_0(u)=0$, return $\bot.$
- If $a \neq 0$ and $X_0(u)=0$, return $\bot.$ * If $c \in \\{0, 1, 4, 5\\}:$
- If $c \in \\{0, 1, 4, 5\\}:$ * If $g(u) = 0$ or $g(x) = 0$, return $\bot$ (even curves only).
- If $g(u) = 0$ or $g(x) = 0$, return $\bot$ (even curves only). * If $g(-u-x)$ is square, return $\bot.$
- If $g(-u-x)$ is square, return $\bot.$ * Let $s = -g(u)/(u^2 + ux + x^2 + a)$ (cannot cause division by zero).
- Let $s = -g(u)/(u^2 + ux + x^2 + a)$ (cannot cause division by zero). * Let $v = x.$
- Let $v = x.$ * Otherwise, when $c \in \\{2, 3, 6, 7\\}:$
- Otherwise, when $c \in \\{2, 3, 6, 7\\}:$ * Let $s = x-u.$
- Let $s = x-u.$ * Let $r = \sqrt{-s(4g(u) + sh(u))}$; return $\bot$ if not square.
- Let $r = \sqrt{-s(4g(u) + sh(u))}$; return $\bot$ if not square. * If $c \in \\{3, 7\\}$ and $r=0$, return $\bot.$
- If $c \in \\{3, 7\\}$ and $r=0$, return $\bot.$ * If $s = 0$, return $\bot.$
- If $s = 0$, return $\bot.$ * Let $v = (r/s - u)/2.$
- Let $v = (r/s - u)/2.$ * Let $w = \sqrt{s}$; return $\bot$ if not square.
- Let $w = \sqrt{s}$; return $\bot$ if not square. * If $a \neq 0$ and $w(u+2v) = 2X_0(u)$ and either $w \neq 2Y_0(u)$ or $h(u) = 0$, return $\bot.$
- If $a \neq 0$ and $w(u+2v) = 2X_0(u)$ and either $w \neq 2Y_0(u)$ or $h(u) = 0$, return $\bot.$ * Depending on $c:$
- Depending on $c:$ * If $c \in \\{0, 2\\}$, let $t = P_u^{'-1}(v, w).$
- If $c \in \\{0, 2\\}$, let $t = P_u^{'-1}(v, w).$ * If $c \in \\{1, 3\\}$, let $t = P_u^{'-1}(-u-v, w).$
- If $c \in \\{1, 3\\}$, let $t = P_u^{'-1}(-u-v, w).$ * If $c \in \\{4, 6\\}$, let $t = P_u^{'-1}(v, -w).$
- If $c \in \\{4, 6\\}$, let $t = P_u^{'-1}(v, -w).$ * If $c \in \\{5, 7\\}$, let $t = P_u^{'-1}(-u-v, -w).$
- If $c \in \\{5, 7\\}$, let $t = P_u^{'-1}(-u-v, -w).$ * If $a=0$ and $t=0$, return $\bot$ (even curves only).
- If $a=0$ and $t=0$, return $\bot$ (even curves only). * If $a \neq 0$ and $h(u)t^2 = -1$, return $\bot.$
- If $a \neq 0$ and $h(u)t^2 = -1$, return $\bot.$ * Return $t.$
- Return $t.$
Given any $u$, using this algorithm over all $x$ and $c$ values, every $t$ value will be reached exactly once, Given any $u$, using this algorithm over all $x$ and $c$ values, every $t$ value will be reached exactly once,
for an $x$ for which $F_u(t) = x$ holds, except for these cases that will not be reached: for an $x$ for which $F_u(t) = x$ holds, except for these cases that will not be reached:
* All cases where $P_u(t)$ is not defined:
- All cases where $P_u(t)$ is not defined: * For $a=0$ curves, when $u=0$, $t=0$, or $g(u) = -t^2.$
- For $a=0$ curves, when $u=0$, $t=0$, or $g(u) = -t^2.$ * For $a \neq 0$ curves, when $h(u)t^2 = -1$, $X_0(u) = 0$, or $Y_0(u) (1 - h(u) t^2) = 2X_0(u)t.$
- For $a \neq 0$ curves, when $h(u)t^2 = -1$, $X_0(u) = 0$, or $Y_0(u) (1 - h(u) t^2) = 2X_0(u)t.$ * When $g(u)=0$, the potentially many $t$ values that decode to an $x$ satisfying $g(x)=0$ using the $x_2$ formula. These were excluded by the $g(u)=0$ condition in the $c \in \\{0, 1, 4, 5\\}$ branch.
- When $g(u)=0$, the potentially many $t$ values that decode to an $x$ satisfying $g(x)=0$ using the $x_2$ formula. These were excluded by the $g(u)=0$ condition in the $c \in \\{0, 1, 4, 5\\}$ branch.
These cases form a negligible subset of all $(u, t)$ for cryptographically sized curves. These cases form a negligible subset of all $(u, t)$ for cryptographically sized curves.
@@ -387,42 +370,40 @@ These cases form a negligible subset of all $(u, t)$ for cryptographically sized
Specialized for odd-ordered $a=0$ curves: Specialized for odd-ordered $a=0$ curves:
**Define** $G_{c,u}(x)$ as: **Define** $G_{c,u}(x)$ as:
* If $u=0$, return $\bot.$
- If $u=0$, return $\bot.$ * If $c \in \\{0, 1, 4, 5\\}:$
- If $c \in \\{0, 1, 4, 5\\}:$ * If $(-u-x)^3 + b$ is square, return $\bot$
- If $(-u-x)^3 + b$ is square, return $\bot$ * Let $s = -(u^3 + b)/(u^2 + ux + x^2)$ (cannot cause division by 0).
- Let $s = -(u^3 + b)/(u^2 + ux + x^2)$ (cannot cause division by 0). * Let $v = x.$
- Let $v = x.$ * Otherwise, when $c \in \\{2, 3, 6, 7\\}:$
- Otherwise, when $c \in \\{2, 3, 6, 7\\}:$ * Let $s = x-u.$
- Let $s = x-u.$ * Let $r = \sqrt{-s(4(u^3 + b) + 3su^2)}$; return $\bot$ if not square.
- Let $r = \sqrt{-s(4(u^3 + b) + 3su^2)}$; return $\bot$ if not square. * If $c \in \\{3, 7\\}$ and $r=0$, return $\bot.$
- If $c \in \\{3, 7\\}$ and $r=0$, return $\bot.$ * If $s = 0$, return $\bot.$
- If $s = 0$, return $\bot.$ * Let $v = (r/s - u)/2.$
- Let $v = (r/s - u)/2.$ * Let $w = \sqrt{s}$; return $\bot$ if not square.
- Let $w = \sqrt{s}$; return $\bot$ if not square. * Depending on $c:$
- Depending on $c:$ * If $c \in \\{0, 2\\}:$ return $w(\frac{\sqrt{-3}-1}{2}u - v).$
- If $c \in \\{0, 2\\}:$ return $w(\frac{\sqrt{-3}-1}{2}u - v).$ * If $c \in \\{1, 3\\}:$ return $w(\frac{\sqrt{-3}+1}{2}u + v).$
- If $c \in \\{1, 3\\}:$ return $w(\frac{\sqrt{-3}+1}{2}u + v).$ * If $c \in \\{4, 6\\}:$ return $w(\frac{-\sqrt{-3}+1}{2}u + v).$
- If $c \in \\{4, 6\\}:$ return $w(\frac{-\sqrt{-3}+1}{2}u + v).$ * If $c \in \\{5, 7\\}:$ return $w(\frac{-\sqrt{-3}-1}{2}u - v).$
- If $c \in \\{5, 7\\}:$ return $w(\frac{-\sqrt{-3}-1}{2}u - v).$
This is implemented in `secp256k1_ellswift_xswiftec_inv_var`. This is implemented in `secp256k1_ellswift_xswiftec_inv_var`.
And the x-only ElligatorSwift encoding algorithm is still: And the x-only ElligatorSwift encoding algorithm is still:
**Define** _ElligatorSwift(x)_ as: **Define** *ElligatorSwift(x)* as:
* Loop:
- Loop: * Pick a uniformly random field element $u.$
- Pick a uniformly random field element $u.$ * Pick a uniformly random integer $c$ in $[0,8).$
- Pick a uniformly random integer $c$ in $[0,8).$ * Let $t = G_{c,u}(x).$
- Let $t = G_{c,u}(x).$ * If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
- If $t \neq \bot$, return $(u, t)$; restart loop otherwise.
Note that this logic does not take the remapped $u=0$, $t=0$, and $g(u) = -t^2$ cases into account; it just avoids them. Note that this logic does not take the remapped $u=0$, $t=0$, and $g(u) = -t^2$ cases into account; it just avoids them.
While it is not impossible to make the encoder target them, this would increase the maximum number of $t$ values for a given $(u, x)$ While it is not impossible to make the encoder target them, this would increase the maximum number of $t$ values for a given $(u, x)$
combination beyond 8, and thereby slow down the ElligatorSwift loop proportionally, for a negligible gain in uniformity. combination beyond 8, and thereby slow down the ElligatorSwift loop proportionally, for a negligible gain in uniformity.
## 4. Encoding and decoding full _(x, y)_ coordinates ## 4. Encoding and decoding full *(x, y)* coordinates
So far we have only addressed encoding and decoding x-coordinates, but in some cases an encoding So far we have only addressed encoding and decoding x-coordinates, but in some cases an encoding
for full points with $(x, y)$ coordinates is desirable. It is possible to encode this information for full points with $(x, y)$ coordinates is desirable. It is possible to encode this information
@@ -441,32 +422,30 @@ four distinct $P_u^{'-1}$ calls in the definition of $G_{u,c}.$
To encode the sign of $y$ in the sign of $Y:$ To encode the sign of $y$ in the sign of $Y:$
**Define** _Decode(u, t)_ for full $(x, y)$ as: **Define** *Decode(u, t)* for full $(x, y)$ as:
* Let $(X, Y) = P_u(t).$
- Let $(X, Y) = P_u(t).$ * Let $x$ be the first value in $(u + 4Y^2, \frac{-X}{2Y} - \frac{u}{2}, \frac{X}{2Y} - \frac{u}{2})$ for which $g(x)$ is square.
- Let $x$ be the first value in $(u + 4Y^2, \frac{-X}{2Y} - \frac{u}{2}, \frac{X}{2Y} - \frac{u}{2})$ for which $g(x)$ is square. * Let $y = \sqrt{g(x)}.$
- Let $y = \sqrt{g(x)}.$ * If $sign(y) = sign(Y)$, return $(x, y)$; otherwise return $(x, -y).$
- If $sign(y) = sign(Y)$, return $(x, y)$; otherwise return $(x, -y).$
And encoding would be done using a $G_{c,u}(x, y)$ function defined as: And encoding would be done using a $G_{c,u}(x, y)$ function defined as:
**Define** $G_{c,u}(x, y)$ as: **Define** $G_{c,u}(x, y)$ as:
* If $c \in \\{0, 1\\}:$
- If $c \in \\{0, 1\\}:$ * If $g(u) = 0$ or $g(x) = 0$, return $\bot$ (even curves only).
- If $g(u) = 0$ or $g(x) = 0$, return $\bot$ (even curves only). * If $g(-u-x)$ is square, return $\bot.$
- If $g(-u-x)$ is square, return $\bot.$ * Let $s = -g(u)/(u^2 + ux + x^2 + a)$ (cannot cause division by zero).
- Let $s = -g(u)/(u^2 + ux + x^2 + a)$ (cannot cause division by zero). * Let $v = x.$
- Let $v = x.$ * Otherwise, when $c \in \\{2, 3\\}:$
- Otherwise, when $c \in \\{2, 3\\}:$ * Let $s = x-u.$
- Let $s = x-u.$ * Let $r = \sqrt{-s(4g(u) + sh(u))}$; return $\bot$ if not square.
- Let $r = \sqrt{-s(4g(u) + sh(u))}$; return $\bot$ if not square. * If $c = 3$ and $r = 0$, return $\bot.$
- If $c = 3$ and $r = 0$, return $\bot.$ * Let $v = (r/s - u)/2.$
- Let $v = (r/s - u)/2.$ * Let $w = \sqrt{s}$; return $\bot$ if not square.
- Let $w = \sqrt{s}$; return $\bot$ if not square. * Let $w' = w$ if $sign(w/2) = sign(y)$; $-w$ otherwise.
- Let $w' = w$ if $sign(w/2) = sign(y)$; $-w$ otherwise. * Depending on $c:$
- Depending on $c:$ * If $c \in \\{0, 2\\}:$ return $P_u^{'-1}(v, w').$
- If $c \in \\{0, 2\\}:$ return $P_u^{'-1}(v, w').$ * If $c \in \\{1, 3\\}:$ return $P_u^{'-1}(-u-v, w').$
- If $c \in \\{1, 3\\}:$ return $P_u^{'-1}(-u-v, w').$
Note that $c$ now only ranges $[0,4)$, as the sign of $w'$ is decided based on that of $y$, rather than on $c.$ Note that $c$ now only ranges $[0,4)$, as the sign of $w'$ is decided based on that of $y$, rather than on $c.$
This change makes some valid encodings unreachable: when $y = 0$ and $sign(Y) \neq sign(0)$. This change makes some valid encodings unreachable: when $y = 0$ and $sign(Y) \neq sign(0)$.
@@ -475,23 +454,22 @@ In the above logic, $sign$ can be implemented in several ways, such as parity of
of the input field element (for prime-sized fields) or the quadratic residuosity (for fields where of the input field element (for prime-sized fields) or the quadratic residuosity (for fields where
$-1$ is not square). The choice does not matter, as long as it only takes on two possible values, and for $x \neq 0$ it holds that $sign(x) \neq sign(-x)$. $-1$ is not square). The choice does not matter, as long as it only takes on two possible values, and for $x \neq 0$ it holds that $sign(x) \neq sign(-x)$.
### 4.1 Full _(x, y)_ coordinates for `secp256k1` ### 4.1 Full *(x, y)* coordinates for `secp256k1`
For $a=0$ curves, there is another option. Note that for those, For $a=0$ curves, there is another option. Note that for those,
the $P_u(t)$ function translates negations of $t$ to negations of (both) $X$ and $Y.$ Thus, we can use $sign(t)$ to the $P_u(t)$ function translates negations of $t$ to negations of (both) $X$ and $Y.$ Thus, we can use $sign(t)$ to
encode the y-coordinate directly. Combined with the earlier remapping to guarantee all inputs land on the curve, we get encode the y-coordinate directly. Combined with the earlier remapping to guarantee all inputs land on the curve, we get
as decoder: as decoder:
**Define** _Decode(u, t)_ as: **Define** *Decode(u, t)* as:
* Let $u'=u$ if $u \neq 0$; $1$ otherwise.
- Let $u'=u$ if $u \neq 0$; $1$ otherwise. * Let $t'=t$ if $t \neq 0$; $1$ otherwise.
- Let $t'=t$ if $t \neq 0$; $1$ otherwise. * Let $t''=t'$ if $u'^3 + b + t'^2 \neq 0$; $2t'$ otherwise.
- Let $t''=t'$ if $u'^3 + b + t'^2 \neq 0$; $2t'$ otherwise. * Let $X = \dfrac{u'^3 + b - t''^2}{2t''}.$
- Let $X = \dfrac{u'^3 + b - t''^2}{2t''}.$ * Let $Y = \dfrac{X + t''}{u'\sqrt{-3}}.$
- Let $Y = \dfrac{X + t''}{u'\sqrt{-3}}.$ * Let $x$ be the first element of $(u' + 4Y^2, \frac{-X}{2Y} - \frac{u'}{2}, \frac{X}{2Y} - \frac{u'}{2})$ for which $g(x)$ is square.
- Let $x$ be the first element of $(u' + 4Y^2, \frac{-X}{2Y} - \frac{u'}{2}, \frac{X}{2Y} - \frac{u'}{2})$ for which $g(x)$ is square. * Let $y = \sqrt{g(x)}.$
- Let $y = \sqrt{g(x)}.$ * Return $(x, y)$ if $sign(y) = sign(t)$; $(x, -y)$ otherwise.
- Return $(x, y)$ if $sign(y) = sign(t)$; $(x, -y)$ otherwise.
This is implemented in `secp256k1_ellswift_swiftec_var`. The used $sign(x)$ function is the parity of $x$ when represented as in integer in $[0,q).$ This is implemented in `secp256k1_ellswift_swiftec_var`. The used $sign(x)$ function is the parity of $x$ when represented as in integer in $[0,q).$

3
external/secp256k1/doc/musig.md vendored
View File

@@ -1,4 +1,5 @@
# Notes on the musig module API Notes on the musig module API
===========================
The following sections contain additional notes on the API of the musig module (`include/secp256k1_musig.h`). The following sections contain additional notes on the API of the musig module (`include/secp256k1_musig.h`).
A usage example can be found in `examples/musig.c`. A usage example can be found in `examples/musig.c`.

40
external/secp256k1/doc/release-process.md vendored
View File

@@ -2,7 +2,7 @@
This document outlines the process for releasing versions of the form `$MAJOR.$MINOR.$PATCH`. This document outlines the process for releasing versions of the form `$MAJOR.$MINOR.$PATCH`.
We distinguish between two types of releases: _regular_ and _maintenance_ releases. We distinguish between two types of releases: *regular* and *maintenance* releases.
Regular releases are releases of a new major or minor version as well as patches of the most recent release. Regular releases are releases of a new major or minor version as well as patches of the most recent release.
Maintenance releases, on the other hand, are required for patches of older releases. Maintenance releases, on the other hand, are required for patches of older releases.
@@ -15,7 +15,6 @@ This process also assumes that there will be no minor releases for old major rel
We aim to cut a regular release every 3-4 months, approximately twice as frequent as major Bitcoin Core releases. Every second release should be published one month before the feature freeze of the next major Bitcoin Core release, allowing sufficient time to update the library in Core. We aim to cut a regular release every 3-4 months, approximately twice as frequent as major Bitcoin Core releases. Every second release should be published one month before the feature freeze of the next major Bitcoin Core release, allowing sufficient time to update the library in Core.
## Sanity checks ## Sanity checks
Perform these checks when reviewing the release PR (see below): Perform these checks when reviewing the release PR (see below):
1. Ensure `make distcheck` doesn't fail. 1. Ensure `make distcheck` doesn't fail.
@@ -43,15 +42,15 @@ Perform these checks when reviewing the release PR (see below):
## Regular release ## Regular release
1. Open a PR to the master branch with a commit (using message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that 1. Open a PR to the master branch with a commit (using message `"release: prepare for $MAJOR.$MINOR.$PATCH"`, for example) that
- finalizes the release notes in [CHANGELOG.md](../CHANGELOG.md) by * finalizes the release notes in [CHANGELOG.md](../CHANGELOG.md) by
- adding a section for the release (make sure that the version number is a link to a diff between the previous and new version), * adding a section for the release (make sure that the version number is a link to a diff between the previous and new version),
- removing the `[Unreleased]` section header, * removing the `[Unreleased]` section header,
- ensuring that the release notes are not missing entries (check the `needs-changelog` label on github), and * ensuring that the release notes are not missing entries (check the `needs-changelog` label on github), and
- including an entry for `### ABI Compatibility` if it doesn't exist, * including an entry for `### ABI Compatibility` if it doesn't exist,
- sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`, and, * sets `_PKG_VERSION_IS_RELEASE` to `true` in `configure.ac`, and,
- if this is not a patch release, * if this is not a patch release,
- updates `_PKG_VERSION_*` and `_LIB_VERSION_*` in `configure.ac`, and * updates `_PKG_VERSION_*` and `_LIB_VERSION_*` in `configure.ac`, and
- updates `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_*` in `CMakeLists.txt`. * updates `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_*` in `CMakeLists.txt`.
2. Perform the [sanity checks](#sanity-checks) on the PR branch. 2. Perform the [sanity checks](#sanity-checks) on the PR branch.
3. After the PR is merged, tag the commit, and push the tag: 3. After the PR is merged, tag the commit, and push the tag:
``` ```
@@ -60,12 +59,11 @@ Perform these checks when reviewing the release PR (see below):
git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
``` ```
4. Open a PR to the master branch with a commit (using message `"release cleanup: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that 4. Open a PR to the master branch with a commit (using message `"release cleanup: bump version after $MAJOR.$MINOR.$PATCH"`, for example) that
- sets `_PKG_VERSION_IS_RELEASE` to `false` and increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac`, * sets `_PKG_VERSION_IS_RELEASE` to `false` and increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac`,
- increments the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt`, and * increments the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt`, and
- adds an `[Unreleased]` section header to the [CHANGELOG.md](../CHANGELOG.md). * adds an `[Unreleased]` section header to the [CHANGELOG.md](../CHANGELOG.md).
If other maintainers are not present to approve the PR, it can be merged without ACKs. If other maintainers are not present to approve the PR, it can be merged without ACKs.
5. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md). 5. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
6. Send an announcement email to the bitcoin-dev mailing list. 6. Send an announcement email to the bitcoin-dev mailing list.
@@ -79,9 +77,9 @@ Note that bug fixes need to be backported only to releases for which no compatib
git push git@github.com:bitcoin-core/secp256k1.git $MAJOR.$MINOR git push git@github.com:bitcoin-core/secp256k1.git $MAJOR.$MINOR
``` ```
2. Open a pull request to the `$MAJOR.$MINOR` branch that 2. Open a pull request to the `$MAJOR.$MINOR` branch that
- includes the bug fixes, * includes the bug fixes,
- finalizes the release notes similar to a regular release, * finalizes the release notes similar to a regular release,
- increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac` * increments `_PKG_VERSION_PATCH` and `_LIB_VERSION_REVISION` in `configure.ac`
and the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt` and the `$PATCH` component of `project(libsecp256k1 VERSION ...)` and `${PROJECT_NAME}_LIB_VERSION_REVISION` in `CMakeLists.txt`
(with commit message `"release: bump versions for $MAJOR.$MINOR.$PATCH"`, for example). (with commit message `"release: bump versions for $MAJOR.$MINOR.$PATCH"`, for example).
3. Perform the [sanity checks](#sanity-checks) on the PR branch. 3. Perform the [sanity checks](#sanity-checks) on the PR branch.
@@ -91,6 +89,6 @@ Note that bug fixes need to be backported only to releases for which no compatib
git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH" git tag -s v$MAJOR.$MINOR.$PATCH -m "libsecp256k1 $MAJOR.$MINOR.$PATCH"
git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH git push git@github.com:bitcoin-core/secp256k1.git v$MAJOR.$MINOR.$PATCH
``` ```
5. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md). 6. Create a new GitHub release with a link to the corresponding entry in [CHANGELOG.md](../CHANGELOG.md).
6. Send an announcement email to the bitcoin-dev mailing list. 7. Send an announcement email to the bitcoin-dev mailing list.
7. Open PR to the master branch that includes a commit (with commit message `"release notes: add $MAJOR.$MINOR.$PATCH"`, for example) that adds release notes to [CHANGELOG.md](../CHANGELOG.md). 8. Open PR to the master branch that includes a commit (with commit message `"release notes: add $MAJOR.$MINOR.$PATCH"`, for example) that adds release notes to [CHANGELOG.md](../CHANGELOG.md).

301
external/secp256k1/doc/safegcd_implementation.md vendored
View File

@@ -29,67 +29,65 @@ def gcd(f, g):
return abs(f) return abs(f)
``` ```
It computes the greatest common divisor of an odd integer _f_ and any integer _g_. Its inner loop It computes the greatest common divisor of an odd integer *f* and any integer *g*. Its inner loop
keeps rewriting the variables _f_ and _g_ alongside a state variable _&delta;_ that starts at _1_, until keeps rewriting the variables *f* and *g* alongside a state variable *&delta;* that starts at *1*, until
_g=0_ is reached. At that point, _|f|_ gives the GCD. Each of the transitions in the loop is called a *g=0* is reached. At that point, *|f|* gives the GCD. Each of the transitions in the loop is called a
"division step" (referred to as divstep in what follows). "division step" (referred to as divstep in what follows).
For example, _gcd(21, 14)_ would be computed as: For example, *gcd(21, 14)* would be computed as:
- Start with *&delta;=1 f=21 g=14*
- Start with _&delta;=1 f=21 g=14_ - Take the third branch: *&delta;=2 f=21 g=7*
- Take the third branch: _&delta;=2 f=21 g=7_ - Take the first branch: *&delta;=-1 f=7 g=-7*
- Take the first branch: _&delta;=-1 f=7 g=-7_ - Take the second branch: *&delta;=0 f=7 g=0*
- Take the second branch: _&delta;=0 f=7 g=0_ - The answer *|f| = 7*.
- The answer _|f| = 7_.
Why it works: Why it works:
- Divsteps can be decomposed into two steps (see paragraph 8.2 in the paper): - Divsteps can be decomposed into two steps (see paragraph 8.2 in the paper):
- (a) If _g_ is odd, replace _(f,g)_ with _(g,g-f)_ or (f,g+f), resulting in an even _g_. - (a) If *g* is odd, replace *(f,g)* with *(g,g-f)* or (f,g+f), resulting in an even *g*.
- (b) Replace _(f,g)_ with _(f,g/2)_ (where _g_ is guaranteed to be even). - (b) Replace *(f,g)* with *(f,g/2)* (where *g* is guaranteed to be even).
- Neither of those two operations change the GCD: - Neither of those two operations change the GCD:
- For (a), assume _gcd(f,g)=c_, then it must be the case that _f=a&thinsp;c_ and _g=b&thinsp;c_ for some integers _a_ - For (a), assume *gcd(f,g)=c*, then it must be the case that *f=a&thinsp;c* and *g=b&thinsp;c* for some integers *a*
and _b_. As _(g,g-f)=(b&thinsp;c,(b-a)c)_ and _(f,f+g)=(a&thinsp;c,(a+b)c)_, the result clearly still has and *b*. As *(g,g-f)=(b&thinsp;c,(b-a)c)* and *(f,f+g)=(a&thinsp;c,(a+b)c)*, the result clearly still has
common factor _c_. Reasoning in the other direction shows that no common factor can be added by common factor *c*. Reasoning in the other direction shows that no common factor can be added by
doing so either. doing so either.
- For (b), we know that _f_ is odd, so _gcd(f,g)_ clearly has no factor _2_, and we can remove - For (b), we know that *f* is odd, so *gcd(f,g)* clearly has no factor *2*, and we can remove
it from _g_. it from *g*.
- The algorithm will eventually converge to _g=0_. This is proven in the paper (see theorem G.3). - The algorithm will eventually converge to *g=0*. This is proven in the paper (see theorem G.3).
- It follows that eventually we find a final value _f'_ for which _gcd(f,g) = gcd(f',0)_. As the - It follows that eventually we find a final value *f'* for which *gcd(f,g) = gcd(f',0)*. As the
gcd of _f'_ and _0_ is _|f'|_ by definition, that is our answer. gcd of *f'* and *0* is *|f'|* by definition, that is our answer.
Compared to more [traditional GCD algorithms](https://en.wikipedia.org/wiki/Euclidean_algorithm), this one has the property of only ever looking at Compared to more [traditional GCD algorithms](https://en.wikipedia.org/wiki/Euclidean_algorithm), this one has the property of only ever looking at
the low-order bits of the variables to decide the next steps, and being easy to make the low-order bits of the variables to decide the next steps, and being easy to make
constant-time (in more low-level languages than Python). The _&delta;_ parameter is necessary to constant-time (in more low-level languages than Python). The *&delta;* parameter is necessary to
guide the algorithm towards shrinking the numbers' magnitudes without explicitly needing to look guide the algorithm towards shrinking the numbers' magnitudes without explicitly needing to look
at high order bits. at high order bits.
Properties that will become important later: Properties that will become important later:
- Performing more divsteps than needed is not a problem, as *f* does not change anymore after *g=0*.
- Performing more divsteps than needed is not a problem, as _f_ does not change anymore after _g=0_. - Only even numbers are divided by *2*. This means that when reasoning about it algebraically we
- Only even numbers are divided by _2_. This means that when reasoning about it algebraically we
do not need to worry about rounding. do not need to worry about rounding.
- At every point during the algorithm's execution the next _N_ steps only depend on the bottom _N_ - At every point during the algorithm's execution the next *N* steps only depend on the bottom *N*
bits of _f_ and _g_, and on _&delta;_. bits of *f* and *g*, and on *&delta;*.
## 2. From GCDs to modular inverses ## 2. From GCDs to modular inverses
We want an algorithm to compute the inverse _a_ of _x_ modulo _M_, i.e. the number a such that _a&thinsp;x=1 We want an algorithm to compute the inverse *a* of *x* modulo *M*, i.e. the number a such that *a&thinsp;x=1
mod M_. This inverse only exists if the GCD of _x_ and _M_ is _1_, but that is always the case if _M_ is mod M*. This inverse only exists if the GCD of *x* and *M* is *1*, but that is always the case if *M* is
prime and _0 < x < M_. In what follows, assume that the modular inverse exists. prime and *0 < x < M*. In what follows, assume that the modular inverse exists.
It turns out this inverse can be computed as a side effect of computing the GCD by keeping track It turns out this inverse can be computed as a side effect of computing the GCD by keeping track
of how the internal variables can be written as linear combinations of the inputs at every step of how the internal variables can be written as linear combinations of the inputs at every step
(see the [extended Euclidean algorithm](https://en.wikipedia.org/wiki/Extended_Euclidean_algorithm)). (see the [extended Euclidean algorithm](https://en.wikipedia.org/wiki/Extended_Euclidean_algorithm)).
Since the GCD is _1_, such an algorithm will compute numbers _a_ and _b_ such that a&thinsp;x + b&thinsp;M = 1*. Since the GCD is *1*, such an algorithm will compute numbers *a* and *b* such that a&thinsp;x + b&thinsp;M = 1*.
Taking that expression *mod M* gives *a&thinsp;x mod M = 1*, and we see that *a* is the modular inverse of *x Taking that expression *mod M* gives *a&thinsp;x mod M = 1*, and we see that *a* is the modular inverse of *x
mod M\*. mod M*.
A similar approach can be used to calculate modular inverses using the divsteps-based GCD A similar approach can be used to calculate modular inverses using the divsteps-based GCD
algorithm shown above, if the modulus _M_ is odd. To do so, compute _gcd(f=M,g=x)_, while keeping algorithm shown above, if the modulus *M* is odd. To do so, compute *gcd(f=M,g=x)*, while keeping
track of extra variables _d_ and _e_, for which at every step _d = f/x (mod M)_ and _e = g/x (mod M)_. track of extra variables *d* and *e*, for which at every step *d = f/x (mod M)* and *e = g/x (mod M)*.
_f/x_ here means the number which multiplied with _x_ gives _f mod M_. As _f_ and _g_ are initialized to _M_ *f/x* here means the number which multiplied with *x* gives *f mod M*. As *f* and *g* are initialized to *M*
and _x_ respectively, _d_ and _e_ just start off being _0_ (_M/x mod M = 0/x mod M = 0_) and _1_ (_x/x mod M and *x* respectively, *d* and *e* just start off being *0* (*M/x mod M = 0/x mod M = 0*) and *1* (*x/x mod M
= 1_). = 1*).
```python ```python
def div2(M, x): def div2(M, x):
@@ -121,16 +119,17 @@ def modinv(M, x):
return (d * f) % M return (d * f) % M
``` ```
Also note that this approach to track _d_ and _e_ throughout the computation to determine the inverse Also note that this approach to track *d* and *e* throughout the computation to determine the inverse
is different from the paper. There (see paragraph 12.1 in the paper) a transition matrix for the is different from the paper. There (see paragraph 12.1 in the paper) a transition matrix for the
entire computation is determined (see section 3 below) and the inverse is computed from that. entire computation is determined (see section 3 below) and the inverse is computed from that.
The approach here avoids the need for 2x2 matrix multiplications of various sizes, and appears to The approach here avoids the need for 2x2 matrix multiplications of various sizes, and appears to
be faster at the level of optimization we're able to do in C. be faster at the level of optimization we're able to do in C.
## 3. Batching multiple divsteps ## 3. Batching multiple divsteps
Every divstep can be expressed as a matrix multiplication, applying a transition matrix _(1/2 t)_ Every divstep can be expressed as a matrix multiplication, applying a transition matrix *(1/2 t)*
to both vectors _[f, g]_ and _[d, e]_ (see paragraph 8.1 in the paper): to both vectors *[f, g]* and *[d, e]* (see paragraph 8.1 in the paper):
``` ```
t = [ u, v ] t = [ u, v ]
@@ -143,15 +142,15 @@ to both vectors _[f, g]_ and _[d, e]_ (see paragraph 8.1 in the paper):
[ out_e ] [ in_e ] [ out_e ] [ in_e ]
``` ```
where _(u, v, q, r)_ is _(0, 2, -1, 1)_, _(2, 0, 1, 1)_, or _(2, 0, 0, 1)_, depending on which branch is where *(u, v, q, r)* is *(0, 2, -1, 1)*, *(2, 0, 1, 1)*, or *(2, 0, 0, 1)*, depending on which branch is
taken. As above, the resulting _f_ and _g_ are always integers. taken. As above, the resulting *f* and *g* are always integers.
Performing multiple divsteps corresponds to a multiplication with the product of all the Performing multiple divsteps corresponds to a multiplication with the product of all the
individual divsteps' transition matrices. As each transition matrix consists of integers individual divsteps' transition matrices. As each transition matrix consists of integers
divided by _2_, the product of these matrices will consist of integers divided by _2<sup>N</sup>_ (see also divided by *2*, the product of these matrices will consist of integers divided by *2<sup>N</sup>* (see also
theorem 9.2 in the paper). These divisions are expensive when updating _d_ and _e_, so we delay theorem 9.2 in the paper). These divisions are expensive when updating *d* and *e*, so we delay
them: we compute the integer coefficients of the combined transition matrix scaled by _2<sup>N</sup>_, and them: we compute the integer coefficients of the combined transition matrix scaled by *2<sup>N</sup>*, and
do one division by _2<sup>N</sup>_ as a final step: do one division by *2<sup>N</sup>* as a final step:
```python ```python
def divsteps_n_matrix(delta, f, g): def divsteps_n_matrix(delta, f, g):
@@ -167,13 +166,13 @@ def divsteps_n_matrix(delta, f, g):
return delta, (u, v, q, r) return delta, (u, v, q, r)
``` ```
As the branches in the divsteps are completely determined by the bottom _N_ bits of _f_ and _g_, this As the branches in the divsteps are completely determined by the bottom *N* bits of *f* and *g*, this
function to compute the transition matrix only needs to see those bottom bits. Furthermore all function to compute the transition matrix only needs to see those bottom bits. Furthermore all
intermediate results and outputs fit in _(N+1)_-bit numbers (unsigned for _f_ and _g_; signed for _u_, _v_, intermediate results and outputs fit in *(N+1)*-bit numbers (unsigned for *f* and *g*; signed for *u*, *v*,
_q_, and _r_) (see also paragraph 8.3 in the paper). This means that an implementation using 64-bit *q*, and *r*) (see also paragraph 8.3 in the paper). This means that an implementation using 64-bit
integers could set _N=62_ and compute the full transition matrix for 62 steps at once without any integers could set *N=62* and compute the full transition matrix for 62 steps at once without any
big integer arithmetic at all. This is the reason why this algorithm is efficient: it only needs big integer arithmetic at all. This is the reason why this algorithm is efficient: it only needs
to update the full-size _f_, _g_, _d_, and _e_ numbers once every _N_ steps. to update the full-size *f*, *g*, *d*, and *e* numbers once every *N* steps.
We still need functions to compute: We still need functions to compute:
@@ -185,8 +184,8 @@ We still need functions to compute:
[ out_e ] ( [ q, r ]) [ in_e ] [ out_e ] ( [ q, r ]) [ in_e ]
``` ```
Because the divsteps transformation only ever divides even numbers by two, the result of _t&thinsp;[f,g]_ is always even. When _t_ is a composition of _N_ divsteps, it follows that the resulting _f_ Because the divsteps transformation only ever divides even numbers by two, the result of *t&thinsp;[f,g]* is always even. When *t* is a composition of *N* divsteps, it follows that the resulting *f*
and _g_ will be multiple of _2<sup>N</sup>_, and division by _2<sup>N</sup>_ is simply shifting them down: and *g* will be multiple of *2<sup>N</sup>*, and division by *2<sup>N</sup>* is simply shifting them down:
```python ```python
def update_fg(f, g, t): def update_fg(f, g, t):
@@ -200,8 +199,8 @@ def update_fg(f, g, t):
return cf >> N, cg >> N return cf >> N, cg >> N
``` ```
The same is not true for _d_ and _e_, and we need an equivalent of the `div2` function for division by _2<sup>N</sup> mod M_. The same is not true for *d* and *e*, and we need an equivalent of the `div2` function for division by *2<sup>N</sup> mod M*.
This is easy if we have precomputed _1/M mod 2<sup>N</sup>_ (which always exists for odd _M_): This is easy if we have precomputed *1/M mod 2<sup>N</sup>* (which always exists for odd *M*):
```python ```python
def div2n(M, Mi, x): def div2n(M, Mi, x):
@@ -225,7 +224,7 @@ def update_de(d, e, t, M, Mi):
return div2n(M, Mi, cd), div2n(M, Mi, ce) return div2n(M, Mi, cd), div2n(M, Mi, ce)
``` ```
With all of those, we can write a version of `modinv` that performs _N_ divsteps at once: With all of those, we can write a version of `modinv` that performs *N* divsteps at once:
```python3 ```python3
def modinv(M, Mi, x): def modinv(M, Mi, x):
@@ -243,19 +242,20 @@ def modinv(M, Mi, x):
return (d * f) % M return (d * f) % M
``` ```
This means that in practice we'll always perform a multiple of _N_ divsteps. This is not a problem This means that in practice we'll always perform a multiple of *N* divsteps. This is not a problem
because once _g=0_, further divsteps do not affect _f_, _g_, _d_, or _e_ anymore (only _&delta;_ keeps because once *g=0*, further divsteps do not affect *f*, *g*, *d*, or *e* anymore (only *&delta;* keeps
increasing). For variable time code such excess iterations will be mostly optimized away in later increasing). For variable time code such excess iterations will be mostly optimized away in later
sections. sections.
## 4. Avoiding modulus operations ## 4. Avoiding modulus operations
So far, there are two places where we compute a remainder of big numbers modulo _M_: at the end of So far, there are two places where we compute a remainder of big numbers modulo *M*: at the end of
`div2n` in every `update_de`, and at the very end of `modinv` after potentially negating _d_ due to the `div2n` in every `update_de`, and at the very end of `modinv` after potentially negating *d* due to the
sign of _f_. These are relatively expensive operations when done generically. sign of *f*. These are relatively expensive operations when done generically.
To deal with the modulus operation in `div2n`, we simply stop requiring _d_ and _e_ to be in range To deal with the modulus operation in `div2n`, we simply stop requiring *d* and *e* to be in range
_[0,M)_ all the time. Let's start by inlining `div2n` into `update_de`, and dropping the modulus *[0,M)* all the time. Let's start by inlining `div2n` into `update_de`, and dropping the modulus
operation at the end: operation at the end:
```python ```python
@@ -272,15 +272,15 @@ def update_de(d, e, t, M, Mi):
return cd >> N, ce >> N return cd >> N, ce >> N
``` ```
Let's look at bounds on the ranges of these numbers. It can be shown that _|u|+|v|_ and _|q|+|r|_ Let's look at bounds on the ranges of these numbers. It can be shown that *|u|+|v|* and *|q|+|r|*
never exceed _2<sup>N</sup>_ (see paragraph 8.3 in the paper), and thus a multiplication with _t_ will have never exceed *2<sup>N</sup>* (see paragraph 8.3 in the paper), and thus a multiplication with *t* will have
outputs whose absolute values are at most _2<sup>N</sup>_ times the maximum absolute input value. In case the outputs whose absolute values are at most *2<sup>N</sup>* times the maximum absolute input value. In case the
inputs _d_ and _e_ are in _(-M,M)_, which is certainly true for the initial values _d=0_ and _e=1_ assuming inputs *d* and *e* are in *(-M,M)*, which is certainly true for the initial values *d=0* and *e=1* assuming
_M > 1_, the multiplication results in numbers in range _(-2<sup>N</sup>M,2<sup>N</sup>M)_. Subtracting less than _2<sup>N</sup>_ *M > 1*, the multiplication results in numbers in range *(-2<sup>N</sup>M,2<sup>N</sup>M)*. Subtracting less than *2<sup>N</sup>*
times _M_ to cancel out _N_ bits brings that up to _(-2<sup>N+1</sup>M,2<sup>N</sup>M)_, and times *M* to cancel out *N* bits brings that up to *(-2<sup>N+1</sup>M,2<sup>N</sup>M)*, and
dividing by _2<sup>N</sup>_ at the end takes it to _(-2M,M)_. Another application of `update_de` would take that dividing by *2<sup>N</sup>* at the end takes it to *(-2M,M)*. Another application of `update_de` would take that
to _(-3M,2M)_, and so forth. This progressive expansion of the variables' ranges can be to *(-3M,2M)*, and so forth. This progressive expansion of the variables' ranges can be
counteracted by incrementing _d_ and _e_ by _M_ whenever they're negative: counteracted by incrementing *d* and *e* by *M* whenever they're negative:
```python ```python
... ...
@@ -293,12 +293,12 @@ counteracted by incrementing _d_ and _e_ by _M_ whenever they're negative:
... ...
``` ```
With inputs in _(-2M,M)_, they will first be shifted into range _(-M,M)_, which means that the With inputs in *(-2M,M)*, they will first be shifted into range *(-M,M)*, which means that the
output will again be in _(-2M,M)_, and this remains the case regardless of how many `update_de` output will again be in *(-2M,M)*, and this remains the case regardless of how many `update_de`
invocations there are. In what follows, we will try to make this more efficient. invocations there are. In what follows, we will try to make this more efficient.
Note that increasing _d_ by _M_ is equal to incrementing _cd_ by _u&thinsp;M_ and _ce_ by _q&thinsp;M_. Similarly, Note that increasing *d* by *M* is equal to incrementing *cd* by *u&thinsp;M* and *ce* by *q&thinsp;M*. Similarly,
increasing _e_ by _M_ is equal to incrementing _cd_ by _v&thinsp;M_ and _ce_ by _r&thinsp;M_. So we could instead write: increasing *e* by *M* is equal to incrementing *cd* by *v&thinsp;M* and *ce* by *r&thinsp;M*. So we could instead write:
```python ```python
... ...
@@ -318,10 +318,10 @@ increasing _e_ by _M_ is equal to incrementing _cd_ by _v&thinsp;M_ and _ce_ by
... ...
``` ```
Now note that we have two steps of corrections to _cd_ and _ce_ that add multiples of _M_: this Now note that we have two steps of corrections to *cd* and *ce* that add multiples of *M*: this
increment, and the decrement that cancels out bottom bits. The second one depends on the first increment, and the decrement that cancels out bottom bits. The second one depends on the first
one, but they can still be efficiently combined by only computing the bottom bits of _cd_ and _ce_ one, but they can still be efficiently combined by only computing the bottom bits of *cd* and *ce*
at first, and using that to compute the final _md_, _me_ values: at first, and using that to compute the final *md*, *me* values:
```python ```python
def update_de(d, e, t, M, Mi): def update_de(d, e, t, M, Mi):
@@ -346,8 +346,8 @@ def update_de(d, e, t, M, Mi):
return cd >> N, ce >> N return cd >> N, ce >> N
``` ```
One last optimization: we can avoid the _md&thinsp;M_ and _me&thinsp;M_ multiplications in the bottom bits of _cd_ One last optimization: we can avoid the *md&thinsp;M* and *me&thinsp;M* multiplications in the bottom bits of *cd*
and _ce_ by moving them to the _md_ and _me_ correction: and *ce* by moving them to the *md* and *me* correction:
```python ```python
... ...
@@ -362,10 +362,10 @@ and _ce_ by moving them to the _md_ and _me_ correction:
... ...
``` ```
The resulting function takes _d_ and _e_ in range _(-2M,M)_ as inputs, and outputs values in the same The resulting function takes *d* and *e* in range *(-2M,M)* as inputs, and outputs values in the same
range. That also means that the _d_ value at the end of `modinv` will be in that range, while we want range. That also means that the *d* value at the end of `modinv` will be in that range, while we want
a result in _[0,M)_. To do that, we need a normalization function. It's easy to integrate the a result in *[0,M)*. To do that, we need a normalization function. It's easy to integrate the
conditional negation of _d_ (based on the sign of _f_) into it as well: conditional negation of *d* (based on the sign of *f*) into it as well:
```python ```python
def normalize(sign, v, M): def normalize(sign, v, M):
@@ -391,21 +391,22 @@ And calling it in `modinv` is simply:
return normalize(f, d, M) return normalize(f, d, M)
``` ```
## 5. Constant-time operation ## 5. Constant-time operation
The primary selling point of the algorithm is fast constant-time operation. What code flow still The primary selling point of the algorithm is fast constant-time operation. What code flow still
depends on the input data so far? depends on the input data so far?
- the number of iterations of the while _g &ne; 0_ loop in `modinv` - the number of iterations of the while *g &ne; 0* loop in `modinv`
- the branches inside `divsteps_n_matrix` - the branches inside `divsteps_n_matrix`
- the sign checks in `update_de` - the sign checks in `update_de`
- the sign checks in `normalize` - the sign checks in `normalize`
To make the while loop in `modinv` constant time it can be replaced with a constant number of To make the while loop in `modinv` constant time it can be replaced with a constant number of
iterations. The paper proves (Theorem 11.2) that _741_ divsteps are sufficient for any _256_-bit iterations. The paper proves (Theorem 11.2) that *741* divsteps are sufficient for any *256*-bit
inputs, and [safegcd-bounds](https://github.com/sipa/safegcd-bounds) shows that the slightly better bound _724_ is inputs, and [safegcd-bounds](https://github.com/sipa/safegcd-bounds) shows that the slightly better bound *724* is
sufficient even. Given that every loop iteration performs _N_ divsteps, it will run a total of sufficient even. Given that every loop iteration performs *N* divsteps, it will run a total of
_&lceil;724/N&rceil;_ times. *&lceil;724/N&rceil;* times.
To deal with the branches in `divsteps_n_matrix` we will replace them with constant-time bitwise To deal with the branches in `divsteps_n_matrix` we will replace them with constant-time bitwise
operations (and hope the C compiler isn't smart enough to turn them back into branches; see operations (and hope the C compiler isn't smart enough to turn them back into branches; see
@@ -424,10 +425,10 @@ divstep can be written instead as (compare to the inner loop of `gcd` in section
``` ```
To convert the above to bitwise operations, we rely on a trick to negate conditionally: per the To convert the above to bitwise operations, we rely on a trick to negate conditionally: per the
definition of negative numbers in two's complement, (_-v == ~v + 1_) holds for every number _v_. As definition of negative numbers in two's complement, (*-v == ~v + 1*) holds for every number *v*. As
_-1_ in two's complement is all _1_ bits, bitflipping can be expressed as xor with _-1_. It follows *-1* in two's complement is all *1* bits, bitflipping can be expressed as xor with *-1*. It follows
that _-v == (v ^ -1) - (-1)_. Thus, if we have a variable _c_ that takes on values _0_ or _-1_, then that *-v == (v ^ -1) - (-1)*. Thus, if we have a variable *c* that takes on values *0* or *-1*, then
_(v ^ c) - c_ is _v_ if _c=0_ and _-v_ if _c=-1_. *(v ^ c) - c* is *v* if *c=0* and *-v* if *c=-1*.
Using this we can write: Using this we can write:
@@ -443,13 +444,13 @@ in constant-time form as:
x = (f ^ c1) - c1 x = (f ^ c1) - c1
``` ```
To use that trick, we need a helper mask variable _c1_ that resolves the condition _&delta;>0_ to _-1_ To use that trick, we need a helper mask variable *c1* that resolves the condition *&delta;>0* to *-1*
(if true) or _0_ (if false). We compute _c1_ using right shifting, which is equivalent to dividing by (if true) or *0* (if false). We compute *c1* using right shifting, which is equivalent to dividing by
the specified power of _2_ and rounding down (in Python, and also in C under the assumption of a typical two's complement system; see the specified power of *2* and rounding down (in Python, and also in C under the assumption of a typical two's complement system; see
`assumptions.h` for tests that this is the case). Right shifting by _63_ thus maps all `assumptions.h` for tests that this is the case). Right shifting by *63* thus maps all
numbers in range _[-2<sup>63</sup>,0)_ to _-1_, and numbers in range _[0,2<sup>63</sup>)_ to _0_. numbers in range *[-2<sup>63</sup>,0)* to *-1*, and numbers in range *[0,2<sup>63</sup>)* to *0*.
Using the facts that _x&0=0_ and _x&(-1)=x_ (on two's complement systems again), we can write: Using the facts that *x&0=0* and *x&(-1)=x* (on two's complement systems again), we can write:
```python ```python
if g & 1: if g & 1:
@@ -497,8 +498,8 @@ becomes:
``` ```
It turns out that this can be implemented more efficiently by applying the substitution It turns out that this can be implemented more efficiently by applying the substitution
_&eta;=-&delta;_. In this representation, negating _&delta;_ corresponds to negating _&eta;_, and incrementing *&eta;=-&delta;*. In this representation, negating *&delta;* corresponds to negating *&eta;*, and incrementing
_&delta;_ corresponds to decrementing _&eta;_. This allows us to remove the negation in the _c1_ *&delta;* corresponds to decrementing *&eta;*. This allows us to remove the negation in the *c1*
computation: computation:
```python ```python
@@ -518,12 +519,12 @@ computation:
g >>= 1 g >>= 1
``` ```
A variant of divsteps with better worst-case performance can be used instead: starting _&delta;_ at A variant of divsteps with better worst-case performance can be used instead: starting *&delta;* at
_1/2_ instead of _1_. This reduces the worst case number of iterations to _590_ for _256_-bit inputs *1/2* instead of *1*. This reduces the worst case number of iterations to *590* for *256*-bit inputs
(which can be shown using convex hull analysis). In this case, the substitution _&zeta;=-(&delta;+1/2)_ (which can be shown using convex hull analysis). In this case, the substitution *&zeta;=-(&delta;+1/2)*
is used instead to keep the variable integral. Incrementing _&delta;_ by _1_ still translates to is used instead to keep the variable integral. Incrementing *&delta;* by *1* still translates to
decrementing _&zeta;_ by _1_, but negating _&delta;_ now corresponds to going from _&zeta;_ to _-(&zeta;+1)_, or decrementing *&zeta;* by *1*, but negating *&delta;* now corresponds to going from *&zeta;* to *-(&zeta;+1)*, or
_~&zeta;_. Doing that conditionally based on _c3_ is simply: *~&zeta;*. Doing that conditionally based on *c3* is simply:
```python ```python
... ...
@@ -533,12 +534,13 @@ _~&zeta;_. Doing that conditionally based on _c3_ is simply:
``` ```
By replacing the loop in `divsteps_n_matrix` with a variant of the divstep code above (extended to By replacing the loop in `divsteps_n_matrix` with a variant of the divstep code above (extended to
also apply all _f_ operations to _u_, _v_ and all _g_ operations to _q_, _r_), a constant-time version of also apply all *f* operations to *u*, *v* and all *g* operations to *q*, *r*), a constant-time version of
`divsteps_n_matrix` is obtained. The full code will be in section 7. `divsteps_n_matrix` is obtained. The full code will be in section 7.
These bit fiddling tricks can also be used to make the conditional negations and additions in These bit fiddling tricks can also be used to make the conditional negations and additions in
`update_de` and `normalize` constant-time. `update_de` and `normalize` constant-time.
## 6. Variable-time optimizations ## 6. Variable-time optimizations
In section 5, we modified the `divsteps_n_matrix` function (and a few others) to be constant time. In section 5, we modified the `divsteps_n_matrix` function (and a few others) to be constant time.
@@ -548,7 +550,7 @@ faster non-constant time `divsteps_n_matrix` function.
To do so, first consider yet another way of writing the inner loop of divstep operations in To do so, first consider yet another way of writing the inner loop of divstep operations in
`gcd` from section 1. This decomposition is also explained in the paper in section 8.2. We use `gcd` from section 1. This decomposition is also explained in the paper in section 8.2. We use
the original version with initial _&delta;=1_ and _&eta;=-&delta;_ here. the original version with initial *&delta;=1* and *&eta;=-&delta;* here.
```python ```python
for _ in range(N): for _ in range(N):
@@ -560,7 +562,7 @@ for _ in range(N):
g >>= 1 g >>= 1
``` ```
Whenever _g_ is even, the loop only shifts _g_ down and decreases _&eta;_. When _g_ ends in multiple zero Whenever *g* is even, the loop only shifts *g* down and decreases *&eta;*. When *g* ends in multiple zero
bits, these iterations can be consolidated into one step. This requires counting the bottom zero bits, these iterations can be consolidated into one step. This requires counting the bottom zero
bits efficiently, which is possible on most platforms; it is abstracted here as the function bits efficiently, which is possible on most platforms; it is abstracted here as the function
`count_trailing_zeros`. `count_trailing_zeros`.
@@ -593,20 +595,20 @@ while True:
# g is even now, and the eta decrement and g shift will happen in the next loop. # g is even now, and the eta decrement and g shift will happen in the next loop.
``` ```
We can now remove multiple bottom _0_ bits from _g_ at once, but still need a full iteration whenever We can now remove multiple bottom *0* bits from *g* at once, but still need a full iteration whenever
there is a bottom _1_ bit. In what follows, we will get rid of multiple _1_ bits simultaneously as there is a bottom *1* bit. In what follows, we will get rid of multiple *1* bits simultaneously as
well. well.
Observe that as long as _&eta; &geq; 0_, the loop does not modify _f_. Instead, it cancels out bottom Observe that as long as *&eta; &geq; 0*, the loop does not modify *f*. Instead, it cancels out bottom
bits of _g_ and shifts them out, and decreases _&eta;_ and _i_ accordingly - interrupting only when _&eta;_ bits of *g* and shifts them out, and decreases *&eta;* and *i* accordingly - interrupting only when *&eta;*
becomes negative, or when _i_ reaches _0_. Combined, this is equivalent to adding a multiple of _f_ to becomes negative, or when *i* reaches *0*. Combined, this is equivalent to adding a multiple of *f* to
_g_ to cancel out multiple bottom bits, and then shifting them out. *g* to cancel out multiple bottom bits, and then shifting them out.
It is easy to find what that multiple is: we want a number _w_ such that _g+w&thinsp;f_ has a few bottom It is easy to find what that multiple is: we want a number *w* such that *g+w&thinsp;f* has a few bottom
zero bits. If that number of bits is _L_, we want _g+w&thinsp;f mod 2<sup>L</sup> = 0_, or _w = -g/f mod 2<sup>L</sup>_. Since _f_ zero bits. If that number of bits is *L*, we want *g+w&thinsp;f mod 2<sup>L</sup> = 0*, or *w = -g/f mod 2<sup>L</sup>*. Since *f*
is odd, such a _w_ exists for any _L_. _L_ cannot be more than _i_ steps (as we'd finish the loop before is odd, such a *w* exists for any *L*. *L* cannot be more than *i* steps (as we'd finish the loop before
doing more) or more than _&eta;+1_ steps (as we'd run `eta, f, g = -eta, g, -f` at that point), but doing more) or more than *&eta;+1* steps (as we'd run `eta, f, g = -eta, g, -f` at that point), but
apart from that, we're only limited by the complexity of computing _w_. apart from that, we're only limited by the complexity of computing *w*.
This code demonstrates how to cancel up to 4 bits per step: This code demonstrates how to cancel up to 4 bits per step:
@@ -640,25 +642,26 @@ some can be found in Hacker's Delight second edition by Henry S. Warren, Jr. pag
Here we need the negated modular inverse, which is a simple transformation of those: Here we need the negated modular inverse, which is a simple transformation of those:
- Instead of a 3-bit table: - Instead of a 3-bit table:
- _-f_ or _f ^ 6_ - *-f* or *f ^ 6*
- Instead of a 4-bit table: - Instead of a 4-bit table:
- _1 - f(f + 1)_ - *1 - f(f + 1)*
- _-(f + (((f + 1) & 4) << 1))_ - *-(f + (((f + 1) & 4) << 1))*
- For larger tables the following technique can be used: if _w=-1/f mod 2<sup>L</sup>_, then _w(w&thinsp;f+2)_ is - For larger tables the following technique can be used: if *w=-1/f mod 2<sup>L</sup>*, then *w(w&thinsp;f+2)* is
_-1/f mod 2<sup>2L</sup>_. This allows extending the previous formulas (or tables). In particular we *-1/f mod 2<sup>2L</sup>*. This allows extending the previous formulas (or tables). In particular we
have this 6-bit function (based on the 3-bit function above): have this 6-bit function (based on the 3-bit function above):
- _f(f<sup>2</sup> - 2)_ - *f(f<sup>2</sup> - 2)*
This loop, again extended to also handle _u_, _v_, _q_, and _r_ alongside _f_ and _g_, placed in This loop, again extended to also handle *u*, *v*, *q*, and *r* alongside *f* and *g*, placed in
`divsteps_n_matrix`, gives a significantly faster, but non-constant time version. `divsteps_n_matrix`, gives a significantly faster, but non-constant time version.
## 7. Final Python version ## 7. Final Python version
All together we need the following functions: All together we need the following functions:
- A way to compute the transition matrix in constant time, using the `divsteps_n_matrix` function - A way to compute the transition matrix in constant time, using the `divsteps_n_matrix` function
from section 2, but with its loop replaced by a variant of the constant-time divstep from from section 2, but with its loop replaced by a variant of the constant-time divstep from
section 5, extended to handle _u_, _v_, _q_, _r_: section 5, extended to handle *u*, *v*, *q*, *r*:
```python ```python
def divsteps_n_matrix(zeta, f, g): def divsteps_n_matrix(zeta, f, g):
@@ -681,7 +684,7 @@ def divsteps_n_matrix(zeta, f, g):
return zeta, (u, v, q, r) return zeta, (u, v, q, r)
``` ```
- The functions to update _f_ and _g_, and _d_ and _e_, from section 2 and section 4, with the constant-time - The functions to update *f* and *g*, and *d* and *e*, from section 2 and section 4, with the constant-time
changes to `update_de` from section 5: changes to `update_de` from section 5:
```python ```python
@@ -720,7 +723,7 @@ def normalize(sign, v, M):
return v return v
``` ```
- And finally the `modinv` function too, adapted to use _&zeta;_ instead of _&delta;_, and using the fixed - And finally the `modinv` function too, adapted to use *&zeta;* instead of *&delta;*, and using the fixed
iteration count from section 5: iteration count from section 5:
```python ```python
@@ -769,21 +772,20 @@ def modinv_var(M, Mi, x):
## 8. From GCDs to Jacobi symbol ## 8. From GCDs to Jacobi symbol
We can also use a similar approach to calculate Jacobi symbol _(x | M)_ by keeping track of an We can also use a similar approach to calculate Jacobi symbol *(x | M)* by keeping track of an
extra variable _j_, for which at every step _(x | M) = j (g | f)_. As we update _f_ and _g_, we extra variable *j*, for which at every step *(x | M) = j (g | f)*. As we update *f* and *g*, we
make corresponding updates to _j_ using make corresponding updates to *j* using
[properties of the Jacobi symbol](https://en.wikipedia.org/wiki/Jacobi_symbol#Properties): [properties of the Jacobi symbol](https://en.wikipedia.org/wiki/Jacobi_symbol#Properties):
* *((g/2) | f)* is either *(g | f)* or *-(g | f)*, depending on the value of *f mod 8* (negating if it's *3* or *5*).
* *(f | g)* is either *(g | f)* or *-(g | f)*, depending on *f mod 4* and *g mod 4* (negating if both are *3*).
- _((g/2) | f)_ is either _(g | f)_ or _-(g | f)_, depending on the value of _f mod 8_ (negating if it's _3_ or _5_). These updates depend only on the values of *f* and *g* modulo *4* or *8*, and can thus be applied
- _(f | g)_ is either _(g | f)_ or _-(g | f)_, depending on _f mod 4_ and _g mod 4_ (negating if both are _3_). very quickly, as long as we keep track of a few additional bits of *f* and *g*. Overall, this
These updates depend only on the values of _f_ and _g_ modulo _4_ or _8_, and can thus be applied
very quickly, as long as we keep track of a few additional bits of _f_ and _g_. Overall, this
calculation is slightly simpler than the one for the modular inverse because we no longer need to calculation is slightly simpler than the one for the modular inverse because we no longer need to
keep track of _d_ and _e_. keep track of *d* and *e*.
However, one difficulty of this approach is that the Jacobi symbol _(a | n)_ is only defined for However, one difficulty of this approach is that the Jacobi symbol *(a | n)* is only defined for
positive odd integers _n_, whereas in the original safegcd algorithm, _f, g_ can take negative positive odd integers *n*, whereas in the original safegcd algorithm, *f, g* can take negative
values. We resolve this by using the following modified steps: values. We resolve this by using the following modified steps:
```python ```python
@@ -797,16 +799,15 @@ values. We resolve this by using the following modified steps:
``` ```
The algorithm is still correct, since the changed divstep, called a "posdivstep" (see section 8.4 The algorithm is still correct, since the changed divstep, called a "posdivstep" (see section 8.4
and E.5 in the paper) preserves _gcd(f, g)_. However, there's no proof that the modified algorithm and E.5 in the paper) preserves *gcd(f, g)*. However, there's no proof that the modified algorithm
will converge. The justification for posdivsteps is completely empirical: in practice, it appears will converge. The justification for posdivsteps is completely empirical: in practice, it appears
that the vast majority of nonzero inputs converge to _f=g=gcd(f<sub>0</sub>, g<sub>0</sub>)_ in a that the vast majority of nonzero inputs converge to *f=g=gcd(f<sub>0</sub>, g<sub>0</sub>)* in a
number of steps proportional to their logarithm. number of steps proportional to their logarithm.
Note that: Note that:
- We require inputs to satisfy *gcd(x, M) = 1*, as otherwise *f=1* is not reached.
- We require inputs to satisfy _gcd(x, M) = 1_, as otherwise _f=1_ is not reached. - We require inputs *x &neq; 0*, because applying posdivstep with *g=0* has no effect.
- We require inputs _x &neq; 0_, because applying posdivstep with _g=0_ has no effect. - We need to update the termination condition from *g=0* to *f=1*.
- We need to update the termination condition from _g=0_ to _f=1_.
We account for the possibility of nonconvergence by only performing a bounded number of We account for the possibility of nonconvergence by only performing a bounded number of
posdivsteps, and then falling back to square-root based Jacobi calculation if a solution has not posdivsteps, and then falling back to square-root based Jacobi calculation if a solution has not
@@ -814,5 +815,5 @@ yet been found.
The optimizations in sections 3-7 above are described in the context of the original divsteps, but The optimizations in sections 3-7 above are described in the context of the original divsteps, but
in the C implementation we also adapt most of them (not including "avoiding modulus operations", in the C implementation we also adapt most of them (not including "avoiding modulus operations",
since it's not necessary to track _d, e_, and "constant-time operation", since we never calculate since it's not necessary to track *d, e*, and "constant-time operation", since we never calculate
Jacobi symbols for secret data) to the posdivsteps version. Jacobi symbols for secret data) to the posdivsteps version.

8086
external/secp256k1/src/wycheproof/ecdsa_secp256k1_sha256_bitcoin_test.json vendored
View File

File diff suppressed because one or more lines are too long

114
include/xrpl/proto/org/xrpl/rpc/v1/get_ledger.proto
View File

@@ -6,89 +6,81 @@ option java_multiple_files = true;
import "org/xrpl/rpc/v1/ledger.proto"; import "org/xrpl/rpc/v1/ledger.proto";
message GetLedgerRequest message GetLedgerRequest {
{ LedgerSpecifier ledger = 1;
LedgerSpecifier ledger = 1; // If true, include transactions contained in this ledger
bool transactions = 2;
// If true, include transactions contained in this ledger // If true and transactions, include full transactions and metadata
bool transactions = 2; // If false and transactions, include only transaction hashes
bool expand = 3;
// If true and transactions, include full transactions and metadata // If true, include state map difference between this ledger and the
// If false and transactions, include only transaction hashes // previous ledger. This includes all added, modified or deleted ledger
bool expand = 3; // objects
bool get_objects = 4;
// If true, include state map difference between this ledger and the // If the request needs to be forwarded from a reporting node to a p2p node,
// previous ledger. This includes all added, modified or deleted ledger // the reporting node will set this field. Clients should not set this
// objects // field.
bool get_objects = 4; string client_ip = 5;
// If the request needs to be forwarded from a reporting node to a p2p node,
// the reporting node will set this field. Clients should not set this
// field.
string client_ip = 5;
// Identifying string. If user is set, client_ip is not set, and request is // Identifying string. If user is set, client_ip is not set, and request is
// coming from a secure_gateway host, then the client is not subject to // coming from a secure_gateway host, then the client is not subject to
// resource controls // resource controls
string user = 6; string user = 6;
// For every object in the diff, get the object's predecessor and successor // For every object in the diff, get the object's predecessor and successor
// in the state map. Only used if get_objects is also true. // in the state map. Only used if get_objects is also true.
bool get_object_neighbors = 7; bool get_object_neighbors = 7;
} }
message GetLedgerResponse message GetLedgerResponse {
{ bytes ledger_header = 1;
bytes ledger_header = 1;
oneof transactions oneof transactions {
{ // Just the hashes
// Just the hashes TransactionHashList hashes_list = 2;
TransactionHashList hashes_list = 2;
// Full transactions and metadata
TransactionAndMetadataList transactions_list = 3;
}
// True if the ledger has been validated // Full transactions and metadata
bool validated = 4; TransactionAndMetadataList transactions_list = 3;
}
// State map difference between this ledger and the previous ledger // True if the ledger has been validated
RawLedgerObjects ledger_objects = 5; bool validated = 4;
// True if the skiplist object is included in ledger_objects // State map difference between this ledger and the previous ledger
bool skiplist_included = 6; RawLedgerObjects ledger_objects = 5;
// True if request was exempt from resource controls // True if the skiplist object is included in ledger_objects
bool is_unlimited = 7; bool skiplist_included = 6;
// True if the response contains the state map diff // True if request was exempt from resource controls
bool objects_included = 8; bool is_unlimited = 7;
// True if the response contains key of objects adjacent to objects in state // True if the response contains the state map diff
// map diff bool objects_included = 8;
bool object_neighbors_included = 9;
// True if the response contains key of objects adjacent to objects in state
// map diff
bool object_neighbors_included = 9;
// Successor information for book directories modified as part of this // Successor information for book directories modified as part of this
// ledger // ledger
repeated BookSuccessor book_successors = 10; repeated BookSuccessor book_successors = 10;
} }
message TransactionHashList message TransactionHashList {
{ repeated bytes hashes = 1;
repeated bytes hashes = 1;
} }
message TransactionAndMetadata message TransactionAndMetadata {
{ bytes transaction_blob = 1;
bytes transaction_blob = 1;
bytes metadata_blob = 2; bytes metadata_blob = 2;
} }
message TransactionAndMetadataList message TransactionAndMetadataList {
{ repeated TransactionAndMetadata transactions = 1;
repeated TransactionAndMetadata transactions = 1;
} }

63
include/xrpl/proto/org/xrpl/rpc/v1/get_ledger_data.proto
View File

@@ -8,46 +8,43 @@ import "org/xrpl/rpc/v1/ledger.proto";
// Get ledger objects for a specific ledger. You can iterate through several // Get ledger objects for a specific ledger. You can iterate through several
// calls to retrieve the entire contents of a single ledger version. // calls to retrieve the entire contents of a single ledger version.
message GetLedgerDataRequest message GetLedgerDataRequest {
{ // If set, only objects with a key greater than marker are returned.
// If set, only objects with a key greater than marker are returned. // This can be used to pick up where a previous call left off.
// This can be used to pick up where a previous call left off. // Set marker to the value of marker in the previous response.
// Set marker to the value of marker in the previous response. bytes marker = 1;
bytes marker = 1;
LedgerSpecifier ledger = 2; LedgerSpecifier ledger = 2;
// If set, only objects with a key less than end_marker are returned // If set, only objects with a key less than end_marker are returned
bytes end_marker = 3; bytes end_marker = 3;
// If the request needs to be forwarded from a reporting node to a p2p node, // If the request needs to be forwarded from a reporting node to a p2p node,
// the reporting node will set this field. Clients should not set this // the reporting node will set this field. Clients should not set this
// field. // field.
string client_ip = 4; string client_ip = 4;
// Identifying string. If user is set, client_ip is not set, and request is // Identifying string. If user is set, client_ip is not set, and request is
// coming from a secure_gateway host, then the client is not subject to // coming from a secure_gateway host, then the client is not subject to
// resource controls // resource controls
string user = 6; string user = 6;
} }
message GetLedgerDataResponse message GetLedgerDataResponse {
{ // Sequence of the ledger containing the returned ledger objects
// Sequence of the ledger containing the returned ledger objects uint32 ledger_index = 1;
uint32 ledger_index = 1;
// Hash of the ledger containing the returned ledger objects // Hash of the ledger containing the returned ledger objects
bytes ledger_hash = 2; bytes ledger_hash = 2;
// Ledger objects
RawLedgerObjects ledger_objects = 3;
// Key to be passed into a subsequent call to continue iteration. If not // Ledger objects
// set, there are no more objects left in the ledger, or no more objects RawLedgerObjects ledger_objects = 3;
// with key less than end_marker (if end_marker was set in the request)
bytes marker = 4;
// True if request was exempt from resource controls // Key to be passed into a subsequent call to continue iteration. If not
bool is_unlimited = 7; // set, there are no more objects left in the ledger, or no more objects
// with key less than end_marker (if end_marker was set in the request)
bytes marker = 4;
// True if request was exempt from resource controls
bool is_unlimited = 7;
} }

30
include/xrpl/proto/org/xrpl/rpc/v1/get_ledger_diff.proto
View File

@@ -6,27 +6,23 @@ option java_multiple_files = true;
import "org/xrpl/rpc/v1/ledger.proto"; import "org/xrpl/rpc/v1/ledger.proto";
// Get the state map difference between the two specified ledgers // Get the state map difference between the two specified ledgers
message GetLedgerDiffRequest message GetLedgerDiffRequest {
{ LedgerSpecifier base_ledger = 1;
LedgerSpecifier base_ledger = 1;
LedgerSpecifier desired_ledger = 2; LedgerSpecifier desired_ledger = 2;
// If true, include the full ledger object. If false, only keys are included. // If true, include the full ledger object. If false, only keys are included.
bool include_blobs = 3; bool include_blobs = 3;
// If the request needs to be forwarded from a reporting node to a p2p node, // If the request needs to be forwarded from a reporting node to a p2p node,
// the reporting node will set this field. Clients should not set this // the reporting node will set this field. Clients should not set this
// field. // field.
string client_ip = 4; string client_ip = 4;
} }
message GetLedgerDiffResponse message GetLedgerDiffResponse {
{ // All ledger objects that were added, modified or deleted between
// All ledger objects that were added, modified or deleted between // base_ledger and desired_ledger
// base_ledger and desired_ledger RawLedgerObjects ledger_objects = 1;
RawLedgerObjects ledger_objects = 1;
} }

32
include/xrpl/proto/org/xrpl/rpc/v1/get_ledger_entry.proto
View File

@@ -7,25 +7,23 @@ option java_multiple_files = true;
import "org/xrpl/rpc/v1/ledger.proto"; import "org/xrpl/rpc/v1/ledger.proto";
// Get a single ledger object // Get a single ledger object
message GetLedgerEntryRequest message GetLedgerEntryRequest {
{ // Key of the desired object
// Key of the desired object bytes key = 1;
bytes key = 1;
// Ledger containing the object // Ledger containing the object
LedgerSpecifier ledger = 2; LedgerSpecifier ledger = 2;
// If the request needs to be forwarded from a reporting node to a p2p node, // If the request needs to be forwarded from a reporting node to a p2p node,
// the reporting node will set this field. Clients should not set this // the reporting node will set this field. Clients should not set this
// field. // field.
string client_ip = 3; string client_ip = 3;
} }
message GetLedgerEntryResponse message GetLedgerEntryResponse {
{ RawLedgerObject ledger_object = 1;
RawLedgerObject ledger_object = 1;
// Ledger containing the object. Will match the value specified in the // Ledger containing the object. Will match the value specified in the
// request. // request.
LedgerSpecifier ledger = 2; LedgerSpecifier ledger = 2;
} }

88
include/xrpl/proto/org/xrpl/rpc/v1/ledger.proto
View File

@@ -5,71 +5,61 @@ option java_package = "org.xrpl.rpc.v1";
option java_multiple_files = true; option java_multiple_files = true;
// Next field: 4 // Next field: 4
message LedgerSpecifier message LedgerSpecifier {
{ // Next field: 4
// Next field: 4 enum Shortcut {
enum Shortcut SHORTCUT_UNSPECIFIED = 0;
{ SHORTCUT_VALIDATED = 1;
SHORTCUT_UNSPECIFIED = 0; SHORTCUT_CLOSED = 2;
SHORTCUT_VALIDATED = 1; SHORTCUT_CURRENT = 3;
SHORTCUT_CLOSED = 2; }
SHORTCUT_CURRENT = 3;
}
oneof ledger oneof ledger {
{ Shortcut shortcut = 1;
Shortcut shortcut = 1; uint32 sequence = 2;
uint32 sequence = 2; // 32 bytes
// 32 bytes bytes hash = 3;
bytes hash = 3; }
}
} }
// Next field: 3 // Next field: 3
message RawLedgerObject message RawLedgerObject {
{ // Raw data of the ledger object. In GetLedgerResponse and
// Raw data of the ledger object. In GetLedgerResponse and // GetLedgerDiffResponse, data will be empty if the object was deleted.
// GetLedgerDiffResponse, data will be empty if the object was deleted. bytes data = 1;
bytes data = 1;
// Key of the ledger object // Key of the ledger object
bytes key = 2; bytes key = 2;
enum ModificationType enum ModificationType {
{ UNSPECIFIED = 0;
UNSPECIFIED = 0; CREATED = 1;
CREATED = 1; MODIFIED = 2;
MODIFIED = 2; DELETED = 3;
DELETED = 3; }
}
// Whether the object was created, modified or deleted // Whether the object was created, modified or deleted
ModificationType mod_type = 3; ModificationType mod_type = 3;
// Key of the object preceding this object in the desired ledger // Key of the object preceding this object in the desired ledger
bytes predecessor = 4; bytes predecessor = 4;
// Key of the object succeeding this object in the desired ledger // Key of the object succeeding this object in the desired ledger
bytes successor = 5; bytes successor = 5;
} }
message RawLedgerObjects message RawLedgerObjects {
{ repeated RawLedgerObject objects = 1;
repeated RawLedgerObject objects = 1;
} }
// Successor information for book directories. The book base is (usually) not // Successor information for book directories. The book base is (usually) not
// an actual object, yet we need to be able to ask for the successor to the // an actual object, yet we need to be able to ask for the successor to the
// book base. // book base.
message BookSuccessor { message BookSuccessor {
// Base of the book in question
bytes book_base = 1;
// Base of the book in question // First book directory in the book. An empty value here means the entire
bytes book_base = 1; // book is deleted
bytes first_book = 2;
// First book directory in the book. An empty value here means the entire
// book is deleted
bytes first_book = 2;
}; };

3
include/xrpl/proto/org/xrpl/rpc/v1/xrp_ledger.proto
View File

@@ -9,13 +9,11 @@ import "org/xrpl/rpc/v1/get_ledger_entry.proto";
import "org/xrpl/rpc/v1/get_ledger_data.proto"; import "org/xrpl/rpc/v1/get_ledger_data.proto";
import "org/xrpl/rpc/v1/get_ledger_diff.proto"; import "org/xrpl/rpc/v1/get_ledger_diff.proto";
// These methods are binary only methods for retrieiving arbitrary ledger state // These methods are binary only methods for retrieiving arbitrary ledger state
// via gRPC. These methods are used by clio, but can also be // via gRPC. These methods are used by clio, but can also be
// used by any client that wants to extract ledger state in an efficient manner. // used by any client that wants to extract ledger state in an efficient manner.
// They do not directly mimic the JSON equivalent methods. // They do not directly mimic the JSON equivalent methods.
service XRPLedgerAPIService { service XRPLedgerAPIService {
// Get a specific ledger, optionally including transactions and any modified, // Get a specific ledger, optionally including transactions and any modified,
// added or deleted ledger objects // added or deleted ledger objects
rpc GetLedger(GetLedgerRequest) returns (GetLedgerResponse); rpc GetLedger(GetLedgerRequest) returns (GetLedgerResponse);
@@ -29,5 +27,4 @@ service XRPLedgerAPIService {
// Get all ledger objects that are different between the two specified // Get all ledger objects that are different between the two specified
// ledgers. Note, this method has no JSON equivalent. // ledgers. Note, this method has no JSON equivalent.
rpc GetLedgerDiff(GetLedgerDiffRequest) returns (GetLedgerDiffResponse); rpc GetLedgerDiff(GetLedgerDiffRequest) returns (GetLedgerDiffResponse);
} }

500
include/xrpl/proto/ripple.proto
View File

@@ -4,29 +4,28 @@ package protocol;
// Unused numbers in the list below may have been used previously. Please don't // Unused numbers in the list below may have been used previously. Please don't
// reassign them for reuse unless you are 100% certain that there won't be a // reassign them for reuse unless you are 100% certain that there won't be a
// conflict. Even if you're sure, it's probably best to assign a new type. // conflict. Even if you're sure, it's probably best to assign a new type.
enum MessageType enum MessageType {
{ mtMANIFESTS = 2;
mtMANIFESTS = 2; mtPING = 3;
mtPING = 3; mtCLUSTER = 5;
mtCLUSTER = 5; mtENDPOINTS = 15;
mtENDPOINTS = 15; mtTRANSACTION = 30;
mtTRANSACTION = 30; mtGET_LEDGER = 31;
mtGET_LEDGER = 31; mtLEDGER_DATA = 32;
mtLEDGER_DATA = 32; mtPROPOSE_LEDGER = 33;
mtPROPOSE_LEDGER = 33; mtSTATUS_CHANGE = 34;
mtSTATUS_CHANGE = 34; mtHAVE_SET = 35;
mtHAVE_SET = 35; mtVALIDATION = 41;
mtVALIDATION = 41; mtGET_OBJECTS = 42;
mtGET_OBJECTS = 42; mtVALIDATORLIST = 54;
mtVALIDATORLIST = 54; mtSQUELCH = 55;
mtSQUELCH = 55; mtVALIDATORLISTCOLLECTION = 56;
mtVALIDATORLISTCOLLECTION = 56; mtPROOF_PATH_REQ = 57;
mtPROOF_PATH_REQ = 57; mtPROOF_PATH_RESPONSE = 58;
mtPROOF_PATH_RESPONSE = 58; mtREPLAY_DELTA_REQ = 59;
mtREPLAY_DELTA_REQ = 59; mtREPLAY_DELTA_RESPONSE = 60;
mtREPLAY_DELTA_RESPONSE = 60; mtHAVE_TRANSACTIONS = 63;
mtHAVE_TRANSACTIONS = 63; mtTRANSACTIONS = 64;
mtTRANSACTIONS = 64;
} }
// token, iterations, target, challenge = issue demand for proof of work // token, iterations, target, challenge = issue demand for proof of work
@@ -36,352 +35,309 @@ enum MessageType
//------------------------------------------------------------------------------ //------------------------------------------------------------------------------
/* Provides the current ephemeral key for a validator. */ /* Provides the current ephemeral key for a validator. */
message TMManifest message TMManifest {
{ // A Manifest object in the Ripple serialization format.
// A Manifest object in the Ripple serialization format. required bytes stobject = 1;
required bytes stobject = 1;
} }
message TMManifests message TMManifests {
{ repeated TMManifest list = 1;
repeated TMManifest list = 1;
// The manifests sent when a peer first connects to another peer are `history`. // The manifests sent when a peer first connects to another peer are `history`.
optional bool history = 2 [deprecated=true]; optional bool history = 2 [deprecated = true];
} }
//------------------------------------------------------------------------------ //------------------------------------------------------------------------------
// The status of a node in our cluster // The status of a node in our cluster
message TMClusterNode message TMClusterNode {
{ required string publicKey = 1;
required string publicKey = 1; required uint32 reportTime = 2;
required uint32 reportTime = 2; required uint32 nodeLoad = 3;
required uint32 nodeLoad = 3; optional string nodeName = 4;
optional string nodeName = 4; optional string address = 5;
optional string address = 5;
} }
// Sources that are placing load on the server // Sources that are placing load on the server
message TMLoadSource message TMLoadSource {
{ required string name = 1;
required string name = 1; required uint32 cost = 2;
required uint32 cost = 2; optional uint32 count = 3; // number of connections
optional uint32 count = 3; // number of connections
} }
// The status of all nodes in the cluster // The status of all nodes in the cluster
message TMCluster message TMCluster {
{ repeated TMClusterNode clusterNodes = 1;
repeated TMClusterNode clusterNodes = 1; repeated TMLoadSource loadSources = 2;
repeated TMLoadSource loadSources = 2;
} }
// Node public key // Node public key
message TMLink message TMLink {
{ required bytes nodePubKey = 1 [deprecated = true]; // node public key
required bytes nodePubKey = 1 [deprecated=true]; // node public key
} }
// Peer public key // Peer public key
message TMPublicKey message TMPublicKey {
{ required bytes publicKey = 1;
required bytes publicKey = 1;
} }
// A transaction can have only one input and one output. // A transaction can have only one input and one output.
// If you want to send an amount that is greater than any single address of yours // If you want to send an amount that is greater than any single address of yours
// you must first combine coins from one address to another. // you must first combine coins from one address to another.
enum TransactionStatus enum TransactionStatus {
{ tsNEW = 1; // origin node did/could not validate
tsNEW = 1; // origin node did/could not validate tsCURRENT = 2; // scheduled to go in this ledger
tsCURRENT = 2; // scheduled to go in this ledger tsCOMMITED = 3; // in a closed ledger
tsCOMMITED = 3; // in a closed ledger tsREJECT_CONFLICT = 4;
tsREJECT_CONFLICT = 4; tsREJECT_INVALID = 5;
tsREJECT_INVALID = 5; tsREJECT_FUNDS = 6;
tsREJECT_FUNDS = 6; tsHELD_SEQ = 7;
tsHELD_SEQ = 7; tsHELD_LEDGER = 8; // held for future ledger
tsHELD_LEDGER = 8; // held for future ledger
} }
message TMTransaction message TMTransaction {
{ required bytes rawTransaction = 1;
required bytes rawTransaction = 1; required TransactionStatus status = 2;
required TransactionStatus status = 2; optional uint64 receiveTimestamp = 3;
optional uint64 receiveTimestamp = 3; optional bool deferred = 4; // not applied to open ledger
optional bool deferred = 4; // not applied to open ledger
} }
message TMTransactions message TMTransactions {
{ repeated TMTransaction transactions = 1;
repeated TMTransaction transactions = 1;
} }
enum NodeStatus {
enum NodeStatus nsCONNECTING = 1; // acquiring connections
{ nsCONNECTED = 2; // convinced we are connected to the real network
nsCONNECTING = 1; // acquiring connections nsMONITORING = 3; // we know what the previous ledger is
nsCONNECTED = 2; // convinced we are connected to the real network nsVALIDATING = 4; // we have the full ledger contents
nsMONITORING = 3; // we know what the previous ledger is nsSHUTTING = 5; // node is shutting down
nsVALIDATING = 4; // we have the full ledger contents
nsSHUTTING = 5; // node is shutting down
} }
enum NodeEvent enum NodeEvent {
{ neCLOSING_LEDGER = 1; // closing a ledger because its close time has come
neCLOSING_LEDGER = 1; // closing a ledger because its close time has come neACCEPTED_LEDGER = 2; // accepting a closed ledger, we have finished computing it
neACCEPTED_LEDGER = 2; // accepting a closed ledger, we have finished computing it neSWITCHED_LEDGER = 3; // changing due to network consensus
neSWITCHED_LEDGER = 3; // changing due to network consensus neLOST_SYNC = 4;
neLOST_SYNC = 4;
} }
message TMStatusChange message TMStatusChange {
{ optional NodeStatus newStatus = 1;
optional NodeStatus newStatus = 1; optional NodeEvent newEvent = 2;
optional NodeEvent newEvent = 2; optional uint32 ledgerSeq = 3;
optional uint32 ledgerSeq = 3; optional bytes ledgerHash = 4;
optional bytes ledgerHash = 4; optional bytes ledgerHashPrevious = 5;
optional bytes ledgerHashPrevious = 5; optional uint64 networkTime = 6;
optional uint64 networkTime = 6; optional uint32 firstSeq = 7;
optional uint32 firstSeq = 7; optional uint32 lastSeq = 8;
optional uint32 lastSeq = 8;
} }
// Announce to the network our position on a closing ledger // Announce to the network our position on a closing ledger
message TMProposeSet message TMProposeSet {
{ required uint32 proposeSeq = 1;
required uint32 proposeSeq = 1; required bytes currentTxHash = 2; // the hash of the ledger we are proposing
required bytes currentTxHash = 2; // the hash of the ledger we are proposing required bytes nodePubKey = 3;
required bytes nodePubKey = 3; required uint32 closeTime = 4;
required uint32 closeTime = 4; required bytes signature = 5; // signature of above fields
required bytes signature = 5; // signature of above fields required bytes previousledger = 6;
required bytes previousledger = 6; repeated bytes addedTransactions = 10; // not required if number is large
repeated bytes addedTransactions = 10; // not required if number is large repeated bytes removedTransactions = 11; // not required if number is large
repeated bytes removedTransactions = 11; // not required if number is large
// node vouches signature is correct // node vouches signature is correct
optional bool checkedSignature = 7 [deprecated=true]; optional bool checkedSignature = 7 [deprecated = true];
// Number of hops traveled // Number of hops traveled
optional uint32 hops = 12 [deprecated=true]; optional uint32 hops = 12 [deprecated = true];
} }
enum TxSetStatus enum TxSetStatus {
{ tsHAVE = 1; // We have this set locally
tsHAVE = 1; // We have this set locally tsCAN_GET = 2; // We have a peer with this set
tsCAN_GET = 2; // We have a peer with this set tsNEED = 3; // We need this set and can't get it
tsNEED = 3; // We need this set and can't get it
} }
message TMHaveTransactionSet message TMHaveTransactionSet {
{ required TxSetStatus status = 1;
required TxSetStatus status = 1; required bytes hash = 2;
required bytes hash = 2;
} }
// Validator list (UNL) // Validator list (UNL)
message TMValidatorList message TMValidatorList {
{ required bytes manifest = 1;
required bytes manifest = 1; required bytes blob = 2;
required bytes blob = 2; required bytes signature = 3;
required bytes signature = 3; required uint32 version = 4;
required uint32 version = 4;
} }
// Validator List v2 // Validator List v2
message ValidatorBlobInfo message ValidatorBlobInfo {
{ optional bytes manifest = 1;
optional bytes manifest = 1; required bytes blob = 2;
required bytes blob = 2; required bytes signature = 3;
required bytes signature = 3;
} }
// Collection of Validator List v2 (UNL) // Collection of Validator List v2 (UNL)
message TMValidatorListCollection message TMValidatorListCollection {
{ required uint32 version = 1;
required uint32 version = 1; required bytes manifest = 2;
required bytes manifest = 2; repeated ValidatorBlobInfo blobs = 3;
repeated ValidatorBlobInfo blobs = 3;
} }
// Used to sign a final closed ledger after reprocessing // Used to sign a final closed ledger after reprocessing
message TMValidation message TMValidation {
{ // The serialized validation
// The serialized validation required bytes validation = 1;
required bytes validation = 1;
// node vouches signature is correct // node vouches signature is correct
optional bool checkedSignature = 2 [deprecated = true]; optional bool checkedSignature = 2 [deprecated = true];
// Number of hops traveled // Number of hops traveled
optional uint32 hops = 3 [deprecated = true]; optional uint32 hops = 3 [deprecated = true];
} }
// An array of Endpoint messages // An array of Endpoint messages
message TMEndpoints message TMEndpoints {
{ // Previously used - don't reuse.
// Previously used - don't reuse. reserved 2;
reserved 2;
// This field is used to allow the TMEndpoints message format to be // This field is used to allow the TMEndpoints message format to be
// modified as necessary in the future. // modified as necessary in the future.
required uint32 version = 1; required uint32 version = 1;
// An update to the Endpoint type that uses a string // An update to the Endpoint type that uses a string
// to represent endpoints, thus allowing ipv6 or ipv4 addresses // to represent endpoints, thus allowing ipv6 or ipv4 addresses
message TMEndpointv2 message TMEndpointv2 {
{ required string endpoint = 1;
required string endpoint = 1; required uint32 hops = 2;
required uint32 hops = 2; }
} repeated TMEndpointv2 endpoints_v2 = 3;
repeated TMEndpointv2 endpoints_v2 = 3;
}; };
message TMIndexedObject message TMIndexedObject {
{ optional bytes hash = 1;
optional bytes hash = 1; optional bytes nodeID = 2;
optional bytes nodeID = 2; optional bytes index = 3;
optional bytes index = 3; optional bytes data = 4;
optional bytes data = 4; optional uint32 ledgerSeq = 5;
optional uint32 ledgerSeq = 5;
} }
message TMGetObjectByHash message TMGetObjectByHash {
{ enum ObjectType {
enum ObjectType { otUNKNOWN = 0;
otUNKNOWN = 0; otLEDGER = 1;
otLEDGER = 1; otTRANSACTION = 2;
otTRANSACTION = 2; otTRANSACTION_NODE = 3;
otTRANSACTION_NODE = 3; otSTATE_NODE = 4;
otSTATE_NODE = 4; otCAS_OBJECT = 5;
otCAS_OBJECT = 5; otFETCH_PACK = 6;
otFETCH_PACK = 6; otTRANSACTIONS = 7;
otTRANSACTIONS = 7; }
}
required ObjectType type = 1; required ObjectType type = 1;
required bool query = 2; // is this a query or a reply? required bool query = 2; // is this a query or a reply?
optional uint32 seq = 3; // used to match replies to queries optional uint32 seq = 3; // used to match replies to queries
optional bytes ledgerHash = 4; // the hash of the ledger these queries are for optional bytes ledgerHash = 4; // the hash of the ledger these queries are for
optional bool fat = 5; // return related nodes optional bool fat = 5; // return related nodes
repeated TMIndexedObject objects = 6; // the specific objects requested repeated TMIndexedObject objects = 6; // the specific objects requested
} }
message TMLedgerNode {
message TMLedgerNode required bytes nodedata = 1;
{ optional bytes nodeid = 2; // missing for ledger base data
required bytes nodedata = 1;
optional bytes nodeid = 2; // missing for ledger base data
} }
enum TMLedgerInfoType enum TMLedgerInfoType {
{ liBASE = 0; // basic ledger info
liBASE = 0; // basic ledger info liTX_NODE = 1; // transaction node
liTX_NODE = 1; // transaction node liAS_NODE = 2; // account state node
liAS_NODE = 2; // account state node liTS_CANDIDATE = 3; // candidate transaction set
liTS_CANDIDATE = 3; // candidate transaction set
} }
enum TMLedgerType enum TMLedgerType {
{ ltACCEPTED = 0;
ltACCEPTED = 0; ltCURRENT = 1; // no longer supported
ltCURRENT = 1; // no longer supported ltCLOSED = 2;
ltCLOSED = 2;
} }
enum TMQueryType enum TMQueryType {
{ qtINDIRECT = 0;
qtINDIRECT = 0;
} }
message TMGetLedger message TMGetLedger {
{ required TMLedgerInfoType itype = 1;
required TMLedgerInfoType itype = 1; optional TMLedgerType ltype = 2;
optional TMLedgerType ltype = 2; optional bytes ledgerHash = 3; // Can also be the transaction set hash if liTS_CANDIDATE
optional bytes ledgerHash = 3; // Can also be the transaction set hash if liTS_CANDIDATE optional uint32 ledgerSeq = 4;
optional uint32 ledgerSeq = 4; repeated bytes nodeIDs = 5;
repeated bytes nodeIDs = 5; optional uint64 requestCookie = 6;
optional uint64 requestCookie = 6; optional TMQueryType queryType = 7;
optional TMQueryType queryType = 7; optional uint32 queryDepth = 8; // How deep to go, number of extra levels
optional uint32 queryDepth = 8; // How deep to go, number of extra levels
} }
enum TMReplyError enum TMReplyError {
{ reNO_LEDGER = 1; // We don't have the ledger you are asking about
reNO_LEDGER = 1; // We don't have the ledger you are asking about reNO_NODE = 2; // We don't have any of the nodes you are asking for
reNO_NODE = 2; // We don't have any of the nodes you are asking for reBAD_REQUEST = 3; // The request is wrong, e.g. wrong format
reBAD_REQUEST = 3; // The request is wrong, e.g. wrong format
} }
message TMLedgerData message TMLedgerData {
{ required bytes ledgerHash = 1;
required bytes ledgerHash = 1; required uint32 ledgerSeq = 2;
required uint32 ledgerSeq = 2; required TMLedgerInfoType type = 3;
required TMLedgerInfoType type = 3; repeated TMLedgerNode nodes = 4;
repeated TMLedgerNode nodes = 4; optional uint32 requestCookie = 5;
optional uint32 requestCookie = 5; optional TMReplyError error = 6;
optional TMReplyError error = 6;
} }
message TMPing message TMPing {
{ enum pingType {
enum pingType { ptPING = 0; // we want a reply
ptPING = 0; // we want a reply ptPONG = 1; // this is a reply
ptPONG = 1; // this is a reply }
} required pingType type = 1;
required pingType type = 1; optional uint32 seq = 2; // detect stale replies, ensure other side is reading
optional uint32 seq = 2; // detect stale replies, ensure other side is reading optional uint64 pingTime = 3; // know when we think we sent the ping
optional uint64 pingTime = 3; // know when we think we sent the ping optional uint64 netTime = 4;
optional uint64 netTime = 4;
} }
message TMSquelch message TMSquelch {
{ required bool squelch = 1; // squelch if true, otherwise unsquelch
required bool squelch = 1; // squelch if true, otherwise unsquelch required bytes validatorPubKey = 2; // validator's public key
required bytes validatorPubKey = 2; // validator's public key optional uint32 squelchDuration = 3; // squelch duration in seconds
optional uint32 squelchDuration = 3; // squelch duration in seconds
} }
enum TMLedgerMapType enum TMLedgerMapType {
{ lmTRANASCTION = 1; // transaction map
lmTRANASCTION = 1; // transaction map lmACCOUNT_STATE = 2; // account state map
lmACCOUNT_STATE = 2; // account state map
} }
message TMProofPathRequest message TMProofPathRequest {
{ required bytes key = 1;
required bytes key = 1; required bytes ledgerHash = 2;
required bytes ledgerHash = 2; required TMLedgerMapType type = 3;
required TMLedgerMapType type = 3;
} }
message TMProofPathResponse message TMProofPathResponse {
{ required bytes key = 1;
required bytes key = 1; required bytes ledgerHash = 2;
required bytes ledgerHash = 2; required TMLedgerMapType type = 3;
required TMLedgerMapType type = 3; optional bytes ledgerHeader = 4;
optional bytes ledgerHeader = 4; repeated bytes path = 5;
repeated bytes path = 5; optional TMReplyError error = 6;
optional TMReplyError error = 6;
} }
message TMReplayDeltaRequest message TMReplayDeltaRequest {
{ required bytes ledgerHash = 1;
required bytes ledgerHash = 1;
} }
message TMReplayDeltaResponse message TMReplayDeltaResponse {
{ required bytes ledgerHash = 1;
required bytes ledgerHash = 1; optional bytes ledgerHeader = 2;
optional bytes ledgerHeader = 2; repeated bytes transaction = 3;
repeated bytes transaction = 3; optional TMReplyError error = 4;
optional TMReplyError error = 4;
} }
message TMHaveTransactions message TMHaveTransactions {
{ repeated bytes hashes = 1;
repeated bytes hashes = 1;
} }