bssl-x509: documentation improvements.

Change-Id: Ib58314641b211c3d6e9ba3a565be61f44601617a
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/90768
Reviewed-by: Xiangfei Ding <xfding@google.com>
Auto-Submit: Adam Langley <agl@google.com>
Commit-Queue: Xiangfei Ding <xfding@google.com>

rust/bssl-x509/src/certificates.rs

diff --git a/rust/bssl-x509/src/certificates.rs b/rust/bssl-x509/src/certificates.rs
index 43d91ef..8432d30 100644
--- a/rust/bssl-x509/src/certificates.rs
+++ b/rust/bssl-x509/src/certificates.rs
@@ -26,13 +26,23 @@
 //! # use bssl_x509::certificates::X509Certificate;
 //! # let concatenated_pem_bytes = include_bytes!("tests/consolidated.pem");
 //! # let pem = include_bytes!("tests/BoringSSLServerTest-RSA.crt");
-//! let certs: Vec<X509Certificate> = X509Certificate::parse_all_from_pem(concatenated_pem_bytes).unwrap();
+//! let certs: Vec<X509Certificate> =
+//!     X509Certificate::parse_all_from_pem(concatenated_pem_bytes).unwrap();
+//! assert_eq!(certs.len(), 6);
 //!
 //! let cert = X509Certificate::parse_one_from_pem(pem).unwrap();
+//!
+//! assert_eq!(cert.get_not_before().unwrap(), 1769078409);
+//! assert_eq!(cert.get_not_after().unwrap(), 64884278409);
+//! assert_eq!(cert.get_serial_number().unwrap().as_twos_complement_bytes().unwrap(),
+//!            [80, 45, 50, 81, 123, 185, 81, 240,
+//!             223, 110, 78, 195, 5, 31, 44, 75,
+//!             175, 205, 82, 115]);
+//!
 //! let der: Vec<u8> = cert.to_der().unwrap();
 //! ```
 //!
-//! # Inspect a certificate
+//! # Inspecting a certificate
 //!
 //! One can check if a certificate has a public key that matches a [`PrivateKey`].
 //! ```rust
@@ -255,7 +265,11 @@
         self.0.as_ptr()
     }
 
-    /// Get a twos-complement big-endian representation of the serial number.
+    /// Get a two's-complement, big-endian representation of the serial number.
+    ///
+    /// This is a big-endian integer. If the most-significant bit is set then
+    /// it is negative. Positive values that would otherwise have the
+    /// most-significant bit set are left padded with a zero byte to avoid this.
     pub fn as_twos_complement_bytes(&self) -> Option<&[u8]> {
         let serial = self.ptr();
         let len = unsafe {

rust/bssl-x509/src/keys.rs

diff --git a/rust/bssl-x509/src/keys.rs b/rust/bssl-x509/src/keys.rs
index d3244b9..9ea8bda 100644
--- a/rust/bssl-x509/src/keys.rs
+++ b/rust/bssl-x509/src/keys.rs
@@ -23,8 +23,8 @@
 //! # let pem = include_bytes!("tests/BoringSSLTestCA.key");
 //! # let crt = include_bytes!("tests/BoringSSLTestCA.crt");
 //! # let crt = X509Certificate::parse_one_from_pem(crt).unwrap();
-//!
-//! let key = PrivateKey::from_pem(pem, || b"BoringSSL is awesome!").unwrap();
+//! let key = PrivateKey::from_pem(
+//!     pem, /*password_callback=*/ || b"BoringSSL is awesome!").unwrap();
 //! assert!(crt.matches_private_key(&key));
 //! ```
 

rust/bssl-x509/src/lib.rs

diff --git a/rust/bssl-x509/src/lib.rs b/rust/bssl-x509/src/lib.rs
index dd7b4bc..e721ac2 100644
--- a/rust/bssl-x509/src/lib.rs
+++ b/rust/bssl-x509/src/lib.rs
@@ -25,9 +25,19 @@
 #![allow(private_bounds)]
 #![cfg_attr(not(any(feature = "std", test)), no_std)]
 
-//! BoringSSL PKI and X.509 bindings
+//! BoringSSL crypto/x509 bindings.
 //!
 //! *WARNING* this crate is still work in progress and unstable.
+//!
+//! BoringSSL contains crypto/x509, an X.509 library inherited and cleaned up
+//! from OpenSSL. This crate contains bindings for it. While documentation
+//! is provided here, you may also need to see [the
+//! documentation](https://boringssl.googlesource.com/boringssl/+/refs/heads/main/include/openssl/x509.h)
+//! for the underlying C API.
+//!
+//! (BoringSSL also contains libpki, a much more modern and correct X.509
+//! validation library which is used in Chromium. But crypto/x509 is still used
+//! in many contexts and there can be valid reasons to want to use it.)
 
 extern crate alloc;
 extern crate core;

rust/bssl-x509/src/verify.rs

diff --git a/rust/bssl-x509/src/verify.rs b/rust/bssl-x509/src/verify.rs
index cfc8902..b4fd436 100644
--- a/rust/bssl-x509/src/verify.rs
+++ b/rust/bssl-x509/src/verify.rs
@@ -12,24 +12,29 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! X.509 certificate verification process.
+//! X.509 certificate verification.
 //!
 //! To verify certificates, one may use [`X509Verifier`] which requires a fully constructed
-//! [`X509Store`] certificate store, [`X509CertificateList`] a list of untrusted intermediate
-//! certificates and [`X509Certificate`] the final end-entity certificate.
+//! [`X509Store`] certificate store, an [`X509CertificateList`] of untrusted intermediate
+//! certificates, and the final end-entity certificate as an [`X509Certificate`].
 //!
 //! ```rust
 //! # use bssl_x509::certificates::X509Certificate;
 //! # use bssl_x509::store::{X509Store, X509StoreBuilder};
 //! # use bssl_x509::verify::X509CertificateList;
 //! # use bssl_x509::verify::X509Verifier;
-//! # let ca = X509Certificate::parse_one_from_pem(include_bytes!("tests/BoringSSLTestCA.crt")).unwrap();
-//! # let cert = X509Certificate::parse_one_from_pem(include_bytes!("tests/BoringSSLServerTest-RSA.crt")).unwrap();
-//! # let chain = X509CertificateList::new();
-//! # let mut store = X509StoreBuilder::new();
-//! # store.add_cert(ca).unwrap();
-//! # let store = store.build();
-//! let mut verifier = X509Verifier::new(&cert, &chain, &store).unwrap();
+//! let ca = X509Certificate::parse_one_from_pem(
+//!     include_bytes!("tests/BoringSSLTestCA.crt")).unwrap();
+//! let mut store = X509StoreBuilder::new();
+//! store.add_cert(ca).unwrap();
+//! let store = store.build();
+//!
+//! let untrusted_intermediates = X509CertificateList::new();
+//!
+//! let leaf = X509Certificate::parse_one_from_pem(
+//!     include_bytes!("tests/BoringSSLServerTest-RSA.crt")).unwrap();
+//!
+//! let mut verifier = X509Verifier::new(&leaf, &untrusted_intermediates, &store).unwrap();
 //! assert!(verifier.verify().is_ok());
 //! ```