From b47d94a0c875396405c0348d54272e6e37cc69bb Mon Sep 17 00:00:00 2001 From: "J.C. Jones" Date: Fri, 19 Dec 2014 12:25:00 +0100 Subject: [PATCH] Bug 968451 - Document the exported functions exposed from mozilla::pkix (pkix/pkix.h). r=keeler --- security/pkix/include/pkix/Result.h | 43 +++++++++++++++++++++++++++++ security/pkix/include/pkix/pkix.h | 39 ++++++++++++++++++++------ 2 files changed, 74 insertions(+), 8 deletions(-) diff --git a/security/pkix/include/pkix/Result.h b/security/pkix/include/pkix/Result.h index 9dbd7240b137..ebea29026a28 100644 --- a/security/pkix/include/pkix/Result.h +++ b/security/pkix/include/pkix/Result.h @@ -33,6 +33,49 @@ namespace mozilla { namespace pkix { static const unsigned int FATAL_ERROR_FLAG = 0x800; +// ---------------------------------------------------------------------------- +// SELECTED ERROR CODE EXPLANATIONS +// +// Result::ERROR_UNTRUSTED_CERT +// means that the end-entity certificate was actively distrusted. +// Result::ERROR_UNTRUSTED_ISSUER +// means that path building failed because of active distrust. +// Result::ERROR_INVALID_TIME +// means the DER-encoded time was unexpected, such as being before the +// UNIX epoch (allowed by X500, but not valid here). +// Result::ERROR_EXPIRED_CERTIFICATE +// means the end entity certificate expired. +// Result::ERROR_EXPIRED_ISSUER_CERTIFICATE +// means the CA certificate expired. +// Result::ERROR_UNKNOWN_ISSUER +// means that the CA could not be found in the root store. +// Result::ERROR_POLICY_VALIDATION_FAILED +// means that an encoded policy could not be applied or wasn't present +// when expected. Usually this is in the context of Extended Validation. +// Result::ERROR_BAD_CERT_DOMAIN +// means that the certificate's name couldn't be matched to the +// reference identifier. +// Result::ERROR_CERT_NOT_IN_NAME_SPACE +// typically means the certificate violates name constraints applied +// by the issuer. +// Result::ERROR_BAD_DER +// means the input was improperly encoded. +// Result::ERROR_UNKNOWN_ERROR +// means that an external library (NSS) provided an error we didn't +// anticipate. See the map below in Result.h to add new ones. +// Result::FATAL_ERROR_LIBRARY_FAILURE +// is an unexpected fatal error indicating a library had an unexpected +// failure, and we can't proceed. +// Result::FATAL_ERROR_INVALID_ARGS +// means that we violated our own expectations on inputs and there's a +// bug somewhere. +// Result::FATAL_ERROR_INVALID_STATE +// means that we violated our own expectations on state and there's a +// bug somewhere. +// Result::FATAL_ERROR_NO_MEMORY +// means a memory allocation failed, prohibiting validation. +// ---------------------------------------------------------------------------- + // The first argument to MOZILLA_PKIX_MAP() is used for building the mapping // from error code to error name in MapResultToName. // diff --git a/security/pkix/include/pkix/pkix.h b/security/pkix/include/pkix/pkix.h index 62fd14859987..771ef51dae23 100644 --- a/security/pkix/include/pkix/pkix.h +++ b/security/pkix/include/pkix/pkix.h @@ -80,14 +80,29 @@ namespace mozilla { namespace pkix { // path), more specific errors will be returned. // // ---------------------------------------------------------------------------- -// Meaning of specific error codes -// -// Result::ERROR_UNTRUSTED_CERT means that the end-entity certificate was -// actively distrusted. -// Result::SEC_ERROR_UNTRUSTED_ISSUER means that path building failed because -// of active distrust. -// TODO(bug 968451): Document more of these. +// Meanings of specific error codes can be found in Result.h +// This function attempts to find a trustworthy path from the supplied +// certificate to a trust anchor. In the event that no trusted path is found, +// the method returns an error result; the error ranking is described above. +// +// Parameters: +// time: +// Timestamp for which the chain should be valid; this is useful to +// analyze whether a record was trustworthy when it was made. +// requiredKeyUsageIfPresent: +// What key usage bits must be set, if the extension is present at all, +// to be considered a valid chain. Multiple values should be OR'd +// together. If you don't want to specify anything, use +// KeyUsage::noParticularKeyUsageRequired. +// requiredEKUIfPresent: +// What extended key usage bits must be set, if the EKU extension +// exists, to be considered a valid chain. Multiple values should be +// OR'd together. If you don't want to specify anything, use +// KeyPurposeId::anyExtendedKeyUsage. +// requiredPolicy: +// This is the policy to apply; typically included in EV certificates. +// If there is no policy, pass in CertPolicyId::anyPolicy. Result BuildCertChain(TrustDomain& trustDomain, Input cert, Time time, EndEntityOrCA endEntityOrCA, KeyUsage requiredKeyUsageIfPresent, @@ -95,8 +110,16 @@ Result BuildCertChain(TrustDomain& trustDomain, Input cert, const CertPolicyId& requiredPolicy, /*optional*/ const Input* stapledOCSPResponse); +// Verify that the given end-entity cert, which is assumed to have been already +// validated with BuildCertChain, is valid for the given hostname. The matching +// function attempts to implement RFC 6125 with a couple of differences: +// - IP addresses are out of scope of RFC 6125, but this method accepts them for +// backward compatibility (see SearchNames in pkixnames.cpp) +// - A wildcard in a DNS-ID may only appear as the entirety of the first label. Result CheckCertHostname(Input cert, Input hostname); +// Construct an RFC-6960-encoded OCSP request, ready for submission to a +// responder, for the provided CertID. The request has no extensions. static const size_t OCSP_REQUEST_MAX_LENGTH = 127; Result CreateEncodedOCSPRequest(TrustDomain& trustDomain, const struct CertID& certID, @@ -105,7 +128,7 @@ Result CreateEncodedOCSPRequest(TrustDomain& trustDomain, // The out parameter expired will be true if the response has expired. If the // response also indicates a revoked or unknown certificate, that error -// will be returned. Otherwise, REsult::ERROR_OCSP_OLD_RESPONSE will be +// will be returned. Otherwise, Result::ERROR_OCSP_OLD_RESPONSE will be // returned for an expired response. // // The optional parameter thisUpdate will be the thisUpdate value of