diff options
Diffstat (limited to 'security/nss/lib/mozpkix/include/pkix/pkix.h')
| -rw-r--r-- | security/nss/lib/mozpkix/include/pkix/pkix.h | 160 |
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 000000000..1cd6548e4 --- /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 |