From e2cf891c338d04cf61bc704a0133b9a5ebff007f Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sat, 14 Oct 2023 15:56:59 -0600
Subject: [PATCH] ssh-key: add `SshSig` signature verification example

Provides a complete example for how to use `PublicKey::verify`
---
 ssh-key/src/public.rs | 31 +++++++++++++++++++++++++++++++
 ssh-key/src/sshsig.rs |  7 +++++++
 2 files changed, 38 insertions(+)

diff --git a/ssh-key/src/public.rs b/ssh-key/src/public.rs
index 28b4ee3..e88a9b3 100644
--- a/ssh-key/src/public.rs
+++ b/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 user@example.com";
+    ///
+    /// // 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<()> {
diff --git a/ssh-key/src/sshsig.rs b/ssh-key/src/sshsig.rs
index 85658fe..f460a75 100644
--- a/ssh-key/src/sshsig.rs
+++ b/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 {