bssl-tls: add TlsConnection::get_peer_certificates

TlsConnection exposes peer certificate type and raw public key getters,
but lacks a way to inspect the peer's X.509 certificate chain after a
handshake. Post-handshake certificate inspection is needed by mTLS
servers and clients (such as tonic gRPC services) to extract peer
identities for per-RPC authorization and custom SAN or issuer checks.
Thus, add TlsConnection::get_peer_certificates wrapping
SSL_get0_peer_certificates.

Change-Id: I902a5a147330600beaec87b569bdf5e64225cae9
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/106089
Commit-Queue: Xiangfei Ding <xfding@google.com>
Reviewed-by: Xiangfei Ding <xfding@google.com>
diff --git a/rust/bssl-tls/src/connection/credentials.rs b/rust/bssl-tls/src/connection/credentials.rs
index c254fd8..7abf111 100644
--- a/rust/bssl-tls/src/connection/credentials.rs
+++ b/rust/bssl-tls/src/connection/credentials.rs
@@ -42,6 +42,7 @@
     check_lib_error,
     config::ConfigurationError,
     credentials::{
+        CertificateChainIterator,
         CertificateType,
         CertificateVerificationMode,
         DistinguishedName,
@@ -557,6 +558,28 @@
         }
         get_peer_raw_public_key(self.ptr())
     }
+
+    /// Get the peer's certificate chain, starting with the leaf certificate.
+    ///
+    /// Returns an empty iterator if the handshake has not completed or if the peer did not
+    /// present an X.509 certificate chain. The chain may also appear empty if the server
+    /// opts into dropping peer certificate chains.
+    pub fn get_peer_certificates(&self) -> CertificateChainIterator<'_> {
+        let cert_chain = if self.is_in_handshake() {
+            null()
+        } else {
+            unsafe {
+                // Safety: `self.ptr()` is a valid `SSL` handle and `cert_chain` borrows from
+                // `self`.
+                bssl_sys::SSL_get0_peer_certificates(self.ptr())
+            }
+        };
+        unsafe {
+            // Safety: `cert_chain` is either null or a valid `STACK_OF(CRYPTO_BUFFER)` borrowed
+            // from `self`.
+            CertificateChainIterator::new(cert_chain)
+        }
+    }
 }
 
 /// # Certificate authorities - Client
diff --git a/rust/bssl-tls/src/tests/credentials.rs b/rust/bssl-tls/src/tests/credentials.rs
index 47e407a..a4b63e3 100644
--- a/rust/bssl-tls/src/tests/credentials.rs
+++ b/rust/bssl-tls/src/tests/credentials.rs
@@ -202,3 +202,33 @@
 
     Ok(())
 }
+
+#[test]
+fn test_get_peer_certificates() -> Result<(), crate::errors::Error> {
+    let (mut server_conn, mut client_conn) = super::dumb_server_client()?;
+
+    assert_eq!(client_conn.get_peer_certificates().len(), 0);
+    assert_eq!(server_conn.get_peer_certificates().len(), 0);
+
+    let (client_socket, server_socket, mut executor) = super::create_mock_pipe();
+    client_conn.set_io(client_socket)?;
+    server_conn.set_io(server_socket)?;
+
+    executor.run(async {
+        futures::future::join(
+            super::drive_handshake(&mut client_conn),
+            super::drive_handshake(&mut server_conn),
+        )
+        .await;
+    });
+
+    assert_eq!(server_conn.get_peer_certificates().len(), 0);
+    let mut peer_certs = client_conn.get_peer_certificates();
+    assert_eq!(peer_certs.len(), 2);
+    assert_eq!(
+        peer_certs.next().expect("chain has 2 certs").as_der_bytes(),
+        super::RSA_SERVER_CERT_DER
+    );
+
+    Ok(())
+}