OSX/libsecurity_asn1/lib/ocspTemplates.h

   1 /*
   2  * Copyright (c) 2003-2006,2008-2012 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  *
  23  * ocspTemplates.h -  ASN1 templates OCSP requests and responses.
  24  */
  25
  26 #ifndef _OCSP_TEMPLATES_H_
  27 #define _OCSP_TEMPLATES_H_
  28
  29 #include <Security/X509Templates.h> /* NSS_CertExtension */
  30 #include <Security/nameTemplates.h> /* NSS_GeneralName and support */
  31
  32 #ifdef  __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #pragma clang diagnostic push
  37 #pragma clang diagnostic ignored "-Wdeprecated-declarations"
  38
  39 // MARK: ----- OCSP Request -----
  40
  41 /*
  42  * CertID          ::=     SEQUENCE {
  43  *              hashAlgorithm           AlgorithmIdentifier,
  44  *              issuerNameHash          OCTET STRING, -- Hash of Issuer's DN
  45  *              issuerKeyHash           OCTET STRING, -- Hash of Issuers public key
  46  *              serialNumber            CertificateSerialNumber }   -- i.e., INTEGER
  47  */
  48 typedef struct {
  49         SecAsn1AlgId            algId;
  50         SecAsn1Item                                                     issuerNameHash;
  51         SecAsn1Item                                                     issuerPubKeyHash;
  52         SecAsn1Item                                                     serialNumber;
  53 } SecAsn1OCSPCertID;
  54
  55 extern const SecAsn1Template kSecAsn1OCSPCertIDTemplate[];
  56
  57 /*
  58  * Request         ::=     SEQUENCE {
  59  *              reqCert                     CertID,
  60  *              singleRequestExtensions     [0] EXPLICIT Extensions OPTIONAL }
  61  */
  62 typedef struct {
  63         SecAsn1OCSPCertID                                       reqCert;
  64     NSS_CertExtension                                   **extensions;           // optional
  65 } SecAsn1OCSPRequest;
  66
  67 extern const SecAsn1Template kSecAsn1OCSPRequestTemplate[];
  68
  69 /*
  70  * Signature       ::=     SEQUENCE {
  71  *              signatureAlgorithm      AlgorithmIdentifier,
  72  *              signature               BIT STRING,
  73  *              certs               [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL}
  74  *
  75  * Since we wish to avoid knowing anything about the details of the certs,
  76  * we declare them here as ASN_ANY, get/set as raw data, and leave it to
  77  * the CL to parse them.
  78  */
  79 typedef struct {
  80         SecAsn1AlgId            algId;
  81         SecAsn1Item                                                     sig;            // length in BITS
  82         SecAsn1Item                                                     **certs;        // OPTIONAL
  83 } SecAsn1OCSPSignature;
  84
  85 extern const SecAsn1Template kSecAsn1OCSPSignatureTemplate[];
  86
  87 /*
  88  * TBSRequest      ::=     SEQUENCE {
  89  *              version             [0]     EXPLICIT Version DEFAULT v1,
  90  *              requestorName       [1]     EXPLICIT GeneralName OPTIONAL,
  91  *              requestList                 SEQUENCE OF Request,
  92  *              requestExtensions   [2]     EXPLICIT Extensions OPTIONAL }
  93  */
  94 typedef struct {
  95         SecAsn1Item                                                     *version;                               // OPTIONAL
  96         NSS_GeneralName                                         *requestorName;                 // OPTIONAL
  97         SecAsn1OCSPRequest                                      **requestList;
  98     NSS_CertExtension                                   **requestExtensions;    // OPTIONAL
  99 } SecAsn1OCSPTbsRequest;
 100
 101 extern const SecAsn1Template kSecAsn1OCSPTbsRequestTemplate[];
 102
 103 /*
 104  * OCSPRequest     ::=     SEQUENCE {
 105  *              tbsRequest                  TBSRequest,
 106  *              optionalSignature   [0]     EXPLICIT Signature OPTIONAL }
 107  */
 108 typedef struct {
 109         SecAsn1OCSPTbsRequest                           tbsRequest;
 110         SecAsn1OCSPSignature                            *signature;                     // OPTIONAL
 111 } SecAsn1OCSPSignedRequest;
 112
 113 extern const SecAsn1Template kSecAsn1OCSPSignedRequestTemplate[];
 114
 115 // MARK: ----- OCSP Response -----
 116
 117 /*
 118  * CertStatus ::= CHOICE {
 119  *              good        [0]     IMPLICIT NULL,
 120  *              revoked     [1]     IMPLICIT RevokedInfo,
 121  *              unknown     [2]     IMPLICIT UnknownInfo }
 122  *
 123  * RevokedInfo ::= SEQUENCE {
 124  *              revocationTime              GeneralizedTime,
 125  *              revocationReason    [0]     EXPLICIT CRLReason OPTIONAL }
 126  *
 127  * UnknownInfo ::= NULL -- this can be replaced with an enumeration
 128  *
 129  * See <Security/certextensions.h> for enum values of CE_CrlReason.
 130  */
 131 typedef struct {
 132         SecAsn1Item                                     revocationTime;
 133         SecAsn1Item                                     *revocationReason;              // OPTIONAL, CE_CrlReason
 134 } SecAsn1OCSPRevokedInfo;
 135
 136 typedef union {
 137         SecAsn1OCSPRevokedInfo          *revokedInfo;
 138         SecAsn1Item                                     *nullData;
 139 } SecAsn1OCSPCertStatus;
 140
 141 typedef enum {
 142         CS_Good = 0,
 143         CS_Revoked = 1,
 144         CS_Unknown = 2,
 145         CS_NotParsed = 0xff             /* Not in protocol: means value not parsed or seen */
 146 } SecAsn1OCSPCertStatusTag;
 147
 148 extern const SecAsn1Template kSecAsn1OCSPRevokedInfoTemplate[];
 149
 150 /*
 151  * Encode/decode CertStatus separately using one of these  hree templates.
 152  * The result goes into SecAsn1OCSPSingleResponse.certStatus on encode.
 153  */
 154 extern const SecAsn1Template kSecAsn1OCSPCertStatusGoodTemplate[];
 155 extern const SecAsn1Template kSecAsn1OCSPCertStatusRevokedTemplate[];
 156 extern const SecAsn1Template kSecAsn1OCSPCertStatusUnknownTemplate[];
 157
 158 /*
 159  * SingleResponse ::= SEQUENCE {
 160  *              certID                       CertID,
 161  *              certStatus                   CertStatus,
 162  *              thisUpdate                   GeneralizedTime,
 163  *              nextUpdate         [0]       EXPLICIT GeneralizedTime OPTIONAL,
 164  *              singleExtensions   [1]       EXPLICIT Extensions OPTIONAL }
 165  */
 166 typedef struct {
 167         SecAsn1OCSPCertID                       certID;
 168         SecAsn1Item                                     certStatus;                             // ASN_ANY here
 169         SecAsn1Item                                     thisUpdate;                             // GeneralizedTime
 170         SecAsn1Item                                     *nextUpdate;                    // GeneralizedTime, OPTIONAL
 171     NSS_CertExtension                   **singleExtensions;             // OPTIONAL
 172 } SecAsn1OCSPSingleResponse;
 173
 174 extern const SecAsn1Template kSecAsn1OCSPSingleResponseTemplate[];
 175
 176 /*
 177  * ResponderID ::= CHOICE {
 178  *     byName               EXPLICIT [1] Name,
 179  *     byKey                EXPLICIT [2] KeyHash }
 180  *
 181  * Since our ASN.1 encoder/decoder can't handle CHOICEs very well, we encode
 182  * this separately using one of the following two templates. On encode the
 183  * result if this step of the encode goes into SecAsn1OCSPResponseData.responderID,
 184  * where it's treated as an ANY_ANY when encoding that struct. The reverse happens
 185  * on decode.
 186  */
 187 typedef union {
 188         SecAsn1Item                                     byName;
 189         SecAsn1Item                                     byKey;          // key hash in OCTET STRING
 190 } SecAsn1OCSPResponderID;
 191
 192 typedef enum {
 193         RIT_Name        = 1,
 194         RIT_Key         = 2
 195 } SecAsn1OCSPResponderIDTag;
 196
 197 extern const SecAsn1Template kSecAsn1OCSPResponderIDAsNameTemplate[];
 198 extern const SecAsn1Template kSecAsn1OCSPResponderIDAsKeyTemplate[];
 199
 200 /*
 201  * ResponseData ::= SEQUENCE {
 202  *              version              [0] EXPLICIT Version DEFAULT v1,
 203  *              responderID              ResponderID,
 204  *              producedAt               GeneralizedTime,
 205  *              responses                SEQUENCE OF SingleResponse,
 206  *              responseExtensions   [1] EXPLICIT Extensions OPTIONAL }
 207  */
 208 typedef struct {
 209         SecAsn1Item                                     *version;               // OPTIONAL
 210         SecAsn1Item                                     responderID;    // ASN_ANY here, decode/encode separately
 211         SecAsn1Item                                     producedAt;             // GeneralizedTime
 212         SecAsn1OCSPSingleResponse   **responses;
 213     NSS_CertExtension                   **responseExtensions;   // OPTIONAL
 214 } SecAsn1OCSPResponseData;
 215
 216 extern const SecAsn1Template kSecAsn1OCSPResponseDataTemplate[];
 217
 218 /*
 219  * BasicOCSPResponse       ::= SEQUENCE {
 220  *              tbsResponseData      ResponseData,
 221  *              signatureAlgorithm   AlgorithmIdentifier,
 222  *              signature            BIT STRING,
 223  *              certs                [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL }
 224  *
 225  * Since we ALWAYS encode the tbsResponseData in preparation for signing,
 226  * we declare it as a raw ASN_ANY in the BasicOCSPResponse.
 227  *
 228  * Certs are likewise ASN_ANY since we use the CL to parse and create them.
 229  */
 230 typedef struct {
 231         SecAsn1Item                                             tbsResponseData;
 232         SecAsn1AlgId    algId;
 233         SecAsn1Item                                             sig;            // length in BITS
 234         SecAsn1Item                                             **certs;        // optional
 235 } SecAsn1OCSPBasicResponse;
 236
 237 extern const SecAsn1Template kSecAsn1OCSPBasicResponseTemplate[];
 238
 239 /*
 240  * ResponseBytes ::=       SEQUENCE {
 241  *              responseType   OBJECT IDENTIFIER,
 242  *              response       OCTET STRING }
 243  *
 244  * The contents of response are actually an encoded SecAsn1OCSPBasicResponse (at
 245  * least until another response type is defined).
 246  */
 247 typedef struct {
 248         SecAsn1Oid                                      responseType;
 249         SecAsn1Item                                     response;
 250 } SecAsn1OCSPResponseBytes;
 251
 252 extern const SecAsn1Template kSecAsn1OCSPResponseBytesTemplate[];
 253
 254 /*
 255  * OCSPResponse ::= SEQUENCE {
 256  *              responseStatus         OCSPResponseStatus,              -- an ENUM
 257  *              responseBytes          [0] EXPLICIT ResponseBytes OPTIONAL }
 258  */
 259 typedef struct {
 260         SecAsn1Item                                     responseStatus;         // see enum below
 261         SecAsn1OCSPResponseBytes        *responseBytes;         // optional
 262 } SecAsn1OCSPResponse;
 263
 264 extern const SecAsn1Template kSecAsn1OCSPResponseTemplate[];
 265
 266 typedef enum {
 267         RS_Success = 0,
 268         RS_MalformedRequest = 1,
 269         RS_InternalError = 2,
 270         RS_TryLater = 3,
 271         RS_Unused = 4,
 272         RS_SigRequired = 5,
 273         RS_Unauthorized = 6
 274 } SecAsn1OCSPResponseStatus;
 275
 276 /*
 277  * This is not part of the OCSP protocol; it's used in the communication between
 278  * the Apple X.509 TP module and the ocspd server.
 279  *
 280  * OCSPDRequest ::= SEQUENCE {
 281  *              cacheWriteDisable :: = EXPLICIT [0] BOOL OPTIONAL;      -- cache write disable
 282  *                                                                                                                      --  default FALSE
 283  *              cacheWriteDisable :: = EXPLICIT [1] BOOL OPTIONAL;      -- cache read disable
 284  *                                                                                                                      --  default FALSE
 285  *              certID          ::= OCTET STRING;                                               -- for cache lookup
 286  *              ocspReq         ::= EXPLICIT [2] OCTET STRING OPTIONAL; -- for net fetch
 287  *              localResp       ::= EXPLICIT [3] IA5String OPTIONAL;    -- for local responder
 288  *              urls            ::= EXPLICIT [4] SEQUENCE of IA5String OPTIONAL;
 289  *                                                                                                                      -- for normal net fetch
 290  * };
 291  */
 292
 293 #define OCSPD_REQUEST_VERS      0
 294
 295 typedef struct {
 296         SecAsn1Item                     *cacheWriteDisable;
 297         SecAsn1Item                     *cacheReadDisable;
 298         SecAsn1Item                     certID;                         // DER encoded SecAsn1OCSPCertID
 299         SecAsn1Item                     *ocspReq;                       // DER encoded SecAsn1OCSPSignedRequest
 300         SecAsn1Item                     *localRespURI;          // local responder URI
 301         SecAsn1Item                     **urls;                         // normal URIs
 302
 303 } SecAsn1OCSPDRequest;
 304
 305 /*
 306  * And this is a sequence of them, packaged up and sent to ocspd in one RPC.
 307  */
 308 typedef struct {
 309         SecAsn1Item                     version;                        // OCSPD_REQUEST_VERS
 310         SecAsn1OCSPDRequest     **requests;
 311 } SecAsn1OCSPDRequests;
 312
 313 extern const SecAsn1Template kSecAsn1OCSPDRequestTemplate[];
 314 extern const SecAsn1Template kSecAsn1OCSPDRequestsTemplate[];
 315
 316 /*
 317  * Unordered set of replies from ocsdp; they map back to individual
 318  * SecAsn1OCSPDRequests by the encoded certID (which is obtained from the
 319  * SecAsn1OCSPDRequest, NOT from the OCSP response).
 320  */
 321 typedef struct {
 322         SecAsn1Item                     certID;                 // DER encoded SecAsn1OCSPCertID
 323         SecAsn1Item                     ocspResp;               // DER encoded SecAsn1OCSPResponse
 324 } SecAsn1OCSPDReply;
 325
 326 #define OCSPD_REPLY_VERS        0
 327
 328 typedef struct {
 329         SecAsn1Item                     version;                        // OCSPD_REPLY_VERS
 330         SecAsn1OCSPDReply       **replies;
 331 } SecAsn1OCSPReplies;
 332
 333 extern const SecAsn1Template kSecAsn1OCSPDReplyTemplate[];
 334 extern const SecAsn1Template kSecAsn1OCSPDRepliesTemplate[];
 335
 336 #pragma clang diagnostic pop
 337
 338 #ifdef  __cplusplus
 339 }
 340 #endif
 341
 342 #endif  /* _OCSP_TEMPLATES_H_ */