The Tor Browser / file revision

 /* 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_ */