Bug 968451 - Document the exported functions exposed from mozilla::pkix (pkix/pkix.h). r=keeler
authorJ.C. Jones <jjones@mozilla.com>
Fri, 19 Dec 2014 12:25:00 +0100
changeset 220829 6ead65d7b9e8b1216e582c768dae84c433650037
parent 220828 edf2031cc7e5ccf76e5d98bdce30507901ffbdfc
child 220830 e64795aab6c9044d02ff9c46474c5ab16cd57381
push id28000
push usercbook@mozilla.com
push dateMon, 22 Dec 2014 12:13:57 +0000
treeherdermozilla-central@c82d5fcdc416 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerskeeler
bugs968451
milestone37.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 968451 - Document the exported functions exposed from mozilla::pkix (pkix/pkix.h). r=keeler
security/pkix/include/pkix/Result.h
security/pkix/include/pkix/pkix.h
--- a/security/pkix/include/pkix/Result.h
+++ b/security/pkix/include/pkix/Result.h
@@ -28,16 +28,59 @@
 #include <cassert>
 
 #include "pkix/enumclass.h"
 
 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.
 //
 // The second argument is for defining the value for the enum literal in the
 // Result enum class.
 //
 // The third argument to MOZILLA_PKIX_MAP() is used, along with the first
 // argument, for maintaining the mapping of mozilla::pkix error codes to
--- a/security/pkix/include/pkix/pkix.h
+++ b/security/pkix/include/pkix/pkix.h
@@ -75,42 +75,65 @@ namespace mozilla { namespace pkix {
 // during the validity period of the certificate.
 //
 // In general, when path building fails, BuildCertChain will return
 // Result::ERROR_UNKNOWN_ISSUER. However, if all attempted paths resulted in
 // the same error (which is trivially true when there is only one potential
 // path), more specific errors will be returned.
 //
 // ----------------------------------------------------------------------------
-// Meaning of specific error codes
+// 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.
 //
-// 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.
-
+// 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,
                       KeyPurposeId requiredEKUIfPresent,
                       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,
                                 /*out*/ uint8_t (&out)[OCSP_REQUEST_MAX_LENGTH],
                                 /*out*/ size_t& outLen);
 
 // 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
 // the encoded response if it is considered trustworthy. Only
 // good, unknown, or revoked responses that verify correctly are considered
 // trustworthy. If the response is not trustworthy, thisUpdate will be 0.
 // Similarly, the optional parameter validThrough will be the time through
 // which the encoded response is considered trustworthy (that is, as long as