`pkcs1`: Document that it only accepts RFC 7468 textual encodings

[str4d]

The trait method for deserializing PKCS#1-encoded RSA private keys is documented as accepting PEM:

formats/pkcs1/src/traits.rs

Lines 29 to 39 in 2898d39

	/// Deserialize PKCS#1-encoded private key from PEM.
	///
	/// Keys in this format begin with the following:
	///
	/// ```text
	/// -----BEGIN RSA PRIVATE KEY-----
	/// ```
	#[cfg(feature = "pem")]
	#[cfg_attr(docsrs, doc(cfg(feature = "pem")))]
	fn from_pkcs1_pem(s: &str) -> Result<Self> {
	RsaPrivateKeyDocument::from_pkcs1_pem(s)

However, via the call graph we can see it actually uses the pem-rfc7468 crate, which parses textual encodings that are a strict subset of PEM:

formats/pkcs1/src/document/private_key.rs

Lines 56 to 57 in 2898d39

	fn from_pkcs1_pem(s: &str) -> Result<Self> {
	let (label, der_bytes) = pem::decode_vec(s.as_bytes())?;

formats/pkcs1/src/lib.rs

Line 70 in 2898d39

use pem_rfc7468 as pem;

In particular, this makes the trait impl incompatible with legacy passphrase-encrypted OpenSSH keys:

   Unlike legacy PEM encoding [RFC1421], OpenPGP ASCII armor, and the
   OpenSSH key file format, textual encoding does *not* define or permit
   headers to be encoded alongside the data.  Empty space can appear
   between the pre-encapsulation boundary and the base64, but generators
   SHOULD NOT emit such any such spacing.  (The provision for this empty
   area is a throwback to PEM, which defined an "encapsulated header
   portion".)

The documentation for FromRsaPrivateKey::from_pkcs1_pem should be updated to clarify that it only accepts RFC 7468 textual encodings, not arbitrary PEM.

[str4d]

Note that I am not advocating for supporting these legacy OpenSSH keys in the rsa crate. In the age crate I parse enough of the PEM format to detect the encryption headers, and then reject the keys as unsupported, since there is an easy migration pathway that I can inform users of. It would be nice if I could just call rsa::RsaPrivateKey::from_pkcs1_pem and detect this specific case via an error, but I'm also happy just handling this myself.

[tarcieri]

It would be nice if I could just call rsa::RsaPrivateKey::from_pkcs1_pem and detect this specific case via an error, but I'm also happy just handling this myself.

It should be returning the special pem_rfc7468::Error::HeaderDisallowed variant when headers are present, which was added to detect this very case.

[str4d]

Ah, nice! That error case isn't quite sufficient on its own, as I need to check that the header present is in fact the encrypted PEM header, but that could be done with a wrapper (as if that error is returned, we know there is at least enough data to see the header).

[dwhjames]

@str4d, FYI, I added (#13) Error::HeaderDisallowed with exactly that use case in mind. Sorry, only just catching up on the comments over in str4d/rage#261 (comment)