summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/certhigh/ocspti.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/certhigh/ocspti.h')
-rw-r--r--security/nss/lib/certhigh/ocspti.h356
1 files changed, 356 insertions, 0 deletions
diff --git a/security/nss/lib/certhigh/ocspti.h b/security/nss/lib/certhigh/ocspti.h
new file mode 100644
index 0000000000..d9297dba6a
--- /dev/null
+++ b/security/nss/lib/certhigh/ocspti.h
@@ -0,0 +1,356 @@
+/* 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/. */
+
+/*
+ * Private header defining OCSP types.
+ */
+
+#ifndef _OCSPTI_H_
+#define _OCSPTI_H_
+
+#include "ocspt.h"
+
+#include "certt.h"
+#include "plarena.h"
+#include "seccomon.h"
+#include "secoidt.h"
+
+/*
+ * Some notes about naming conventions...
+ *
+ * The public data types all start with "CERTOCSP" (e.g. CERTOCSPRequest).
+ * (Even the public types are opaque, however. Only their names are
+ * "exported".)
+ *
+ * Internal-only data types drop the "CERT" prefix and use only the
+ * lower-case "ocsp" (e.g. ocspTBSRequest), for brevity sake.
+ *
+ * In either case, the base/suffix of the type name usually matches the
+ * name as defined in the OCSP specification. The exceptions to this are:
+ * - When there is overlap between the "OCSP" or "ocsp" prefix and
+ * the name used in the standard. That is, you cannot strip off the
+ * "CERTOCSP" or "ocsp" prefix and necessarily get the name of the
+ * type as it is defined in the standard; the "real" name will be
+ * *either* "OCSPSuffix" or just "Suffix".
+ * - When the name in the standard was a little too generic. (e.g. The
+ * standard defines "Request" but we call it a "SingleRequest".)
+ * In this case a comment above the type definition calls attention
+ * to the difference.
+ *
+ * The definitions laid out in this header file are intended to follow
+ * the same order as the definitions in the OCSP specification itself.
+ * With the OCSP standard in hand, you should be able to move through
+ * this file and follow along. To future modifiers of this file: please
+ * try to keep it that way. The only exceptions are the few cases where
+ * we need to define a type before it is referenced (e.g. enumerations),
+ * whereas in the OCSP specification these are usually defined the other
+ * way around (reference before definition).
+ */
+
+/*
+ * Forward-declarations of internal-only data structures.
+ *
+ * These are in alphabetical order (case-insensitive); please keep it that way!
+ */
+typedef struct ocspBasicOCSPResponseStr ocspBasicOCSPResponse;
+typedef struct ocspCertStatusStr ocspCertStatus;
+typedef struct ocspResponderIDStr ocspResponderID;
+typedef struct ocspResponseBytesStr ocspResponseBytes;
+typedef struct ocspResponseDataStr ocspResponseData;
+typedef struct ocspRevokedInfoStr ocspRevokedInfo;
+typedef struct ocspServiceLocatorStr ocspServiceLocator;
+typedef struct ocspSignatureStr ocspSignature;
+typedef struct ocspSingleRequestStr ocspSingleRequest;
+typedef struct ocspSingleResponseStr ocspSingleResponse;
+typedef struct ocspTBSRequestStr ocspTBSRequest;
+
+/*
+ * An OCSPRequest; this is what is sent (encoded) to an OCSP responder.
+ */
+struct CERTOCSPRequestStr {
+ PLArenaPool *arena; /* local; not part of encoding */
+ ocspTBSRequest *tbsRequest;
+ ocspSignature *optionalSignature;
+};
+
+/*
+ * A TBSRequest; when an OCSPRequest is signed, the encoding of this
+ * is what the signature is actually applied to. ("TBS" == To Be Signed)
+ * Whether signed or not, however, this structure will be present, and
+ * is the "meat" of the OCSPRequest.
+ *
+ * Note that the "requestorName" field cannot be encoded/decoded in the
+ * same pass as the entire request -- it needs to be handled with a special
+ * call to convert to/from our internal form of a GeneralName. Thus the
+ * "derRequestorName" field, which is the actual DER-encoded bytes.
+ *
+ * The "extensionHandle" field is used on creation only; it holds
+ * in-progress extensions as they are optionally added to the request.
+ */
+struct ocspTBSRequestStr {
+ SECItem version; /* an INTEGER */
+ SECItem *derRequestorName; /* encoded GeneralName; see above */
+ CERTGeneralNameList *requestorName; /* local; not part of encoding */
+ ocspSingleRequest **requestList;
+ CERTCertExtension **requestExtensions;
+ void *extensionHandle; /* local; not part of encoding */
+};
+
+/*
+ * This is the actual signature information for an OCSPRequest (applied to
+ * the TBSRequest structure) or for a BasicOCSPResponse (applied to a
+ * ResponseData structure).
+ *
+ * Note that the "signature" field itself is a BIT STRING; operations on
+ * it need to keep that in mind, converting the length to bytes as needed
+ * and back again afterward (so that the length is usually expressing bits).
+ *
+ * The "cert" field is the signer's certificate. In the case of a received
+ * signature, it will be filled in when the signature is verified. In the
+ * case of a created signature, it is filled in on creation and will be the
+ * cert used to create the signature when the signing-and-encoding occurs,
+ * as well as the cert (and its chain) to fill in derCerts if requested.
+ *
+ * The extra fields cache information about the signature after we have
+ * attempted a verification. "wasChecked", if true, means the signature
+ * has been checked against the appropriate data and thus that "status"
+ * contains the result of that verification. If "status" is not SECSuccess,
+ * "failureReason" is a copy of the error code that was set at the time;
+ * presumably it tells why the signature verification failed.
+ */
+struct ocspSignatureStr {
+ SECAlgorithmID signatureAlgorithm;
+ SECItem signature; /* a BIT STRING */
+ SECItem **derCerts; /* a SEQUENCE OF Certificate */
+ CERTCertificate *cert; /* local; not part of encoding */
+ PRBool wasChecked; /* local; not part of encoding */
+ SECStatus status; /* local; not part of encoding */
+ int failureReason; /* local; not part of encoding */
+};
+
+/*
+ * An OCSPRequest contains a SEQUENCE OF these, one for each certificate
+ * whose status is being checked.
+ *
+ * Note that in the OCSP specification this is just called "Request",
+ * but since that seemed confusing (vs. an OCSPRequest) and to be more
+ * consistent with the parallel type "SingleResponse", I called it a
+ * "SingleRequest".
+ *
+ * XXX figure out how to get rid of that arena -- there must be a way
+ */
+struct ocspSingleRequestStr {
+ PLArenaPool *arena; /* just a copy of the response arena,
+ * needed here for extension handling
+ * routines, on creation only */
+ CERTOCSPCertID *reqCert;
+ CERTCertExtension **singleRequestExtensions;
+};
+
+/*
+ * A CertID is the means of identifying a certificate, used both in requests
+ * and in responses.
+ *
+ * When in a SingleRequest it specifies the certificate to be checked.
+ * When in a SingleResponse it is the cert whose status is being given.
+ */
+struct CERTOCSPCertIDStr {
+ SECAlgorithmID hashAlgorithm;
+ SECItem issuerNameHash; /* an OCTET STRING */
+ SECItem issuerKeyHash; /* an OCTET STRING */
+ SECItem serialNumber; /* an INTEGER */
+ SECItem issuerSHA1NameHash; /* keep other hashes around when */
+ SECItem issuerMD5NameHash; /* we have them */
+ SECItem issuerMD2NameHash;
+ SECItem issuerSHA1KeyHash; /* keep other hashes around when */
+ SECItem issuerMD5KeyHash; /* we have them */
+ SECItem issuerMD2KeyHash;
+ PLArenaPool *poolp;
+};
+
+/*
+ * This describes the value of the responseStatus field in an OCSPResponse.
+ * The corresponding ASN.1 definition is:
+ *
+ * OCSPResponseStatus ::= ENUMERATED {
+ * successful (0), --Response has valid confirmations
+ * malformedRequest (1), --Illegal confirmation request
+ * internalError (2), --Internal error in issuer
+ * tryLater (3), --Try again later
+ * --(4) is not used
+ * sigRequired (5), --Must sign the request
+ * unauthorized (6), --Request unauthorized
+ * }
+ */
+typedef enum {
+ ocspResponse_min = 0,
+ ocspResponse_successful = 0,
+ ocspResponse_malformedRequest = 1,
+ ocspResponse_internalError = 2,
+ ocspResponse_tryLater = 3,
+ ocspResponse_unused = 4,
+ ocspResponse_sigRequired = 5,
+ ocspResponse_unauthorized = 6,
+ ocspResponse_max = 6 /* Please update max when adding values.
+ * Remember to also update arrays, e.g.
+ * "responseStatusNames" in ocspclnt.c
+ * and potentially other places. */
+} ocspResponseStatus;
+
+/*
+ * An OCSPResponse is what is sent (encoded) by an OCSP responder.
+ *
+ * The field "responseStatus" is the ASN.1 encoded value; the field
+ * "statusValue" is simply that same value translated into our local
+ * type ocspResponseStatus.
+ */
+struct CERTOCSPResponseStr {
+ PLArenaPool *arena; /* local; not part of encoding */
+ SECItem responseStatus; /* an ENUMERATED, see above */
+ ocspResponseStatus statusValue; /* local; not part of encoding */
+ ocspResponseBytes *responseBytes; /* only when status is successful */
+};
+
+/*
+ * A ResponseBytes (despite appearances) is what contains the meat
+ * of a successful response -- but still in encoded form. The type
+ * given as "responseType" tells you how to decode the string.
+ *
+ * We look at the OID and translate it into our local OID representation
+ * "responseTypeTag", and use that value to tell us how to decode the
+ * actual response itself. For now the only kind of OCSP response we
+ * know about is a BasicOCSPResponse. However, the intention in the
+ * OCSP specification is to allow for other response types, so we are
+ * building in that flexibility from the start and thus put a pointer
+ * to that data structure inside of a union. Whenever OCSP adds more
+ * response types, just add them to the union.
+ */
+struct ocspResponseBytesStr {
+ SECItem responseType; /* an OBJECT IDENTIFIER */
+ SECOidTag responseTypeTag; /* local; not part of encoding */
+ SECItem response; /* an OCTET STRING */
+ union {
+ ocspBasicOCSPResponse *basic; /* when type is id-pkix-ocsp-basic */
+ } decodedResponse; /* local; not part of encoding */
+};
+
+/*
+ * A BasicOCSPResponse -- when the responseType in a ResponseBytes is
+ * id-pkix-ocsp-basic, the "response" OCTET STRING above is the DER
+ * encoding of one of these.
+ *
+ * Note that in the OCSP specification, the signature fields are not
+ * part of a separate sub-structure. But since they are the same fields
+ * as we define for the signature in a request, it made sense to share
+ * the C data structure here and in some shared code to operate on them.
+ */
+struct ocspBasicOCSPResponseStr {
+ SECItem tbsResponseDataDER;
+ ocspResponseData *tbsResponseData; /* "tbs" == To Be Signed */
+ ocspSignature responseSignature;
+};
+
+/*
+ * A ResponseData is the part of a BasicOCSPResponse that is signed
+ * (after it is DER encoded). It contains the real details of the response
+ * (a per-certificate status).
+ */
+struct ocspResponseDataStr {
+ SECItem version; /* an INTEGER */
+ SECItem derResponderID;
+ ocspResponderID *responderID; /* local; not part of encoding */
+ SECItem producedAt; /* a GeneralizedTime */
+ CERTOCSPSingleResponse **responses;
+ CERTCertExtension **responseExtensions;
+};
+
+struct ocspResponderIDStr {
+ CERTOCSPResponderIDType responderIDType; /* local; not part of encoding */
+ union {
+ CERTName name; /* when ocspResponderID_byName */
+ SECItem keyHash; /* when ocspResponderID_byKey */
+ SECItem other; /* when ocspResponderID_other */
+ } responderIDValue;
+};
+
+/*
+ * The ResponseData in a BasicOCSPResponse contains a SEQUENCE OF
+ * SingleResponse -- one for each certificate whose status is being supplied.
+ *
+ * XXX figure out how to get rid of that arena -- there must be a way
+ */
+struct CERTOCSPSingleResponseStr {
+ PLArenaPool *arena; /* just a copy of the response arena,
+ * needed here for extension handling
+ * routines, on creation only */
+ CERTOCSPCertID *certID;
+ SECItem derCertStatus;
+ ocspCertStatus *certStatus; /* local; not part of encoding */
+ SECItem thisUpdate; /* a GeneralizedTime */
+ SECItem *nextUpdate; /* a GeneralizedTime */
+ CERTCertExtension **singleExtensions;
+};
+
+/*
+ * A CertStatus is the actual per-certificate status. Its ASN.1 definition:
+ *
+ * CertStatus ::= CHOICE {
+ * good [0] IMPLICIT NULL,
+ * revoked [1] IMPLICIT RevokedInfo,
+ * unknown [2] IMPLICIT UnknownInfo }
+ *
+ * (where for now UnknownInfo is defined to be NULL but in the
+ * future may be replaced with an enumeration).
+ *
+ * Because it is CHOICE, the status value and its associated information
+ * (if any) are actually encoded together. To represent this same
+ * information internally, we explicitly define a type and save it,
+ * along with the value, into a data structure.
+ */
+
+typedef enum {
+ ocspCertStatus_good, /* cert is not revoked */
+ ocspCertStatus_revoked, /* cert is revoked */
+ ocspCertStatus_unknown, /* cert was unknown to the responder */
+ ocspCertStatus_other /* status was not an expected value */
+} ocspCertStatusType;
+
+/*
+ * This is the actual per-certificate status.
+ *
+ * The "goodInfo" and "unknownInfo" items are only place-holders for a NULL.
+ * (Though someday OCSP may replace UnknownInfo with an enumeration that
+ * gives more detailed information.)
+ */
+struct ocspCertStatusStr {
+ ocspCertStatusType certStatusType; /* local; not part of encoding */
+ union {
+ SECItem *goodInfo; /* when ocspCertStatus_good */
+ ocspRevokedInfo *revokedInfo; /* when ocspCertStatus_revoked */
+ SECItem *unknownInfo; /* when ocspCertStatus_unknown */
+ SECItem *otherInfo; /* when ocspCertStatus_other */
+ } certStatusInfo;
+};
+
+/*
+ * A RevokedInfo gives information about a revoked certificate -- when it
+ * was revoked and why.
+ */
+struct ocspRevokedInfoStr {
+ SECItem revocationTime; /* a GeneralizedTime */
+ SECItem *revocationReason; /* a CRLReason; ignored for now */
+};
+
+/*
+ * ServiceLocator can be included as one of the singleRequestExtensions.
+ * When added, it specifies the (name of the) issuer of the cert being
+ * checked, and optionally the value of the AuthorityInfoAccess extension
+ * if the cert has one.
+ */
+struct ocspServiceLocatorStr {
+ CERTName *issuer;
+ SECItem locator; /* DER encoded authInfoAccess extension from cert */
+};
+
+#endif /* _OCSPTI_H_ */