Improve rustdocs on `display_secret` by doing:
- Minor improvements to the rustdocs to aid readability in the editor.
- Do not guarantee (`assert_eq!`) debug output
The `serialize_secret` method is a getter method, it does not do any
serialisation. However we use the method on secret keys and key types so
in order for the name to be uniform use the descriptive name
`secret_bytes`.
Rename `serialize_secret` to be `secret_bytes`.
The identifier `i` is predominantly used for indexing an array but we
are using it as a place holder for the iterated value of an array that
is then printed. The identifier `byte` is more descriptive.
Done in preparation for adding similar code to the `ecdh` module.
In array initialisation we use magic number 64, this is the secret bytes
length multiplied by 2.
Please note; we still use the magic number 32, left as such because it
is used in various ways and its not immediately clear that using a
single const would be any more descriptive.
Use `SECRET_KEY_SIZE * 2` instead of magic number 64.
Hashing the debug output for secrets can be done with `bitcoin_hashes`
not just `std`. Mention this in the obfuscated string output when
neither are available.
5603d71ad3 Limit SharedSecret to 32 byte buffer (Tobin Harding)
d5eeb099ad Use more intuitive local var numbering (Tobin Harding)
834f63c26c Separate new_with_hash into public function (Tobin Harding)
Pull request description:
Currently `SharedSecret` provides a way to get a shared secret using SHA256 _as well as_ a way to use a custom hash function to get the shared secret. Internally `SharedSecret` uses a 256 byte buffer, this is a tad wasteful. We would like to keep the current functionality but reduce memory usage.
- Patch 1: Pulls the `new_with_hash` logic out into a standalone public function that just returns the 64 bytes representing the x,y co-ordinates of the computed shared secret point. Callers are then responsible for hashing this point to get the shared secret (idea by @Kixunil, thanks).
- Patch 2: Does trivial refactor
- Patch 3: Uses a 32 byte buffer internally for `SharedSecret`. This is basically a revert of the work @elichai did to add the custom hashing logic. @elichai please holla if you are not happy with me walking all over this code :)
### Note to reviewers
Secret obfuscation is done on top of this in https://github.com/rust-bitcoin/rust-secp256k1/pull/396, they could be reviewed in order if this work is of interest to you.
ACKs for top commit:
apoelstra:
ACK 5603d71ad3
Tree-SHA512: 48982a4a6a700a111e4c1d5d21d62503d34f433d8cb303d11ff018d2f2be2467fa806107018db16b6d0fcc5ff1a0325dd5790c62c47831c7cd2141a1b6f9467d
e6cb588a23 Breaking: changed `Parity` serialization to `u8` (Martin Habovstiak)
Pull request description:
Serializing the value as `u8` is more compact but this is a breaking
change.
`Visitor` was renamed to avoid hungarian notation and maybe allow other
integers in the future.
For next major version, depends on #400
ACKs for top commit:
tcharding:
tACK e6cb588
apoelstra:
ACK e6cb588a23
Tree-SHA512: 1432a2f3c913c3a7eaec5228fd2dd4e8320d828128bec71812cbf56dd8950c969ed22c69867402eb9e820127868d29b291f3374c6e15de0a3ff2341420c4bbab
65d32af6fd bump version to 0.21.3 (Andrew Poelstra)
Pull request description:
We've got a ton of minor changes in, plus fixing the Parity type and adding some extra serde impls. Let's push a minor version out so that we can move on to updating the upstream libsecp.
Top commit has no ACKs.
Tree-SHA512: 584c03106124b4152b8971ac6d0587a26d2aca9187f88d8228a356c2327bf066d2c9b8134149f9ee3bc5f3712f64559b32843aa8e92d3395c5a1bd53de5442ce
2a25e5eae8 restore `global-context-less-secure` feature (Andrew Poelstra)
Pull request description:
We can't remove a feature in a minor release, and also I believe this feature is actually necessary in some niche applications.
ACKs for top commit:
elichai:
utACK 2a25e5eae8
Tree-SHA512: bad6e40dcf625d231568e7336c0996e8b7d1aed8883c7ea475dd7248a98232a27796bbd1cae23ffbd81336d08e3ebaab4b2d559bf9f6f5f17801e91588871b58
The `SharedSecret` uses sha256 to hash the secret, this implies the
secret is 32 bytes of data.
Currently we use a buffer of 256 bytes, this is unnecessary.
Change the implementation of `SharedSecret` to use a 32 byte buffer.
In test code we use multiple pub/sec keys. It is more intuitive if the
'secret 1' is generated by the owner of secret key 1.
Refactor only, no logic changes.
In preparation for simplifying the `SharedSecret` internals pull the
`new_with_hash` function logic out into a standalone public function
that provides similar functionality without use of the `SharedSecret`
struct. Function now returns the 64 bytes of data representing a shared
point on the curve, callers are expected to the hash these bytes to get
a shared secret.
4c9bab9f6e Remove explicit mention of feature requirements (Tobin Harding)
806eaca5f1 Use feature std with rand-std (Tobin Harding)
Pull request description:
Recently we fixed a bunch of feature gates to use `rand-std` instead
of `rand` but in doing so did not notice that the same feature gates
were using `alloc` which is meaningless if `std` is enabled.
- Patch 1: Feature gate on `std` if we are using `rand-std`.
- Patch 2: Remove redundant docs related to feature gating.
ACKs for top commit:
apoelstra:
ACK 4c9bab9f6e
Tree-SHA512: 316303e34dfcf62ffce2aa01742131b9ca6143895110b7e49c9aab376cfeb5cc0573d040504710a7e1bfdd0ab85b2ffa13c79c5d1176b32eecc3713482f6114e
We are using `cfg_attr` to instruct the rustdocs build system to
highlight feature requirements for functions, there is no need to
explicitly mention feature requirements in the text.
Recently we fixed a bunch of feature gates to use `rand-std` instead
of `rand` but in doing so did not notice that the same feature gates
were using `alloc` which is meaningless if `std` is enabled.
Feature gate on `std` if we are using `rand-std`.
c73eb2f391 Use 'extra' instead of 'cheap' (Tobin Harding)
c79eb976ca Remove unnecessary explanation (Tobin Harding)
f95e91a6da Use isn't instead of shouldn't (Tobin Harding)
c9e6ca1680 Use rust-bitcoin module doc style (Tobin Harding)
3fa6762437 Add link to referenced commit (Tobin Harding)
f5e68f3ba7 Add ticks around code snippet (Tobin Harding)
d25431c1da Use 3rd person tense for function docs (Tobin Harding)
c3be285c1d Fix size constant docs (Tobin Harding)
5e07e7596b Add period to sentences (Tobin Harding)
269bde042f Remove unnecessary capitalisation (Tobin Harding)
Pull request description:
In a continued effort to find my feet around here, and inspired by issue #128 I've done a codebase wide audit of the docs (primarily just rustdocs but I glanced at `//` docs as well). Each change is in a separate commit so can be removed if resistance is met. (_"resistance is futile"_).
I've based the stylistic decisions on [work done](https://github.com/rust-bitcoin/rust-bitcoin/pull/704) in rust-bitcoin.
I believe the only controversial change is the last (commit: da161c9 Use rust-bitcoin module doc style), please review that one carefully.
ACKs for top commit:
apoelstra:
ACK c73eb2f391
Tree-SHA512: 5ea215de3fd23ca2a4f25d8f8d59a85a299044fe495269c43b621291ea50c58856fa8544e36cc109b7bdb1a7a59bcab8711f30113572ddce4509d3b06ff0d3b6
662843e73b Improved error handling in `Parity` serde impl (Martin Habovstiak)
Pull request description:
* Fixes error message to be according to the trait documentation
* Uses `unexpected_value` to provide more information about the error
ACKs for top commit:
apoelstra:
ACK 662843e73b
Tree-SHA512: 2506f06305b01793f64818640931d00564334d96a1e0ef00574faacf1ec8733da13fbf91e57e49fa7c9c06587863fe66145f25afae8d8cabe546dd0ecc48caea
Serializing the value as `u8` is more compact but this is a breaking
change.
`Visitor` was renamed to avoid hungarian notation and maybe allow other
integers in the future.
705c9cfbc1 Clarified conversions between `Parity` and integers (Martin Habovstiak)
Pull request description:
This was discussed in https://github.com/rust-bitcoin/rust-secp256k1/pull/390#issuecomment-1033018430
ACKs for top commit:
apoelstra:
ACK 705c9cfbc1
Tree-SHA512: 3ba2ec566099c3c6d1c6f830e4959312b818b8766d924e3d995e6b23bd196ab747cc03d46f494ef451569188b0163f53e3236cacd20bfae9118ee76bcdbc9c02
4c43d5e20f Add custom Debug impl for RecoverableSignature (Tobin Harding)
Pull request description:
Currently when debug printing the `RecoverableSignature` we do so byte by byte, this means that the output differs depending on the endianess of the machine. If instead we serialize the signature in compact form then the output is the same irrespective of the endianess.
With this applied the following two commands now pass:
```
cargo test test_debug_output --features=recovery
```
```
cross test --target powerpc-unknown-linux-gnu test_debug_output --features=recovery
```
Fixes: #375
ACKs for top commit:
apoelstra:
ACK 4c43d5e20f
Tree-SHA512: 073c2e0e23ce41a2b35f1b1193b07a755b726bf565d61e6bcb23b6bdaab31ba3591f31aa92230b07f7dfc018de0401eba09a6858dc261e66dacb331355f40d76
3c9dd2fb32 Fix example dependency list (Tobin Harding)
Pull request description:
Example relies on `rand-std` not plain `rand` dependency.
I do not understand why the following command passes without this patch
applied
```
cargo test --no-default-features --features=std,rand,bitcoin_hashes
```
But if we put the same code in a standalone binary it fails as expected?
Since the running of this test is _unusual_ and it is primarily meant as
an entry point example to the library, remove the mention of "alloc"
feature and just depend upon "std".
Fixes: #395
ACKs for top commit:
apoelstra:
ACK 3c9dd2fb32
Tree-SHA512: 8e7ec7ac846e2916c29b74c7485650e5242ae1141c12c69b50d74efdfee71c11a52cd454231d2a7cdd6f8f683d3ba4369f9bf898a6b9351dc92c2a4e2bd626cd
eb453b8227 Add global context API (Tobin Harding)
3ecb5e41b3 Refactor from_secret_key definition (Tobin Harding)
e2d47a29e2 Remove unnecessary import statement (Tobin Harding)
d79989bc95 Remove erroneous duplicate feature (Tobin Harding)
Pull request description:
Our API often involves a `Secp256k1` parameter, when users enable the `global-context` feature they must then pass `SECP256K1` into these functions. This is kind of clunky since the global is by definition available everywhere.
Make the API more ergonomic for `global-context` builds by adding various API functions/methods that use the global context implicitly.
The first 3 patches are clean up.
Resolves: #330
ACKs for top commit:
apoelstra:
ACK eb453b8227
Tree-SHA512: 21d89a6688c24a7920d48ea92d923889bec2bbe9dc5ed5e33639405be45a50f50022a28dc1f235b8bea850ac39013c7dd24b5aed086ed40f5b259dd44c06433d
Our API often involves a `Secp256k1` parameter, when users enable the
`global-context` feature they must then pass `SECP256K1` into these
functions. This is kind of clunky since the global is by definition
available everywhere.
Make the API more ergonomic for `global-context` builds by adding
various API functions/methods that use the global context implicitly.
The global context is already in scope in tests since we use a glob
import. No clue why Clippy does not warn for this.
Remove unnecessary import statement in test function.
Recently we introduced uniform styling for module docs over in
`rust-bitcoin` repo. We can do the same here but its a bit controversial
because it removes the heading from module docs and every single public
module in rust-secp256k1 uses a heading. Instead we use a full
sentences. Also makes uniform the trailing `//!`.
As is typical in the Rust ecosystem use the third person tense when
documenting functions. E.g.,
```
/// Creates a new Foo.
```
As opposed to
```
/// Create a new Foo.
```
Example relies on `rand-std` not plain `rand` dependency.
I do not understand why the following command passes without this patch
applied
```
cargo test --no-default-features --features=std,rand,bitcoin_hashes
```
But if we put the same code in a standalone binary it fails as expected?
Since the running of this test is _unusual_ and it is primarily meant as
an entry point example to the library, remove the mention of "alloc"
feature and just depend upon "std".
Currently when debug printing the `RecoverableSignature` we do so byte
by byte, this means that the output differs depending on the endianess
of the machine. If instead we serialize the signature in compact form
then the output is the same irrespective of the endianess.
With this applied the following two commands now pass:
```
cargo test test_debug_output --features=recovery
```
cross test --target powerpc-unknown-linux-gnu test_debug_output --features=recovery
```
Fixes: #375
b3503ba148 Add example to SharedSecret (Tobin Harding)
Pull request description:
Currently the rustdoc on `SharedSecret` is wildly incorrect (possibly a cut'n'pasta error).
Fix the rustdoc for `SharedSecret` and add an examples section to assist testing the public API.
Fixes: #249
ACKs for top commit:
apoelstra:
ACK b3503ba148
Tree-SHA512: 650092388099bb415c11ea335ca6b64c90094f1a51ceecc403911316ee62da0279488af6fa66e00ee5269c129f06d4641085f8ab9be91c98d24a7a4449d235c2
8339ca5706 Add documentation guiding users towards randomization (Tobin Harding)
cf1496b64e Add documentation about rand-std feature (Tobin Harding)
1693d51ce7 Randomize context on creation (Tobin Harding)
a0465ea279 Remove feature global-context-less-secure (Tobin Harding)
Pull request description:
Currently it is easy for users to mis-use our API because they may not know that `randomize()` should be called after context creation for maximum defence against side channel attacks.
This PR entails the first two parts of the plan outlined in #388. The commit messages are a bit light of information as to _why_ we are doing this so please see #388 for more context.
In light of @real-or-random's [comment](https://github.com/rust-bitcoin/rust-secp256k1/issues/388#issuecomment-1026613592) about verification contexts the randomization is done in `gen_new` i.e., for _all_ contexts not just signing ones.
Also, I think we should add some docs about exactly _what_ randomization buys the user and what it costs. I do not know exactly what this is, can someone please write a sentence or two that we can include in the docs to `gen_new`?
@TheBlueMatt please review patch 4.
Resolves: #225
**Note**: This is a total re-write of the original PR, most of the discussion below is stale. Of note, the additional API that takes a seed during construction is not implemented here.
ACKs for top commit:
apoelstra:
ACK 8339ca5706
Tree-SHA512: e74fe9a6eaf8ac40e4e06997602006eb8ca95216b5bc6dca3f5f96b5b4d3bf8610d851d8f1ef5c199ab7fbe85b34d162f2ee0073647f45105a486d20d8c0722a
Currently the rustdoc on `SharedSecret` is wildly incorrect (possibly a
cut'n'pasta error).
Fix the rustdoc for `SharedSecret` and add an examples section to assist
testing the public API.
Fixes: 249
Now that we opportunistically randomize the context on creation if
`rand-std` is enabled it would be nice to encourage users who do not
wish to use `rand-std` to randomize the context. We already have an API
to do this but it requires a separate call to do so. Instead of adding a
bunch of additional constructors elect to add documentation to the
current constructors guiding users towards randomization.
We recently implemented opportunistic randomization of the context
object if the the `rand-std` feature is enabled. Both for the global
context and also for signing context constructors.
Add documentation about `rand-std` feature in relation to the context
object.
Tobin Harding
Andrew Poelstra
Martin Habovstiak