Update pubkey.rst #4586
Update pubkey.rst #4586
Conversation
randombit
force-pushed
the
jack/update-pubkey-rst
branch
from
3abebbd to
faf49c0
Compare
| RSA signature padding schemes | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| These signature padding mechanisms are specific to RSA; no other public | ||
| key algorithms included in Botan make use of then. For historical reasons, | ||
| many different padding schemes have been defined for RSA over the years. | ||
| The most common are PSS and the (now obsolete) PKCS1v15. | ||
|
|
There was a problem hiding this comment.
Thanks! I think this is really crucial information for crypto newcomers!
There was a problem hiding this comment.
The situation was a lot more confused in earlier releases
[Pre 2.0] Rabin-Williams and Nyberg-Rueppel could use the same padding schemes as RSA
"EMSA1" (aka the plain hash with possible truncation) was a real padding scheme that was used with *DSA and could be used with RSA as well.
Now things are pretty clearly bifurcated to "RSA specific" and "everyone else"
| Sign inputs directly with no hashing or padding | ||
|
|
||
| .. warning:: | ||
|
|
||
| This exists as an escape hatch allowing an application to define | ||
| some protocol-specific padding scheme. Don't use this unless you | ||
| know what you are doing. |
There was a problem hiding this comment.
Thinking out loud: once the PK_Options (#4318) are fully operational, we could potentially replace this escape hatch with the ability for a user to create their own subclass of EMSA to build application-specific paddings. And then pass it along as .with_padding(ptr_to_an_object_of_my_emsa). (Assuming that class EMSA is even public API.)
That makes it more involved to YOLO your own padding, with more boilerplate. But perhaps that's actually a good thing.
doc/api_ref/pubkey.rst
Outdated
| Return a shared key. The *salt* will be hashed along with the shared secret by the | ||
| KDF; this can be useful to bind the shared secret to a specific usage. |
There was a problem hiding this comment.
Perhaps add something like: "if no KDF was defined, the salt and the key length are typically ignored." (Or a formulation along those lines.)
I actually find this to be an API pitfall, because users might have designed their protocol around the idea of injecting that context while it fact it is just silently ignored. Here, a to-be-built API along the lines of PK_Options (#4318) might come in handy. It would make it easy to throw an exception if .with_salt() (or .with_output_length()) was given but no KDF actually ended up consuming those values in derive_key().
There was a problem hiding this comment.
Actually we already do reject a salt if a KDF is not being used but I agree with your point in the broad sense.
There was a problem hiding this comment.
Updated to describe how keylen param is ignored without a kdf
randombit
force-pushed
the
jack/update-pubkey-rst
branch
from
a5275f1 to
3236904
Compare
Along with a few doc comments in pubkey.h
Along with a few doc comments in pubkey.h