Documentation overhaul

[roblabla]

The documentation in this crate is currently a bit barebones. I'd be interested in working on enhancing the documentation. Here are some things I can think of that would be nice to document:

• RSAPrivateKey.sign Why is the Hash an Option? (Same question for verify). I assume passing None there means the "hashed" value is actually the raw message rather than a hash? That won't work for PSS verification.
• RSAPrivateKey.validate When is it necessary to call this function? What happens if a key is used without being valid? Why do the constructors not ensure validity?
• RSAPrivateKey.precompute Again, why not do this in new()? When is it necessary to call this function?
• What does "blinding" the decryption process mean? When is it useful? (Probably want to put a link to wikipedia or something here, but having some documentation about it directly in the crate would be most welcome).
• For all the enc/dec/sig/verif routines that are likely to be used, it would be nice to have a doctest showing how it should be used.

[dignifiedquire]

hey, much appreciate the interest and would love the help. I‘ll try and get some answers in here tomorrow. In the meantime you can look at the go lang std lib rsa implementation, which this implementation takes a lot of inspiration from.

…

On 18. Aug 2019, 20:27 +0200, Robin Lambertz ***@***.***>, wrote: The documentation in this crate is currently a bit barebones. I'd be interested in working on enhancing the documentation. Here are some things I can think of that would be nice to document: • RSAPrivateKey.sign Why is the Hash an Option? (Same question for verify). I assume passing None there means the "hashed" value is actually the raw message rather than a hash? That won't work for PSS verification. • RSAPrivateKey.validate When is it necessary to call this function? What happens if a key is used without being valid? Why do the constructors not ensure validity? • RSAPrivateKey.precompute Again, why not do this in new()? When is it necessary to call this function? • What does "blinding" the decryption process mean? When is it useful? (Probably want to put a link to wikipedia or something here, but having some documentation about it directly in the crate would be most welcome). • For all the enc/dec/sig/verif routines that are likely to be used, it would be nice to have a doctest showing how it should be used. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[dignifiedquire]

* Why is the Hash an Option? (Same question for verify). I assume passing None there means the "hashed" value is actually the raw message rather than a hash? That won't work for PSS verification.

Yes, it is a very important part of the api to be able to pass either hashed or not hashed values.

[dignifiedquire]

* When is it necessary to call this function? What happens if a key is used without being valid? Why do the constructors not ensure validity?

As far as I remember the validate call is there to ensure a given key is valid, if you don't know exactly where it comes from. Simplifying this into moving this into the constructor is likely possible.

[dignifiedquire]

* [RSAPrivateKey.precompute](https://docs.rs/rsa/0.1.3/rsa/struct.RSAPrivateKey.html#method.precompute) Again, why not do this in `new()`? When is it necessary to call this function?

It already is part of the construction, should just be marked as private instead of public

[dignifiedquire]

* What does "blinding" the decryption process mean? When is it useful? (Probably want to put a link to wikipedia or something here, but having some documentation about it directly in the crate would be most welcome).

yeah, some links

• https://en.wikipedia.org/wiki/Blinding_(cryptography)
• https://en.wikipedia.org/wiki/Blind_signature#Blind_RSA_signatures

[andrewbaxter]

Yeah the sign/verify behavior WRT hash was hard for me to understand, and I ended up having to look at the code to figure out how to use it. Basically it seems like hashed may or may not be hashed bytes, but needs to correspond to Hash or None if it's not hashed.

Going off topic, I was expecting either

1. pass in hash and plaintext, sign either hashes it for me or does non-hashed signing and returns the hash
2. pass in a enum Unhashed(&[u8]), Hashed(Hash, &[u8]) (or maybe something more granular with each hash type and a fixed size byte array ref) which would tie those parameters together

[tarcieri]

The documentation has changed considerably since this was originally filed. It now contains comprehensive examples for all of the core features of this crate.

If there are still gaps, please file more specific issues.