Bug 968451 - Document the exported functions exposed from mozilla::pkix (pkix/pkix.h). r=keeler

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.
 //

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