OSX/include/security_pkcs12/pkcs12Templates.h

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