diff --git a/ssh-key/src/algorithm.rs b/ssh-key/src/algorithm.rs index ed56c706..6f8520c3 100644 --- a/ssh-key/src/algorithm.rs +++ b/ssh-key/src/algorithm.rs @@ -150,7 +150,7 @@ impl Algorithm { /// Decode algorithm from the given string identifier as used by the OpenSSH certificate format. /// /// OpenSSH certificate algorithms end in `*-cert-v01@openssh.com`. - /// See [PROTOCOL.certkeys] for more information. + /// See [draft-ietf-sshm-cert] for more information. /// /// # Supported algorithms /// - `ssh-rsa-cert-v01@openssh.com` @@ -164,7 +164,7 @@ impl Algorithm { /// /// Any other algorithms are mapped to the [`Algorithm::Other`] variant. /// - /// [PROTOCOL.certkeys]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD + /// [draft-ietf-sshm-cert]: https://www.ietf.org/archive/id/draft-ietf-sshm-cert-01.html /// /// # Errors /// Returns [`Error::AlgorithmUnknown`] in the event the algorithm is not known. @@ -224,9 +224,9 @@ impl Algorithm { /// format. /// /// OpenSSH certificate algorithms end in `*-cert-v01@openssh.com`. - /// See [PROTOCOL.certkeys] for more information. + /// See [draft-ietf-sshm-cert] for more information. /// - /// [PROTOCOL.certkeys]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD + /// [draft-ietf-sshm-cert]: https://www.ietf.org/archive/id/draft-ietf-sshm-cert-01.html #[cfg(feature = "alloc")] #[must_use] pub fn to_certificate_type(&self) -> String { diff --git a/ssh-key/src/certificate.rs b/ssh-key/src/certificate.rs index 1a37ee57..17ae0234 100644 --- a/ssh-key/src/certificate.rs +++ b/ssh-key/src/certificate.rs @@ -29,44 +29,41 @@ use { std::{fs, path::Path, time::SystemTime}, }; -/// OpenSSH certificate as specified in [PROTOCOL.certkeys]. +/// OpenSSH certificate as specified in [draft-ietf-sshm-cert]. /// -/// OpenSSH supports X.509-like certificate authorities, but using a custom -/// encoding format. +/// OpenSSH supports X.509-like certificate authorities, but using a custom encoding format. /// ///
/// Security Warning /// /// Certificates must be validated before they can be trusted! /// -/// The [`Certificate`] type does not automatically perform validation checks -/// and supports parsing certificates which may potentially be invalid. -/// Just because a [`Certificate`] parses successfully does not mean that it -/// can be trusted. +/// The [`Certificate`] type does not automatically perform validation checks and supports parsing +/// certificates which may potentially be invalid. /// -/// See "Certificate Validation" documentation below for more information on -/// how to properly validate certificates. +/// Just because a [`Certificate`] parses successfully does not mean that it can be trusted. +/// +/// See "Certificate Validation" documentation below for more information on how to properly +/// validate certificates. ///
/// /// # Certificate Validation /// -/// For a certificate to be trusted, the following properties MUST be -/// validated: +/// For a certificate to be trusted, the following properties MUST be validated: /// /// - Certificate is signed by a trusted certificate authority (CA) /// - Signature over the certificate verifies successfully /// - Current time is within the certificate's validity window /// - Certificate authorizes the expected principal -/// - All critical extensions to the certificate are recognized and validate -/// successfully. +/// - All critical extensions to the certificate are recognized and validate successfully. /// -/// The [`Certificate::validate`] and [`Certificate::validate_at`] methods can -/// be used to validate a certificate. +/// The [`Certificate::validate`] and [`Certificate::validate_at`] methods can be used to validate a +/// certificate. /// /// ## Example /// -/// The following example walks through how to implement the steps outlined -/// above for validating a certificate: +/// The following example walks through how to implement the steps outlined above for validating a +/// certificate: /// #[cfg_attr(all(feature = "p256", feature = "std"), doc = " ```")] #[cfg_attr(not(all(feature = "p256", feature = "std")), doc = " ```ignore")] @@ -103,21 +100,20 @@ use { /// /// # Certificate Builder (SSH CA support) /// -/// This crate implements all of the functionality needed for a pure Rust -/// SSH certificate authority which can build and sign OpenSSH certificates. +/// This crate implements all of the functionality needed for a pure Rust SSH certificate authority +/// which can build and sign OpenSSH certificates. /// /// See the [`Builder`] type's documentation for more information. /// /// # `serde` support /// -/// When the `serde` feature of this crate is enabled, this type receives impls -/// of [`Deserialize`][`serde::Deserialize`] and [`Serialize`][`serde::Serialize`]. +/// When the `serde` feature of this crate is enabled, this type receives impls of +/// [`Deserialize`][`serde::Deserialize`] and [`Serialize`][`serde::Serialize`]. /// -/// The serialization uses a binary encoding with binary formats like bincode -/// and CBOR, and the OpenSSH string serialization when used with -/// human-readable formats like JSON and TOML. +/// The serialization uses a binary encoding with binary formats like bincode and CBOR, and the +/// OpenSSH string serialization when used with human-readable formats like JSON and TOML. /// -/// [PROTOCOL.certkeys]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD +/// [draft-ietf-sshm-cert]: https://www.ietf.org/archive/id/draft-ietf-sshm-cert-01.html #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)] pub struct Certificate { /// CA-provided random bitstring of arbitrary length @@ -444,7 +440,7 @@ impl Certificate { return Err(Error::CertificateValidation); } - // From PROTOCOL.certkeys: + // From draft-ietf-sshm-cert: // // "valid after" and "valid before" specify a validity period for the // certificate. Each represents a time in seconds since 1970-01-01 diff --git a/ssh-key/src/certificate/unix_time.rs b/ssh-key/src/certificate/unix_time.rs index 636fe87a..dd8c9385 100644 --- a/ssh-key/src/certificate/unix_time.rs +++ b/ssh-key/src/certificate/unix_time.rs @@ -15,7 +15,7 @@ use { #[allow(clippy::as_conversions, reason = "constant")] pub(super) const MAX_SECS: u64 = i64::MAX as u64; -/// Sentinel value meaning "no expiry" per OpenSSH PROTOCOL.certkeys. +/// Sentinel value meaning "no expiry" per OpenSSH draft-ietf-sshm-cert. /// When `valid_before` is set to this value, the certificate never expires. pub(super) const FOREVER_SECS: u64 = u64::MAX; @@ -37,7 +37,7 @@ impl UnixTime { /// /// `secs` is the number of seconds since the Unix epoch and must be less /// than or equal to `i64::MAX`, or `u64::MAX` (the OpenSSH "no expiry" - /// sentinel defined in PROTOCOL.certkeys). + /// sentinel defined in draft-ietf-sshm-cert). #[cfg(not(feature = "std"))] pub(super) fn new(secs: u64) -> Result { if secs == FOREVER_SECS || secs <= MAX_SECS { @@ -53,7 +53,7 @@ impl UnixTime { /// representation with an infallible conversion (which also improves the /// `Debug` output). /// - /// `u64::MAX` is the OpenSSH "no expiry" sentinel (PROTOCOL.certkeys) and + /// `u64::MAX` is the OpenSSH "no expiry" sentinel (draft-ietf-sshm-cert) and /// is accepted; its `SystemTime` representation is capped at `MAX_SECS`. #[cfg(feature = "std")] pub(super) fn new(secs: u64) -> Result { diff --git a/ssh-key/src/public/key_data.rs b/ssh-key/src/public/key_data.rs index 5924ca98..88ce6d7f 100644 --- a/ssh-key/src/public/key_data.rs +++ b/ssh-key/src/public/key_data.rs @@ -44,11 +44,9 @@ pub enum KeyData { /// [PROTOCOL.u2f]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.u2f?annotate=HEAD SkEd25519(SkEd25519), - /// Certificate key as specified in [draft-miller-ssh-cert] - /// (and [PROTOCOL.certkeys], now deprecated in favor of the IETF draft). + /// Certificate key as specified in [draft-ietf-sshm-cert]. /// - /// [draft-miller-ssh-cert]: https://datatracker.ietf.org/doc/draft-miller-ssh-cert - /// [PROTOCOL.certkeys]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD + /// [draft-ietf-sshm-cert]: https://www.ietf.org/archive/id/draft-ietf-sshm-cert-01.html #[cfg(feature = "alloc")] Certificate(Box), diff --git a/ssh-key/src/signature.rs b/ssh-key/src/signature.rs index db132c31..98e6244a 100644 --- a/ssh-key/src/signature.rs +++ b/ssh-key/src/signature.rs @@ -70,7 +70,7 @@ where /// as the higher-level [`SshSig`][`crate::SshSig`] format, which provides /// general-purpose signing functionality using SSH keys. /// -/// From OpenSSH's [PROTOCOL.certkeys] specification: +/// From OpenSSH's [draft-ietf-sshm-cert] specification: /// /// > Signatures are computed and encoded according to the rules defined for /// > the CA's public key algorithm ([RFC4253 section 6.6] for ssh-rsa and @@ -79,7 +79,7 @@ where /// RSA signature support is implemented using the SHA2 family extensions as /// described in [RFC8332]. /// -/// [PROTOCOL.certkeys]: https://cvsweb.openbsd.org/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD +/// [draft-ietf-sshm-cert]: https://www.ietf.org/archive/id/draft-ietf-sshm-cert-01.html /// [RFC4253 section 6.6]: https://datatracker.ietf.org/doc/html/rfc4253#section-6.6 /// [RFC5656]: https://datatracker.ietf.org/doc/html/rfc5656 /// [RFC8032]: https://datatracker.ietf.org/doc/html/rfc8032