OSX/libsecurity_asn1/lib/pkcs12Templates.h

   1 /*
   2  * Copyright (c) 2003-2004,2008,2010,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 /*
  24  * pkcs12Templates.h
  25  *
  26  *******************************************************************
  27  *
  28  * In a probably vain attempt to clarify the structure of a PKCS12
  29  * PFX, here is a high-level summary.
  30  *
  31  * The top level item in P12 is a PFX.
  32  *
  33  * PFX = {
  34  *      int version;
  35  *              ContentInfo authSafe;   -- from PKCS7
  36  *              MacData mac;                    -- optional, password integrity version
  37  * }
  38  *
  39  * The authSafe in a PFX has two legal contentTypes in the P12
  40  * world, CT_Data (password integrity mode) or CT_SignedData
  41  * (public key integrity mode). The current version of this library
  42  * only supports password integrity mode. Thus the integrity of
  43  * the whole authSafe item is protected by a MAC in the PFX.
  44  *
  45  * The authSafe.content field is a BER-encoded AuthenticatedSafe.
  46  *
  47  * AuthenticatedSafe = {
  48  *              SEQUENCE OF ContentInfo;
  49  * }
  50  *
  51  * OK. Each ContentInfo in an AuthenticatedSafe can either be type
  52  * CT_Data, CT_EnvData, or CT_EncryptedData. In the latter cases the
  53  * content is decrypted to produce an encoded SafeContents; in the
  54  * former case the content *is* an encoded SafeContents.
  55  *
  56  * A SafeContents is a sequence of SafeBags.
  57  *
  58  * Each SafeBag can be of several types:
  59  *
  60  *              BT_KeyBag
  61  *              BT_ShroudedKeyBag
  62  *              BT_CertBag
  63  *              BT_CrlBag
  64  *              BT_SecretBag
  65  *              BT_SafeContentsBag
  66  *
  67  */
  68
  69 #ifndef _PKCS12_TEMPLATES_H_
  70 #define _PKCS12_TEMPLATES_H_
  71
  72 #include <Security/keyTemplates.h>      /* for NSS_Attribute */
  73 #include <security_asn1/pkcs7Templates.h>                       /* will be lib-specific place */
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 /*
  80  * MacData ::= SEQUENCE {
  81  *              mac             DigestInfo,
  82  *              macSalt     OCTET STRING,
  83  *              iterations      INTEGER DEFAULT 1
  84  * }
  85  */
  86 typedef struct {
  87         NSS_P7_DigestInfo       mac;
  88         SecAsn1Item                     macSalt;
  89         SecAsn1Item                     iterations;     // optional
  90 } NSS_P12_MacData;
  91
  92 extern const SecAsn1Template NSS_P12_MacDataTemplate[];
  93
  94 /*
  95  * PFX ::= SEQUENCE {
  96  *      version         INTEGER {v3(3)}(v3,...),
  97  *      authSafe        ContentInfo,
  98  *      macData         MacData OPTIONAL
  99  * }
 100  */
 101
 102 /*
 103  * First the top level PFX with unparsed ContentInfo.content.
 104  */
 105 typedef struct {
 106         SecAsn1Item                             version;
 107         NSS_P7_RawContentInfo   authSafe;
 108         NSS_P12_MacData                 *macData;
 109 } NSS_P12_RawPFX;
 110
 111 extern const SecAsn1Template NSS_P12_RawPFXTemplate[];
 112
 113 /*
 114  * And a PFX with a decoded ContentInfo.content.
 115  */
 116 typedef struct {
 117         SecAsn1Item                                     version;
 118         NSS_P7_DecodedContentInfo       authSafe;
 119         NSS_P12_MacData                         *macData;
 120 } NSS_P12_DecodedPFX;
 121
 122 extern const SecAsn1Template NSS_P12_DecodedPFXTemplate[];
 123
 124 /*
 125  * The CSSMOID_PKCS7_Data-style ContentInfo.content of a PFX
 126  * contains an encoded AuthenticatedSafe.
 127  *
 128  * AuthenticatedSafe ::= SEQUENCE OF ContentInfo
 129  *              -- Data if unencrypted
 130  *              -- EncryptedData if password-encrypted
 131  *              -- EnvelopedData if public key-encrypted
 132  */
 133 typedef struct {
 134         NSS_P7_DecodedContentInfo               **info;
 135 } NSS_P12_AuthenticatedSafe;
 136
 137 extern const SecAsn1Template NSS_P12_AuthenticatedSafeTemplate[];
 138
 139 /*
 140  * Individual BagTypes.
 141  * Code on demand.
 142  */
 143 typedef SecAsn1Item     NSS_P12_KeyBag;
 144 typedef NSS_EncryptedPrivateKeyInfo     NSS_P12_ShroudedKeyBag;
 145 typedef SecAsn1Item     NSS_P12_SecretBag;
 146 typedef SecAsn1Item     NSS_P12_SafeContentsBag;
 147
 148 /*
 149  * CertBag
 150  *
 151  * CertBag ::= SEQUENCE {
 152  *              certId BAG-TYPE.&id ({CertTypes}),
 153  *              certValue [0] EXPLICIT BAG-TYPE.&Type ({CertTypes}{@certId})
 154  * }
 155  *
 156  * x509Certificate BAG-TYPE ::=
 157  *              {OCTET STRING IDENTIFIED BY {certTypes 1}}
 158  *                      -- DER-encoded X.509 certificate stored in OCTET STRING
 159  * sdsiCertificate BAG-TYPE ::=
 160  *              {IA5String IDENTIFIED BY {certTypes 2}}
 161  *                      -- Base64-encoded SDSI certificate stored in IA5String
 162  */
 163 typedef enum {
 164         CT_Unknown,                     // --> ASN_ANY
 165         CT_X509,
 166         CT_SDSI,
 167 } NSS_P12_CertBagType;
 168
 169 typedef struct {
 170         SecAsn1Oid                      bagType;
 171         NSS_P12_CertBagType     type;
 172         SecAsn1Item                     certValue;
 173 } NSS_P12_CertBag;
 174
 175 extern const SecAsn1Template NSS_P12_CertBagTemplate[];
 176
 177 /*
 178  * CRLBag
 179  *
 180  * CRLBag ::= SEQUENCE {
 181  *              certId BAG-TYPE.&id ({CertTypes}),
 182  *              certValue [0] EXPLICIT BAG-TYPE.&Type ({CertTypes}{@certId})
 183  * }
 184  *
 185  * x509Certificate BAG-TYPE ::=
 186  *              {OCTET STRING IDENTIFIED BY {certTypes 1}}
 187  *                      -- DER-encoded X.509 certificate stored in OCTET STRING
 188  * sdsiCertificate BAG-TYPE ::=
 189  *              {IA5String IDENTIFIED BY {certTypes 2}}
 190  *                      -- Base64-encoded SDSI certificate stored in IA5String
 191  */
 192 typedef enum {
 193         CRT_Unknown,                    // --> ASN_ANY
 194         CRT_X509,
 195 } NSS_P12_CrlBagType;
 196
 197 typedef struct {
 198         SecAsn1Oid                      bagType;
 199         NSS_P12_CrlBagType      type;
 200         SecAsn1Item                     crlValue;
 201 } NSS_P12_CrlBag;
 202
 203 extern const SecAsn1Template NSS_P12_CrlBagTemplate[];
 204
 205 /*
 206  * BagId OIDs map to one of these for convenience. Our dynamic
 207  * template chooser drops one of these into NSS_P12_SafeBag.type
 208  * on decode.
 209  */
 210 typedef enum {
 211         BT_None = 0,
 212         BT_KeyBag,
 213         BT_ShroudedKeyBag,
 214         BT_CertBag,
 215         BT_CrlBag,
 216         BT_SecretBag,
 217         BT_SafeContentsBag
 218 } NSS_P12_SB_Type;
 219
 220 /*
 221  * The ContentInfo.content values of each element in
 222  * an AuthenticatedSafe map to a sequence of these - either directly
 223  * (contentType CSSMOID_PKCS7_Data, octet string contents are
 224  * the DER encoding of this) or indirectly (encrypted or
 225  * shrouded, the decrypted content is the DER encoding of this).
 226  */
 227 typedef struct {
 228         SecAsn1Oid                                      bagId;
 229         NSS_P12_SB_Type                         type;
 230         union {
 231                 NSS_P12_KeyBag                  *keyBag;
 232                 NSS_P12_ShroudedKeyBag  *shroudedKeyBag;
 233                 NSS_P12_CertBag                 *certBag;
 234                 NSS_P12_CrlBag                  *crlBag;
 235                 NSS_P12_SecretBag               *secretBag;
 236                 NSS_P12_SafeContentsBag *safeContentsBag;
 237         } bagValue;
 238         NSS_Attribute                           **bagAttrs;             // optional
 239 } NSS_P12_SafeBag;
 240
 241 extern const SecAsn1Template NSS_P12_SafeBagTemplate[];
 242
 243 /*
 244  * SafeContents, the contents of an element in an AuthenticatedSafe.
 245  */
 246 typedef struct {
 247         NSS_P12_SafeBag                         **bags;
 248 }
 249 NSS_P12_SafeContents;
 250
 251 extern const SecAsn1Template NSS_P12_SafeContentsTemplate[];
 252
 253 /*
 254  * PKCS12-specific algorithm parameters.
 255  * A DER encoded version of this is the parameters value of
 256  * a CSSM_X509_ALGORITHM_IDENTIFIER used in a
 257  * NSS_P7_EncrContentInfo.encrAlg in P12 password privacy mode.
 258  *
 259  * pkcs-12PbeParams ::= SEQUENCE {
 260  *              salt OCTET STRING,
 261  *              iterations INTEGER
 262  * }
 263  *
 264  * NOTE the P12 spec does place a limit on the value of iterations.
 265  * I guess we have to assume in actual usage that it's
 266  * restricted to (0..MAX), i.e., uint32-sized.
 267  *
 268  * We're also assuming that it is explicitly an unsigned value,
 269  * so that the value bytes in the encoding of 0xff would be
 270  * (0, 255).
 271  */
 272 typedef struct {
 273         SecAsn1Item             salt;
 274         SecAsn1Item             iterations;
 275 } NSS_P12_PBE_Params;
 276
 277 extern const SecAsn1Template NSS_P12_PBE_ParamsTemplate[];
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif  /* _PKCS12_TEMPLATES_H_ */
 284