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