summaryrefslogtreecommitdiff
path: root/security/nss/lib/mozpkix/include/pkix/pkix.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/mozpkix/include/pkix/pkix.h')
-rw-r--r--security/nss/lib/mozpkix/include/pkix/pkix.h160
1 files changed, 160 insertions, 0 deletions
diff --git a/security/nss/lib/mozpkix/include/pkix/pkix.h b/security/nss/lib/mozpkix/include/pkix/pkix.h
new file mode 100644
index 0000000000..1cd6548e48
--- /dev/null
+++ b/security/nss/lib/mozpkix/include/pkix/pkix.h
@@ -0,0 +1,160 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ts=8 sts=2 et sw=2 tw=80: */
+/* This code is made available to you under your choice of the following sets
+ * of licensing terms:
+ */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+/* Copyright 2013 Mozilla Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef mozilla_pkix_pkix_h
+#define mozilla_pkix_pkix_h
+
+#include "mozpkix/pkixtypes.h"
+
+namespace mozilla {
+namespace pkix {
+
+// ----------------------------------------------------------------------------
+// LIMITED SUPPORT FOR CERTIFICATE POLICIES
+//
+// If SEC_OID_X509_ANY_POLICY is passed as the value of the requiredPolicy
+// parameter then all policy validation will be skipped. Otherwise, path
+// building and validation will be done for the given policy.
+//
+// In RFC 5280 terms:
+//
+// * user-initial-policy-set = { requiredPolicy }.
+// * initial-explicit-policy = true
+// * initial-any-policy-inhibit = false
+//
+// We allow intermediate cerificates to use this extension but since
+// we do not process the inhibit anyPolicy extesion we will fail if this
+// extension is present. TODO(bug 989051)
+// Because we force explicit policy and because we prohibit policy mapping, we
+// do not bother processing the policy mapping, or policy constraint.
+//
+// ----------------------------------------------------------------------------
+// ERROR RANKING
+//
+// BuildCertChain prioritizes certain checks ahead of others so that when a
+// certificate chain has multiple errors, the "most serious" error is
+// returned. In practice, this ranking of seriousness is tied directly to how
+// Firefox's certificate error override mechanism.
+//
+// The ranking is:
+//
+// 1. Active distrust (Result::ERROR_UNTRUSTED_CERT).
+// 2. Problems with issuer-independent properties for CA certificates.
+// 3. Unknown issuer (Result::ERROR_UNKNOWN_ISSUER).
+// 4. Problems with issuer-independent properties for EE certificates.
+// 5. Revocation.
+//
+// In particular, if BuildCertChain returns Result::ERROR_UNKNOWN_ISSUER then
+// the caller can call CERT_CheckCertValidTimes to determine if the certificate
+// is ALSO expired.
+//
+// It would be better if revocation were prioritized above expiration and
+// unknown issuer. However, it is impossible to do revocation checking without
+// knowing the issuer, since the issuer information is needed to validate the
+// revocation information. Also, generally revocation checking only works
+// 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.
+//
+// ----------------------------------------------------------------------------
+// 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,
+ 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,
+ NameMatchingPolicy& nameMatchingPolicy);
+
+// 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 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
+// 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
+// the given time at which to validate is less than or equal to validThrough,
+// the response will be considered trustworthy).
+Result VerifyEncodedOCSPResponse(
+ TrustDomain& trustDomain, const CertID& certID, Time time,
+ uint16_t maxLifetimeInDays, Input encodedResponse,
+ /* out */ bool& expired,
+ /* optional out */ Time* thisUpdate = nullptr,
+ /* optional out */ Time* validThrough = nullptr);
+
+// Check that the TLSFeature extensions in a given end-entity cert (which is
+// assumed to have been already validated with BuildCertChain) are satisfied.
+// The only feature which we cancurrently process a requirement for is
+// status_request (OCSP stapling) so we reject any extension that specifies a
+// requirement for another value. Empty extensions are also rejected.
+Result CheckTLSFeaturesAreSatisfied(Input& cert,
+ const Input* stapledOCSPResponse);
+}
+} // namespace mozilla::pkix
+
+#endif // mozilla_pkix_pkix_h