Documentation: Change |...| to `...` for code references in comments 6/N This CL includes the result of running util/update_comment_style.py over all public header files in include/openssl/pki, and fixing omissions manually if necessary. Bug: 42290410 Change-Id: I2c6cb4270f5d68c27b7adc0ddb26b6e86a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96128 Commit-Queue: Lily Chen <chlily@google.com> Reviewed-by: David Benjamin <davidben@google.com>
diff --git a/include/openssl/pki/certificate.h b/include/openssl/pki/certificate.h index 94017a1..d424735 100644 --- a/include/openssl/pki/certificate.h +++ b/include/openssl/pki/certificate.h
@@ -35,16 +35,16 @@ ~Certificate(); Certificate& operator=(const Certificate& other) = delete; - // FromDER returns a certificate from an DER-encoded X.509 object in |der|. - // In the event of a failure, it will return no value, and |out_diagnostic| + // FromDER returns a certificate from an DER-encoded X.509 object in `der`. + // In the event of a failure, it will return no value, and `out_diagnostic` // may be set to a string of human readable debugging information if // information about the failure is available. static std::unique_ptr<Certificate> FromDER( bssl::Span<const uint8_t> der, std::string *out_diagnostic); // FromPEM returns a certificate from the first CERTIFICATE PEM block in - // |pem|. In the event of a failure, it will return no value, and - // |out_diagnostic| may be set to a string of human readable debugging + // `pem`. In the event of a failure, it will return no value, and + // `out_diagnostic` may be set to a string of human readable debugging // information if information about the failure is available. static std::unique_ptr<Certificate> FromPEM( std::string_view pem, std::string *out_diagnostic);
diff --git a/include/openssl/pki/ocsp.h b/include/openssl/pki/ocsp.h index 29f529b..b22a36c 100644 --- a/include/openssl/pki/ocsp.h +++ b/include/openssl/pki/ocsp.h
@@ -33,10 +33,10 @@ // The result of OCSP verification. This always contains a ResponseStatus, which // describes whether or not an OCSP response was provided, and response level -// errors. It optionally contains an OCSPRevocationStatus when |response_status -// = PROVIDED|. For example, a stapled OCSP response matching the certificate, -// and indicating a non-revoked status, will have |response_status = PROVIDED| -// and |revocation_status = GOOD|. +// errors. It optionally contains an OCSPRevocationStatus when +// `response_status = PROVIDED`. For example, a stapled OCSP response matching +// the certificate, and indicating a non-revoked status, will have +// `response_status = PROVIDED` and `revocation_status = GOOD`. struct OPENSSL_EXPORT OCSPVerifyResult { bool operator==(const OCSPVerifyResult &other) const { if (response_status != other.response_status) { @@ -44,7 +44,7 @@ } if (response_status == PROVIDED) { - // |revocation_status| is only defined when |response_status| is PROVIDED. + // `revocation_status` is only defined when `response_status` is PROVIDED. return revocation_status == other.revocation_status; } return true; @@ -92,26 +92,26 @@ ResponseStatus response_status = NOT_CHECKED; // The strictest CertStatus matching the certificate (REVOKED > UNKNOWN > - // GOOD). Only valid if |response_status| = PROVIDED. + // GOOD). Only valid if `response_status` = PROVIDED. OCSPRevocationStatus revocation_status = OCSPRevocationStatus::UNKNOWN; }; -// Checks the revocation status of the certificate |certificate_der| by using -// the DER-encoded |raw_response|. +// Checks the revocation status of the certificate `certificate_der` by using +// the DER-encoded `raw_response`. // // Returns GOOD if the OCSP response indicates the certificate is not revoked, // REVOKED if it indicates it is revoked, or UNKNOWN for all other cases. // -// * |raw_response|: A DER encoded OCSPResponse. -// * |certificate_der|: The certificate being checked for revocation. -// * |issuer_certificate_der|: The certificate that signed |certificate_der|. +// * `raw_response`: A DER encoded OCSPResponse. +// * `certificate_der`: The certificate being checked for revocation. +// * `issuer_certificate_der`: The certificate that signed `certificate_der`. // The caller must have already performed path verification. -// * |verify_time_epoch_seconds|: The time as the difference in seconds from +// * `verify_time_epoch_seconds`: The time as the difference in seconds from // the POSIX epoch to use when checking revocation status. -// * |max_age_seconds|: The maximum age in seconds for a CRL, implemented as -// time since the |thisUpdate| field in the CRL TBSCertList. Responses -// older than |max_age_seconds| will be considered invalid. -// * |response_details|: Additional details about failures. +// * `max_age_seconds`: The maximum age in seconds for a CRL, implemented as +// time since the `thisUpdate` field in the CRL TBSCertList. Responses +// older than `max_age_seconds` will be considered invalid. +// * `response_details`: Additional details about failures. [[nodiscard]] OPENSSL_EXPORT OCSPRevocationStatus CheckOCSP( std::string_view raw_response, std::string_view certificate_der, std::string_view issuer_certificate_der, int64_t verify_time_epoch_seconds,
diff --git a/include/openssl/pki/signature_verify_cache.h b/include/openssl/pki/signature_verify_cache.h index 32cc107..0c2ae52 100644 --- a/include/openssl/pki/signature_verify_cache.h +++ b/include/openssl/pki/signature_verify_cache.h
@@ -35,14 +35,14 @@ // std::unordered_map or similar can run into problems with std::hash before // C++20. (https://en.cppreference.com/w/cpp/container/unordered_map/find) - // |Store| is called to store the result of a verification for |key| as kValid + // `Store` is called to store the result of a verification for `key` as kValid // or kInvalid after a signature check. virtual void Store(const std::string &key, Value value) = 0; - // |Check| is called to fetch a cached value for a verification for |key|. If + // `Check` is called to fetch a cached value for a verification for `key`. If // the result is kValid, or kInvalid, signature checking is skipped and the // corresponding cached result is used. If the result is kUnknown signature - // checking is performed and the corresponding result saved using |Store|. + // checking is performed and the corresponding result saved using `Store`. virtual Value Check(const std::string &key) = 0; };
diff --git a/include/openssl/pki/verify.h b/include/openssl/pki/verify.h index 9968766..2d9779d 100644 --- a/include/openssl/pki/verify.h +++ b/include/openssl/pki/verify.h
@@ -23,15 +23,15 @@ ~VerifyTrustStore(); - // FromDER returns a |TrustStore| derived from interpreting the |der_certs| as + // FromDER returns a `TrustStore` derived from interpreting the `der_certs` as // a bunch of DER-encoded certs, concatenated. In the event of a failure nullptr - // e is returned and a diagnostic string is placed in |out_diagnostic| + // e is returned and a diagnostic string is placed in `out_diagnostic` static std::unique_ptr<VerifyTrustStore> FromDER( std::string_view der_certs, std::string *out_diagnostic); - // FromDER returns a |TrustStore| consisting of the supplied DER-encoded - // certs in |der_certs|. In the event of a failure nullptr is returned and a - // diagnostic string is placed in |out_diagnostic| + // FromDER returns a `TrustStore` consisting of the supplied DER-encoded + // certs in `der_certs`. In the event of a failure nullptr is returned and a + // diagnostic string is placed in `out_diagnostic` static std::unique_ptr<VerifyTrustStore> FromDER( const std::vector<std::string_view> &der_certs, std::string *out_diagnostic); @@ -44,9 +44,9 @@ CertPool &operator=(const CertPool &) = delete; virtual ~CertPool(); - // FromCerts returns a |CertPool| consisting of the supplied DER-encoded - // certs in |der_certs|. In the event of a failure nullptr is returned and a - // diagnostic string is placed in |out_diagnostic| + // FromCerts returns a `CertPool` consisting of the supplied DER-encoded + // certs in `der_certs`. In the event of a failure nullptr is returned and a + // diagnostic string is placed in `out_diagnostic` static std::unique_ptr<CertPool> FromCerts( const std::vector<std::string_view> &der_certs, std::string *out_diagnostic); @@ -106,11 +106,11 @@ uint32_t max_iteration_count = 20; // Sets an optional deadline for completing path building. It defaults - // to std::chrono::time_point::max() if it not set. If |deadline| has a + // to std::chrono::time_point::max() if it not set. If `deadline` has a // value that has passed based on comparison to // std::chrono::steady_clock::now(), and path building has not completed, // path building will stop. Note that this is not a hard limit, there is no - // guarantee how far past |deadline| time will be when path building is + // guarantee how far past `deadline` time will be when path building is // aborted. std::optional<std::chrono::time_point<std::chrono::steady_clock>> deadline; @@ -151,19 +151,19 @@ size_t max_depth_seen_ = 0; }; -// Verify verifies |opts.leaf_cert| using the other values in |opts|. It +// Verify verifies `opts.leaf_cert` using the other values in `opts`. It // returns either an error, or else a validated chain from leaf to root. // -// In the event of an error return, |out_error| will be updated with information -// about the error. It may be |nullptr|. +// In the event of an error return, `out_error` will be updated with information +// about the error. It may be `nullptr`. // -// Status information about the verification will be returned in |out_status|. -// It may be |nullptr|. +// Status information about the verification will be returned in `out_status`. +// It may be `nullptr`. OPENSSL_EXPORT std::optional<std::vector<std::string>> CertificateVerify( const CertificateVerifyOptions &opts, VerifyError *out_error = nullptr, CertificateVerifyStatus *out_status = nullptr); -// VerifyAllPaths verifies |opts.leaf_cert| using the other values in |opts|, +// VerifyAllPaths verifies `opts.leaf_cert` using the other values in `opts`, // and returns all possible valid chains from the leaf to a root. If no chains // exist, it returns an error. OPENSSL_EXPORT std::optional<std::vector<std::vector<std::string>>>
diff --git a/include/openssl/pki/verify_error.h b/include/openssl/pki/verify_error.h index d930371..58650e2 100644 --- a/include/openssl/pki/verify_error.h +++ b/include/openssl/pki/verify_error.h
@@ -59,11 +59,11 @@ CERTIFICATE_UNABLE_TO_CHECK_REVOCATION, // CERTIFICATE_EXPIRED means that the validation time is after the - // certificate's |notAfter| timestamp. + // certificate's `notAfter` timestamp. CERTIFICATE_EXPIRED, // CERTIFICATE_NOT_YET_VALID means that the validation time is before the - // certificate's |notBefore| timestamp. + // certificate's `notBefore` timestamp. CERTIFICATE_NOT_YET_VALID, // CERTIFICATE_NO_MATCHING_EKU means that the certificate's EKU does not