ssh-key: add SshSig signature verification example (#166)

Provides a complete example for how to use `PublicKey::verify`

ssh-key/src/public.rs

@@ -170,6 +170,37 @@ impl PublicKey {
     ///
     /// See [PROTOCOL.sshsig] for more information.
     ///
+    /// # Usage
+    ///
+    #[cfg_attr(feature = "ed25519", doc = "```")]
+    #[cfg_attr(not(feature = "ed25519"), doc = "```ignore")]
+    /// # fn main() -> Result<(), ssh_key::Error> {
+    /// use ssh_key::{PublicKey, SshSig};
+    ///
+    /// // Message to be verified.
+    /// let message = b"testing";
+    ///
+    /// // Example domain/namespace used for the message.
+    /// let namespace = "example";
+    ///
+    /// // Public key which computed the signature.
+    /// let public_key_str = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILM+rvN+ot98qgEN796jTiQfZfG1KaT0PtFDJ/XFSqti [email protected]";
+    ///
+    /// // Example signature to be verified.
+    /// let signature_str = "-----BEGIN SSH SIGNATURE-----
+    /// U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgsz6u836i33yqAQ3v3qNOJB9l8b
+    /// UppPQ+0UMn9cVKq2IAAAAHZXhhbXBsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQy
+    /// NTUxOQAAAEBPEav+tMGNnox4MuzM7rlHyVBajCn8B0kAyiOWwPKprNsG3i6X+voz/WCSik
+    /// /FowYwqhgCABUJSvRX3AERVBUP
+    /// -----END SSH SIGNATURE-----";
+    ///
+    /// let public_key = public_key_str.parse::<PublicKey>()?;
+    /// let signature = signature_str.parse::<SshSig>()?;
+    /// public_key.verify(namespace, message, &signature)?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
     /// [PROTOCOL.sshsig]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.sshsig?annotate=HEAD
     #[cfg(feature = "alloc")]
     pub fn verify(&self, namespace: &str, msg: &[u8], signature: &SshSig) -> Result<()> {

ssh-key/src/sshsig.rs

@@ -9,6 +9,9 @@ use encoding::{
 };
 use signature::Verifier;
 
+#[cfg(doc)]
+use crate::PublicKey;
+
 type Version = u32;
 
 /// `sshsig` provides a general-purpose signature format based on SSH keys and
@@ -23,6 +26,10 @@ type Version = u32;
 ///
 /// See [PROTOCOL.sshsig] for more information.
 ///
+/// # Usage
+///
+/// See [`SshSig::sign`] and [`PublicKey::verify`] for usage information.
+///
 /// [PROTOCOL.sshsig]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.sshsig?annotate=HEAD
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SshSig {