Add a tutorial on intro page

[AlscadIngenierie]

We could add how to use this crate :

dependency to add in cargo.toml file
how to import the package in our own crate ?
how to generate private and public keys ?
how to access them and convert them into std::string ?
how to encrypt with the public key ?
how to decrypt with the private key ?

[dignifiedquire]

yes, agreed this would be great to have.

…

On 31. Jan 2019, 11:09 +0100, crocwolf ***@***.***>, wrote: We could add how to use this crate : dependency to add in cargo.toml file how to import the package in our own crate ? how to generate private and public keys ? how to convert them into std::string ? how to encrypt with the public key ? how to decrypt with the private key ? — 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]

I added a basic example of encryption as a starting point to the readme

[builat]

Please could you expose example of from_components usage?

[dignifiedquire]

@builat is there a specific issue with that, you can see an example of it here: https://github.com/RustCrypto/RSA/blob/master/src/key.rs#L547

[builat]

@dignifiedquire Well no specific issue. But if you have to use RSA for the first time in your life you need to perform some kind of resaerch and do few more mental loops before you understand that you have to perform specific calculations for n,e,d and fi(n) and not just insert prime numbers.

Anyway awsome job! and thnx for what you done.

[newpavlov]

I think it will be much better to link some good external materials instead of trying to squeeze all good-to-know knowledge to the crate docs.

[dignifiedquire]

My ideal state is to have proper doc comments on the individual methods, which link to the core definitions on wikipedia + other reference material, in addition to have usage examples.

[builat]

@newpavlov totaly agree for example best material for me was : https://www.di-mgt.com.au/rsa_alg.html

[skaunov]

I wonder if this issue is still relevant, and what methods needs attention from this angle. Especially regarding PKCS1v15 encryption.

For example is it needed to describe why there two modules for padding, and one of them exposes only signatures structs?

[tarcieri]

The rustdoc now includes comprehensive usage examples including PKCS#1v15 encryption as well as the new signing APIs located in the pkcs1v15 and pss crates.

However, for some reason I've been asked a lot of questions about how to use the rsa crate lately, always referring people to the examples. I'm not sure if there's something better we can do to highlight them... perhaps linkify the algorithm directory that's now at the top of the rustdoc?

[tarcieri]

I also opened #226 with the suggestion of refactoring PaddingScheme into a trait, in which case the PKCS1v15Encrypt padding could be a struct that lives in e.g. rsa::pkcs1v15::EncryptionPadding.

[tarcieri]

Going to call this addressed by the current usage examples.

If there are specific things missing, please open new issues.