1/* 2 * Copyright (c) 2003-2004,2008,2010 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/pkcs7Templates.h> /* will be lib-specific place */ 74 75#ifdef __cplusplus 76extern "C" { 77#endif 78 79/* 80 * MacData ::= SEQUENCE { 81 * mac DigestInfo, 82 * macSalt OCTET STRING, 83 * iterations INTEGER DEFAULT 1 84 * } 85 */ 86typedef struct { 87 NSS_P7_DigestInfo mac; 88 SecAsn1Item macSalt; 89 SecAsn1Item iterations; // optional 90} NSS_P12_MacData; 91 92extern 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 */ 105typedef struct { 106 SecAsn1Item version; 107 NSS_P7_RawContentInfo authSafe; 108 NSS_P12_MacData *macData; 109} NSS_P12_RawPFX; 110 111extern const SecAsn1Template NSS_P12_RawPFXTemplate[]; 112 113/* 114 * And a PFX with a decoded ContentInfo.content. 115 */ 116typedef struct { 117 SecAsn1Item version; 118 NSS_P7_DecodedContentInfo authSafe; 119 NSS_P12_MacData *macData; 120} NSS_P12_DecodedPFX; 121 122extern 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 */ 133typedef struct { 134 NSS_P7_DecodedContentInfo **info; 135} NSS_P12_AuthenticatedSafe; 136 137extern const SecAsn1Template NSS_P12_AuthenticatedSafeTemplate[]; 138 139/* 140 * Individual BagTypes. 141 * Code on demand. 142 */ 143typedef SecAsn1Item NSS_P12_KeyBag; 144typedef NSS_EncryptedPrivateKeyInfo NSS_P12_ShroudedKeyBag; 145typedef SecAsn1Item NSS_P12_SecretBag; 146typedef 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 */ 163typedef enum { 164 CT_Unknown, // --> ASN_ANY 165 CT_X509, 166 CT_SDSI, 167} NSS_P12_CertBagType; 168 169typedef struct { 170 SecAsn1Oid bagType; 171 NSS_P12_CertBagType type; 172 SecAsn1Item certValue; 173} NSS_P12_CertBag; 174 175extern 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 */ 192typedef enum { 193 CRT_Unknown, // --> ASN_ANY 194 CRT_X509, 195} NSS_P12_CrlBagType; 196 197typedef struct { 198 SecAsn1Oid bagType; 199 NSS_P12_CrlBagType type; 200 SecAsn1Item crlValue; 201} NSS_P12_CrlBag; 202 203extern 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 */ 210typedef 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 */ 227typedef 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 241extern const SecAsn1Template NSS_P12_SafeBagTemplate[]; 242 243/* 244 * SafeContents, the contents of an element in an AuthenticatedSafe. 245 */ 246typedef struct { 247 NSS_P12_SafeBag **bags; 248} 249NSS_P12_SafeContents; 250 251extern 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 */ 272typedef struct { 273 SecAsn1Item salt; 274 SecAsn1Item iterations; 275} NSS_P12_PBE_Params; 276 277extern const SecAsn1Template NSS_P12_PBE_ParamsTemplate[]; 278 279#ifdef __cplusplus 280} 281#endif 282 283#endif /* _PKCS12_TEMPLATES_H_ */ 284 285