feat(auth): add certificate-based authentication via SSH agent

Add support for authenticating with SSH certificates held by an SSH agent,
complementing the existing key-based authentication flow.

- Add FutureCertificate method variant for certificate auth
- Add AgentIdentity enum to represent both keys and certificates
- Implement sign_request_cert for certificate-based signing
- Add authenticate_certificate_with for FutureCertificate auth flow
- Add hash_alg support for RSA certificate signing
- Comprehensive test coverage for new functionality

Closes #438

Author: wi-adam

russh/src/auth.rs

@@ -163,6 +163,22 @@ pub trait Signer: Sized {
         hash_alg: Option<HashAlg>,
         to_sign: CryptoVec,
     ) -> impl Future<Output = Result<CryptoVec, Self::Error>> + Send;
+
+    /// Sign authentication data using a certificate identity.
+    ///
+    /// The default implementation returns an error, indicating certificate
+    /// signing is not supported. Implementations that support certificate
+    /// signing (e.g., SSH agent clients) should override this method.
+    ///
+    /// For RSA certificates, you can specify the hash algorithm to use.
+    fn auth_certificate_sign(
+        &mut self,
+        _cert: &Certificate,
+        _hash_alg: Option<HashAlg>,
+        _to_sign: CryptoVec,
+    ) -> impl Future<Output = Result<CryptoVec, Self::Error>> + Send {
+        async { Err((crate::SendError {}).into()) }
+    }
 }
 
 #[derive(Debug, Error)]
@@ -192,6 +208,20 @@ impl<R: AsyncRead + AsyncWrite + Unpin + Send + 'static> Signer
                 .map_err(Into::into)
         }
     }
+
+    #[allow(clippy::manual_async_fn)]
+    fn auth_certificate_sign(
+        &mut self,
+        cert: &Certificate,
+        hash_alg: Option<HashAlg>,
+        to_sign: CryptoVec,
+    ) -> impl Future<Output = Result<CryptoVec, Self::Error>> {
+        async move {
+            self.sign_request_cert(cert, hash_alg, to_sign)
+                .await
+                .map_err(Into::into)
+        }
+    }
 }
 
 #[derive(Debug)]
@@ -212,6 +242,12 @@ pub enum Method {
         key: ssh_key::PublicKey,
         hash_alg: Option<HashAlg>,
     },
+    /// Certificate-based authentication using an external signer (e.g., SSH agent).
+    /// The certificate is sent to the server, but signing is delegated to the signer.
+    FutureCertificate {
+        cert: Certificate,
+        hash_alg: Option<HashAlg>,
+    },
     KeyboardInteractive {
         submethods: String,
     },

russh/src/client/encrypted.rs

@@ -252,6 +252,38 @@ impl Session {
                                         })
                                     }
                                 }
+                                Some(auth::Method::FutureCertificate { cert, hash_alg }) => {
+                                    debug!("certificate");
+                                    self.common.buffer.clear();
+                                    let i = enc.client_make_to_sign(
+                                        &self.common.auth_user,
+                                        &PublicKeyOrCertificate::Certificate(cert.clone()),
+                                        &mut self.common.buffer,
+                                    )?;
+                                    let len = self.common.buffer.len();
+                                    let buf = std::mem::replace(
+                                        &mut self.common.buffer,
+                                        CryptoVec::new(),
+                                    );
+
+                                    self.sender
+                                        .send(Reply::SignRequestCert { cert, hash_alg, data: buf })
+                                        .map_err(|_| crate::Error::SendError)?;
+                                    self.common.buffer = loop {
+                                        match self.receiver.recv().await {
+                                            Some(Msg::Signed { data }) => break data,
+                                            None => return Err(crate::Error::RecvError.into()),
+                                            _ => {}
+                                        }
+                                    };
+                                    if self.common.buffer.len() != len {
+                                        // The buffer was modified.
+                                        push_packet!(enc.write, {
+                                            #[allow(clippy::indexing_slicing)] // length checked
+                                            enc.write.extend(&self.common.buffer[i..]);
+                                        })
+                                    }
+                                }
                                 _ => {}
                             }
                         }
@@ -940,6 +972,18 @@ impl Encrypted {
                     key.to_bytes()?.as_slice().encode(&mut self.write)?;
                     true
                 }
+                auth::Method::FutureCertificate { ref cert, .. } => {
+                    user.as_bytes().encode(&mut self.write)?;
+                    "ssh-connection".encode(&mut self.write)?;
+                    "publickey".encode(&mut self.write)?;
+                    self.write.push(0); // This is a probe
+
+                    cert.algorithm()
+                        .to_certificate_type()
+                        .encode(&mut self.write)?;
+                    cert.to_bytes()?.as_slice().encode(&mut self.write)?;
+                    true
+                }
                 auth::Method::KeyboardInteractive { ref submethods } => {
                     debug!("Keyboard interactive");
                     user.as_bytes().encode(&mut self.write)?;

russh/src/client/mod.rs

@@ -119,6 +119,11 @@ enum Reply {
         key: ssh_key::PublicKey,
         data: CryptoVec,
     },
+    SignRequestCert {
+        cert: Certificate,
+        hash_alg: Option<HashAlg>,
+        data: CryptoVec,
+    },
     AuthInfoRequest {
         name: String,
         instructions: String,
@@ -500,6 +505,64 @@ impl<H: Handler> Handle<H> {
         }
     }
 
+    /// Authenticate using a certificate with a custom signer that implements the
+    /// [`Signer`][auth::Signer] trait. This is for certificate-based authentication
+    /// where the signing is delegated to an external signer (e.g., SSH agent).
+    ///
+    /// For RSA certificates, you can specify the hash algorithm to use.
+    pub async fn authenticate_certificate_with<U: Into<String>, S: auth::Signer>(
+        &mut self,
+        user: U,
+        cert: Certificate,
+        hash_alg: Option<HashAlg>,
+        signer: &mut S,
+    ) -> Result<AuthResult, S::Error> {
+        let user = user.into();
+        if self
+            .sender
+            .send(Msg::Authenticate {
+                user,
+                method: auth::Method::FutureCertificate { cert, hash_alg },
+            })
+            .await
+            .is_err()
+        {
+            return Err((crate::SendError {}).into());
+        }
+        loop {
+            let reply = self.receiver.recv().await;
+            match reply {
+                Some(Reply::AuthSuccess) => return Ok(AuthResult::Success),
+                Some(Reply::AuthFailure {
+                    proceed_with_methods: remaining_methods,
+                    partial_success,
+                }) => {
+                    return Ok(AuthResult::Failure {
+                        remaining_methods,
+                        partial_success,
+                    });
+                }
+                Some(Reply::SignRequestCert { cert, hash_alg, data }) => {
+                    let data = signer.auth_certificate_sign(&cert, hash_alg, data).await;
+                    let data = match data {
+                        Ok(data) => data,
+                        Err(e) => return Err(e),
+                    };
+                    if self.sender.send(Msg::Signed { data }).await.is_err() {
+                        return Err((crate::SendError {}).into());
+                    }
+                }
+                None => {
+                    return Ok(AuthResult::Failure {
+                        remaining_methods: MethodSet::empty(),
+                        partial_success: false,
+                    });
+                }
+                _ => {}
+            }
+        }
+    }
+
     /// Wait for confirmation that a channel is open
     async fn wait_channel_confirmation(
         &self,

russh/src/keys/agent/client.rs

@@ -4,11 +4,11 @@ use byteorder::{BigEndian, ByteOrder};
 use bytes::Bytes;
 use log::{debug, error};
 use ssh_encoding::{Decode, Encode, Reader};
-use ssh_key::{Algorithm, HashAlg, PrivateKey, PublicKey, Signature};
+use ssh_key::{Algorithm, Certificate, HashAlg, PrivateKey, PublicKey, Signature};
 use tokio;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
-use super::{msg, Constraint};
+use super::{msg, AgentIdentity, Constraint};
 use crate::helpers::EncodedExt;
 use crate::keys::{key, Error};
 use crate::CryptoVec;
@@ -254,8 +254,12 @@ impl<S: AgentStream + Unpin> AgentClient<S> {
         Ok(())
     }
 
-    /// Ask the agent for a list of the currently registered secret
-    /// keys.
+    /// Ask the agent for a list of the currently registered public keys.
+    ///
+    /// Note: Certificates held by the agent will be returned as their underlying public
+    /// key only, without the certificate data. Use
+    /// [`request_identities_full`](Self::request_identities_full) to retrieve full
+    /// certificate information.
     pub async fn request_identities(&mut self) -> Result<Vec<PublicKey>, Error> {
         self.buf.clear();
         self.buf.resize(4);
@@ -282,6 +286,70 @@ impl<S: AgentStream + Unpin> AgentClient<S> {
         Ok(keys)
     }
 
+    /// Ask the agent for a list of identities, including certificates.
+    ///
+    /// Unlike [`request_identities`](Self::request_identities) which only returns public keys,
+    /// this method correctly parses OpenSSH certificates held by the agent.
+    pub async fn request_identities_full(&mut self) -> Result<Vec<AgentIdentity>, Error> {
+        self.buf.clear();
+        self.buf.resize(4);
+        msg::REQUEST_IDENTITIES.encode(&mut self.buf)?;
+        let len = self.buf.len() - 4;
+        BigEndian::write_u32(&mut self.buf[..], len as u32);
+
+        self.read_response().await?;
+        debug!("identities: {:?}", &self.buf[..]);
+        let mut identities = Vec::new();
+
+        #[allow(clippy::indexing_slicing)] // static length
+        if let Some((&msg::IDENTITIES_ANSWER, mut r)) = self.buf.split_first() {
+            let n = u32::decode(&mut r)?;
+            for _ in 0..n {
+                let key_blob = Bytes::decode(&mut r)?;
+                let comment = String::decode(&mut r)?;
+
+                // Check if blob starts with a certificate algorithm by reading the algorithm string.
+                // Certificate algorithms end with "-cert-v01@openssh.com".
+                // This avoids parsing the blob twice for regular keys.
+                let identity = if Self::is_certificate_blob(&key_blob) {
+                    match Certificate::decode(&mut key_blob.as_ref()) {
+                        Ok(cert) => AgentIdentity::Certificate { cert, comment },
+                        Err(_) => {
+                            // Fallback to public key if certificate parsing fails
+                            let key = key::parse_public_key(&key_blob)?;
+                            AgentIdentity::PublicKey { key, comment }
+                        }
+                    }
+                } else {
+                    let key = key::parse_public_key(&key_blob)?;
+                    AgentIdentity::PublicKey { key, comment }
+                };
+                identities.push(identity);
+            }
+        }
+
+        Ok(identities)
+    }
+
+    /// Check if a key blob appears to be a certificate by examining the algorithm prefix.
+    /// Certificate algorithms end with "-cert-v01@openssh.com".
+    fn is_certificate_blob(blob: &[u8]) -> bool {
+        // The blob starts with a length-prefixed string containing the algorithm name.
+        // Read the length (4 bytes, big-endian) and then the algorithm string.
+        let Some(len_bytes) = blob.get(..4) else {
+            return false;
+        };
+        let alg_len = BigEndian::read_u32(len_bytes) as usize;
+        let Some(alg_bytes) = blob.get(4..4 + alg_len) else {
+            return false;
+        };
+        if let Ok(alg_str) = str::from_utf8(alg_bytes) {
+            alg_str.ends_with("-cert-v01@openssh.com")
+        } else {
+            false
+        }
+    }
+
     /// Ask the agent to sign the supplied piece of data.
     pub async fn sign_request(
         &mut self,
@@ -307,6 +375,56 @@ impl<S: AgentStream + Unpin> AgentClient<S> {
         }
     }
 
+    /// Ask the agent to sign data using a certificate identity.
+    ///
+    /// This sends the certificate blob to the agent (not just the public key),
+    /// allowing the agent to match it to the correct private key.
+    ///
+    /// For RSA certificates, you can specify the hash algorithm to use.
+    pub async fn sign_request_cert(
+        &mut self,
+        cert: &Certificate,
+        hash_alg: Option<HashAlg>,
+        mut data: CryptoVec,
+    ) -> Result<CryptoVec, Error> {
+        debug!("sign_request_cert: {data:?}");
+
+        self.buf.clear();
+        self.buf.resize(4);
+        msg::SIGN_REQUEST.encode(&mut self.buf)?;
+        cert.to_bytes()?.encode(&mut self.buf)?;
+        data.as_ref().encode(&mut self.buf)?;
+
+        // Calculate hash flag for RSA certificates (same logic as prepare_sign_request)
+        let hash = match cert.algorithm() {
+            Algorithm::Rsa { .. } => match hash_alg {
+                Some(HashAlg::Sha256) => 2,
+                Some(HashAlg::Sha512) => 4,
+                _ => 0,
+            },
+            _ => 0,
+        };
+
+        hash.encode(&mut self.buf)?;
+
+        let len = self.buf.len() - 4;
+        BigEndian::write_u32(&mut self.buf[..], len as u32);
+
+        self.read_response().await?;
+
+        match self.buf.split_first() {
+            Some((&msg::SIGN_RESPONSE, mut r)) => {
+                self.write_signature(&mut r, hash, &mut data)?;
+                Ok(data)
+            }
+            Some((&msg::FAILURE, _)) => Err(Error::AgentFailure),
+            _ => {
+                debug!("self.buf = {:?}", &self.buf[..]);
+                Err(Error::AgentProtocolError)
+            }
+        }
+    }
+
     fn prepare_sign_request(
         &mut self,
         public: &ssh_key::PublicKey,