Add doctest examples for key parsing

src/key.rs

@@ -199,6 +199,30 @@ impl RSAPublicKey {
     /// following a `-----BEGIN RSA PUBLIC KEY-----` header.
     ///
     /// <https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem>
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use rsa::RSAPublicKey;
+    /// 
+    /// # // openssl rsa -pubin -in tiny_key.pub.pem -RSAPublicKey_out
+    /// let file_content = r#"
+    /// -----BEGIN RSA PUBLIC KEY-----
+    /// MEgCQQCuWe45NapeQ6rkb5T5hYMgQwr3T0NE9rItqDwFJjcNmf6m9kq/wRAaFqWo
+    /// BX/BpdSuD0YqSUrnQ5ejf1XW9gmJAgMBAAE=
+    /// -----END RSA PUBLIC KEY-----
+    /// "#;
+    /// 
+    /// let der_encoded = file_content
+    ///     .lines()
+    ///     .filter(|line| !line.starts_with("-"))
+    ///     .fold(String::new(), |mut data, line| {
+    ///         data.push_str(&line);
+    ///         data
+    ///     });
+    /// let der_bytes = base64::decode(&der_encoded).expect("failed to decode base64 content");
+    /// let public_key = RSAPublicKey::from_pkcs1(&der_bytes).expect("failed to parse key");
+    /// ```
     pub fn from_pkcs1(der: &[u8]) -> Result<RSAPublicKey> {
         crate::parse::parse_public_key_pkcs1(der)
     }
@@ -209,6 +233,30 @@ impl RSAPublicKey {
     /// following a `-----BEGIN PUBLIC KEY-----` header.
     ///
     /// <https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem>
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use rsa::RSAPublicKey;
+    /// 
+    /// # // openssl rsa -in tiny_key.pem -outform PEM -pubout -out tiny_key.pub.pem
+    /// let file_content = r#"
+    /// -----BEGIN PUBLIC KEY-----
+    /// MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAK5Z7jk1ql5DquRvlPmFgyBDCvdPQ0T2
+    /// si2oPAUmNw2Z/qb2Sr/BEBoWpagFf8Gl1K4PRipJSudDl6N/Vdb2CYkCAwEAAQ==
+    /// -----END PUBLIC KEY-----
+    /// "#;
+    /// 
+    /// let der_encoded = file_content
+    ///     .lines()
+    ///     .filter(|line| !line.starts_with("-"))
+    ///     .fold(String::new(), |mut data, line| {
+    ///         data.push_str(&line);
+    ///         data
+    ///     });
+    /// let der_bytes = base64::decode(&der_encoded).expect("failed to decode base64 content");
+    /// let public_key = RSAPublicKey::from_pkcs8(&der_bytes).expect("failed to parse key");
+    /// ```
     pub fn from_pkcs8(der: &[u8]) -> Result<RSAPublicKey> {
         crate::parse::parse_public_key_pkcs8(der)
     }
@@ -327,6 +375,35 @@ impl RSAPrivateKey {
     /// following a `-----BEGIN RSA PRIVATE KEY-----` header.
     ///
     /// <https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem>
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use rsa::RSAPrivateKey;
+    /// 
+    /// # // openssl genrsa -out tiny_key.pem 512
+    /// let file_content = r#"
+    /// -----BEGIN RSA PRIVATE KEY-----
+    /// MIIBOwIBAAJBAK5Z7jk1ql5DquRvlPmFgyBDCvdPQ0T2si2oPAUmNw2Z/qb2Sr/B
+    /// EBoWpagFf8Gl1K4PRipJSudDl6N/Vdb2CYkCAwEAAQJBAI3vWCfqsE8c9zoQPE8F
+    /// icHx0jOSq0ixLExO8M2gVqESq3SJpWbEbvPPbRb1sIqZHe5wV3Xmj09zvUzfdeB7
+    /// C6ECIQDjoB/kp7QlRiNhgudhQPct8XUf6Cgp7hBxL2K9Q9UzawIhAMQVvtH1TUOd
+    /// aSWiqrFx7w+54o58fIpkecI5Kl0TaWfbAiBrnye1Kn2IKhNMZWIUn2y+8izYeyGS
+    /// QZbQjQD4T3wcJQIgKGgWv2teNZ29ai0AIbrJuaLjhdsvStFzqctf6Hg0k1sCIQCj
+    /// JdwDGF7Kanex70KAacmOlw3vfx6XWT+2PH6Qh8tLug==
+    /// -----END RSA PRIVATE KEY-----
+    /// "#;
+    /// 
+    /// let der_encoded = file_content
+    ///     .lines()
+    ///     .filter(|line| !line.starts_with("-"))
+    ///     .fold(String::new(), |mut data, line| {
+    ///         data.push_str(&line);
+    ///         data
+    ///     });
+    /// let der_bytes = base64::decode(&der_encoded).expect("failed to decode base64 content");
+    /// let private_key = RSAPrivateKey::from_pkcs1(&der_bytes).expect("failed to parse key");
+    /// ```
     pub fn from_pkcs1(der: &[u8]) -> Result<RSAPrivateKey> {
         crate::parse::parse_private_key_pkcs1(der)
     }
@@ -337,6 +414,36 @@ impl RSAPrivateKey {
     /// following a `-----BEGIN PRIVATE KEY-----` header.
     ///
     /// <https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem>
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use rsa::RSAPrivateKey;
+    /// 
+    /// # // openssl pkcs8 -topk8 -inform PEM -outform PEM -in tiny_key.pem -out tiny_key.pkcs8.pem -nocrypt
+    /// let file_content = r#"
+    /// -----BEGIN PRIVATE KEY-----
+    /// MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEArlnuOTWqXkOq5G+U
+    /// +YWDIEMK909DRPayLag8BSY3DZn+pvZKv8EQGhalqAV/waXUrg9GKklK50OXo39V
+    /// 1vYJiQIDAQABAkEAje9YJ+qwTxz3OhA8TwWJwfHSM5KrSLEsTE7wzaBWoRKrdIml
+    /// ZsRu889tFvWwipkd7nBXdeaPT3O9TN914HsLoQIhAOOgH+SntCVGI2GC52FA9y3x
+    /// dR/oKCnuEHEvYr1D1TNrAiEAxBW+0fVNQ51pJaKqsXHvD7nijnx8imR5wjkqXRNp
+    /// Z9sCIGufJ7UqfYgqE0xlYhSfbL7yLNh7IZJBltCNAPhPfBwlAiAoaBa/a141nb1q
+    /// LQAhusm5ouOF2y9K0XOpy1/oeDSTWwIhAKMl3AMYXspqd7HvQoBpyY6XDe9/HpdZ
+    /// P7Y8fpCHy0u6
+    /// -----END PRIVATE KEY-----
+    /// "#;
+    /// 
+    /// let der_encoded = file_content
+    ///     .lines()
+    ///     .filter(|line| !line.starts_with("-"))
+    ///     .fold(String::new(), |mut data, line| {
+    ///         data.push_str(&line);
+    ///         data
+    ///     });
+    /// let der_bytes = base64::decode(&der_encoded).expect("failed to decode base64 content");
+    /// let private_key = RSAPrivateKey::from_pkcs8(&der_bytes).expect("failed to parse key");
+    /// ```
     pub fn from_pkcs8(der: &[u8]) -> Result<RSAPrivateKey> {
         crate::parse::parse_private_key_pkcs8(der)
     }

src/parse.rs

@@ -23,6 +23,29 @@ impl TryFrom<pem::Pem> for RSAPrivateKey {
     /// Expects one of the following `pem` headers:
     /// - `-----BEGIN PRIVATE KEY-----`
     /// - `-----BEGIN RSA PRIVATE KEY-----`
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use std::convert::TryFrom;
+    /// use rsa::RSAPrivateKey;
+    /// 
+    /// # // openssl genrsa -out tiny_key.pem 512
+    /// let file_content = r#"
+    /// -----BEGIN RSA PRIVATE KEY-----
+    /// MIIBOwIBAAJBAK5Z7jk1ql5DquRvlPmFgyBDCvdPQ0T2si2oPAUmNw2Z/qb2Sr/B
+    /// EBoWpagFf8Gl1K4PRipJSudDl6N/Vdb2CYkCAwEAAQJBAI3vWCfqsE8c9zoQPE8F
+    /// icHx0jOSq0ixLExO8M2gVqESq3SJpWbEbvPPbRb1sIqZHe5wV3Xmj09zvUzfdeB7
+    /// C6ECIQDjoB/kp7QlRiNhgudhQPct8XUf6Cgp7hBxL2K9Q9UzawIhAMQVvtH1TUOd
+    /// aSWiqrFx7w+54o58fIpkecI5Kl0TaWfbAiBrnye1Kn2IKhNMZWIUn2y+8izYeyGS
+    /// QZbQjQD4T3wcJQIgKGgWv2teNZ29ai0AIbrJuaLjhdsvStFzqctf6Hg0k1sCIQCj
+    /// JdwDGF7Kanex70KAacmOlw3vfx6XWT+2PH6Qh8tLug==
+    /// -----END RSA PRIVATE KEY-----
+    /// "#;
+    /// 
+    /// let pem = rsa::pem::parse(file_content).expect("failed to parse pem file");
+    /// let private_key = RSAPrivateKey::try_from(pem).expect("failed to parse key");
+    /// ```
     fn try_from(pem: pem::Pem) -> Result<RSAPrivateKey> {
         match &*pem.tag {
             "RSA PRIVATE KEY" => parse_private_key_pkcs1(&pem.contents),
@@ -43,6 +66,24 @@ impl TryFrom<pem::Pem> for RSAPublicKey {
     /// Expects one of the following `pem` headers:
     /// - `-----BEGIN PUBLIC KEY-----`
     /// - `-----BEGIN RSA PUBLIC KEY-----`
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use std::convert::TryFrom;
+    /// use rsa::RSAPublicKey;
+    /// 
+    /// # // openssl rsa -in tiny_key.pem -outform PEM -pubout -out tiny_key.pub.pem
+    /// let file_content = r#"
+    /// -----BEGIN PUBLIC KEY-----
+    /// MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAK5Z7jk1ql5DquRvlPmFgyBDCvdPQ0T2
+    /// si2oPAUmNw2Z/qb2Sr/BEBoWpagFf8Gl1K4PRipJSudDl6N/Vdb2CYkCAwEAAQ==
+    /// -----END PUBLIC KEY-----
+    /// "#;
+    /// 
+    /// let pem = rsa::pem::parse(file_content).expect("failed to parse pem file");
+    /// let public_key = RSAPublicKey::try_from(pem).expect("failed to parse key");
+    /// ```
     fn try_from(pem: pem::Pem) -> Result<RSAPublicKey> {
         match &*pem.tag {
             "RSA PUBLIC KEY" => parse_public_key_pkcs1(&pem.contents),