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/******************************************************************* 25 * 26 * SecPkcs12.h 27 * 28 * This module is an implementation of the logic required to create 29 * and parse PKCS12 "blobs", known as PFXs in PKCS12 lingo. The user 30 * of this module need not know anything about the details of 31 * PKCS12 PFX construction. All one needs to know at this level 32 * is that a PKCS12 PFX is a collection of the following items: 33 * 34 * -- Zero or more certificates 35 * -- Zero or more Certficate Revocation Lists (CRLs) 36 * -- Zero or more private keys. (If this number is zero, using this 37 * module is probably not what you want to do) 38 * -- Zero or more other opaque types, not understood or parsed 39 * by this module. 40 * 41 * Each individual component of a PFX contains zero or more 42 * attributes; commonly the only two such attributes used in 43 * the PKCS12 world are "FriendlyName", a Unicode string, and 44 * "LocalKeyId", an opaque data blob which serves solely to tie 45 * a specific cert to a specific key in the context of this specific 46 * PFX. 47 * 48 * Individual components of a PKCS12 PFX are typically encrypted with 49 * a key derived from a user-supplied passphrase. The entire PFX 50 * is protected with a MAC whose key is also derived from a user- 51 * supplied passphrase. Typically these two passphrases are identical 52 * but they don't have to be. 53 * 54 * There are a number of options and modes which, while described in 55 * the PKCS12 spec and provided for in the interface in this file, 56 * are rarely if ever used. The following is a description of the 57 * actual, typical, real-world use of this module. 58 * 59 * Decoding a PKCS12 blob 60 * ---------------------- 61 * 62 * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate(). 63 * 64 * 2. App specifies supplies a (small) number of options such as 65 * passphrase(s) and SecKeychainRefs. 66 * 67 * 3. App calls SecPkcs12Decode(), providing the raw PKCS12 PFX 68 * blob which is to be decoded. This performs all of the actual 69 * decoding and decryption. 70 * 71 * 4. At this point the app optionally obtains the resulting 72 * components by a set of calls which return individual 73 * certs, CRLS, and keys. 74 * 75 * 5. Also, per the configuration performed in step 2, individual 76 * components (certs, keys) found in the PFX have been added 77 * to a specified keychain, rendering step 4 superfluous. 78 * 79 * 80 * Creating a PKCS12 blob 81 * ---------------------- 82 * 83 * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate(). 84 * 85 * 2. App specifies supplies a (small) number of options such as 86 * passphrase(s). 87 * 88 * 3. App makes a set of calls which add individual components such 89 * as certs, CRLs, and private keys. A high-level call, 90 * SecPkcs12ExportKeychainItems(), allow the specification of 91 * all components to be exported at once. 92 * 93 * 4. App calls SecPkcs12Encode(), which does all of the required 94 * encryption and encoding. The result is an exportable PKCS12 95 * PFX blob. 96 */ 97 98#ifndef _SEC_PKCS12_H_ 99#define _SEC_PKCS12_H_ 100 101#include <CoreFoundation/CoreFoundation.h> 102#include <Security/Security.h> 103 104#ifdef __cplusplus 105extern "C" { 106#endif 107 108/* 109 * Opaque handle for a PKCS12 encoder/decoder. 110 */ 111typedef void *SecPkcs12CoderRef; 112 113#pragma mark --- SecPkcs12CoderRef create/destroy --- 114 115/* 116 * Basic SecPkcs12CoderRef create/destroy. 117 */ 118OSStatus SecPkcs12CoderCreate( 119 SecPkcs12CoderRef *coder); // RETURNED 120 121/* 122 * Destroy object created in SecPkcs12CoderCreate. 123 */ 124OSStatus SecPkcs12CoderRelease( 125 SecPkcs12CoderRef coder); 126 127#pragma mark --- High-level API --- 128 129/* 130 * Keychain associated with encode/decode. 131 * Client must call exactly one of { SecPkcs12SetKeychain(), 132 * SecPkcs12SetCspHandle() } for both encoding and decoding. 133 * If SecPkcs12SetCspHandle() is used, components which are 134 * obtained during decode are ephemeral (i.e., they are not 135 * stored anywhere and only have a lifetime which is the same as 136 * the lifetime of the SecPkcs12CoderRef). 137 */ 138OSStatus SecPkcs12SetKeychain( 139 SecPkcs12CoderRef coder, 140 SecKeychainRef keychain); 141 142/* 143 * Required iff SecPkcs12SetKeychain() is not called. 144 */ 145OSStatus SecPkcs12SetCspHandle( 146 SecPkcs12CoderRef coder, 147 CSSM_CSP_HANDLE cspHandle); 148 149 150/* 151 * PKCS12 allows for separate passphrases for encryption and for 152 * verification (via MAC). Typically, in the real world, one 153 * passphrase is used for both; we provide the means to set them 154 * separately. 155 * 156 * Passphrases can be specified directly as CFStringRefs, or as 157 * CSSM_KEYs which represent secure passphrases obtained by the 158 * SecurityServer. This latter method is preferred since the 159 * plaintext passphrase never appears in the app's address space. 160 * Passphrases expressed in this manner are referred to as 161 * PassKeys. 162 * 163 * If one passphrase is to be used for both encryption and 164 * verification, use one of these two function to set it. 165 */ 166OSStatus SecPkcs12SetMACPassphrase( 167 SecPkcs12CoderRef coder, 168 CFStringRef passphrase); 169 170OSStatus SecPkcs12SetMACPassKey( 171 SecPkcs12CoderRef coder, 172 const CSSM_KEY *passKey); 173 174/* 175 * Specify separate passphrase for encrypt/decrypt. 176 */ 177OSStatus SecPkcs12SetCryptPassphrase( 178 SecPkcs12CoderRef coder, 179 CFStringRef passphrase); 180 181OSStatus SecPkcs12SetCryptPassKey( 182 SecPkcs12CoderRef coder, 183 const CSSM_KEY *passKey); 184 185/* 186 * Prior to decoding a PFX, client can specify whether individual 187 * components (certificates, CRLs, and keys) get stored in the 188 * keychain specified via SecPkcs12SetKeychain(). 189 */ 190enum { 191 kSecImportCertificates = 0x0001, 192 kSecImportCRLs = 0x0002, 193 kSecImportKeys = 0x0004, 194}; 195 196typedef UInt32 SecPkcs12ImportFlags; 197 198OSStatus SecPkcs12SetImportToKeychain( 199 SecPkcs12CoderRef coder, 200 SecPkcs12ImportFlags flags); 201 202OSStatus SecPkcs12GetImportToKeychain( 203 SecPkcs12CoderRef coder, 204 SecPkcs12ImportFlags *flags); // RETURNED 205 206/* 207 * Specify individual SecKeychainItemRef to export, prior to encoding. 208 * The items argument is a CFArray containing any number of each 209 * of the following SecKeychainItemRef objects: 210 * 211 * SecKeyRef 212 * SecCertificateRef 213 * ...and others, in the future. 214 */ 215OSStatus SecPkcs12ExportKeychainItems( 216 SecPkcs12CoderRef coder, 217 CFArrayRef items); 218 219/* 220 * Specify additional optional imported private key attributes: 221 * -- a SecAccessRef; default is the default ACL. Passing NULL here 222 * results in private keys being created with no ACL. 223 * -- CSSM_KEYUSE; default is CSSM_KEYUSE_ANY. 224 * -- CSSM_KEYATTR_FLAGS; default is CSSM_KEYATTR_RETURN_REF | 225 * CSSM_KEYATTR_EXTRACTABLE | CSSM_KEYATTR_SENSITIVE, plus 226 * CSSM_KEYATTR_PERMANENT if importing to a keychain 227 */ 228OSStatus SecPkcs12SetAccess( 229 SecPkcs12CoderRef coder, 230 SecAccessRef access); 231 232OSStatus SecPkcs12SetKeyUsage( 233 SecPkcs12CoderRef coder, 234 CSSM_KEYUSE keyUsage); 235 236OSStatus SecPkcs12SetKeyAttrs( 237 SecPkcs12CoderRef coder, 238 CSSM_KEYATTR_FLAGS keyAttrs); 239 240/* 241 * Parse and decode. 242 */ 243OSStatus SecPkcs12Decode( 244 SecPkcs12CoderRef coder, 245 CFDataRef pfx); 246 247/* 248 * This the final step to create an encoded PKCS12 PFX blob. 249 * This called after initial configuration of the SecPkcs12CoderRef, 250 * and either specifying items to export via either 251 * SecPkcs12ExportKeychainItems() or some number of SecPkcs12Add* 252 * function calls, described below. 253 * 254 * The result is a DER-encoded PFX in PKCS12 lingo. 255 */ 256OSStatus SecPkcs12Encode( 257 SecPkcs12CoderRef coder, 258 CFDataRef *pfx); // RETURNED 259 260 261/* 262 * Opaque handle for optional attributes associated with any 263 * component of a SecPkcs12CoderRef. 264 * 265 * The use of SecPkcs12AttrsRefs is optional and in fact, in the real 266 * world, rare. Their appearance in this API is just for completeness 267 * and to allow access to all "legal" PKCS12 options. 268 * 269 * We define the type here to allow use elsewhere in this 270 * interface; actual SecPkcs12AttrsRef manipulation functions 271 * are described later in this header. 272 */ 273typedef void *SecPkcs12AttrsRef; 274 275#pragma mark --- Decoder Functions --- 276 277/* 278 * Subsequent to decoding, obtain the components. 279 * These functions can also be used as "getter" functions while encoding. 280 * 281 * Certificates: 282 */ 283OSStatus SecPkcs12CertificateCount( 284 SecPkcs12CoderRef coder, 285 CFIndex *numCerts); // RETURNED 286 287OSStatus SecPkcs12CopyCertificate( 288 SecPkcs12CoderRef coder, 289 CFIndex certNum, 290 SecCertificateRef *cert, // RETURNED 291 CFStringRef *friendlyName, // optional, RETURNED 292 CFDataRef *localKeyId, // optional, RETURNED 293 SecPkcs12AttrsRef *attrs); // optional, RETURNED 294 295/* 296 * CRLs. The might change if a SecCrl type is defined elsewhere. 297 * We'll typedef it here to preserve the semantics of this function. 298 */ 299typedef CFDataRef SecCrlRef; 300 301OSStatus SecPkcs12CrlCount( 302 SecPkcs12CoderRef coder, 303 CFIndex *numCrls); // RETURNED 304 305OSStatus SecPkcs12CopyCrl( 306 SecPkcs12CoderRef coder, 307 CFIndex crlNum, 308 SecCrlRef *crl, // RETURNED 309 CFStringRef *friendlyName, // optional, RETURNED 310 CFDataRef *localKeyId, // optional, RETURNED 311 SecPkcs12AttrsRef *attrs); // optional, RETURNED 312 313/* 314 * Private keys. 315 */ 316OSStatus SecPkcs12PrivateKeyCount( 317 SecPkcs12CoderRef coder, 318 CFIndex *numKeys); // RETURNED 319 320/* currently not implemented : use SecPkcs12GetCssmPrivateKey() */ 321OSStatus SecPkcs12CopyPrivateKey( 322 SecPkcs12CoderRef coder, 323 CFIndex keyNum, 324 SecKeyRef *privateKey, // RETURNED 325 CFStringRef *friendlyName, // optional, RETURNED 326 CFDataRef *localKeyId, // optional, RETURNED 327 SecPkcs12AttrsRef *attrs); // optional, RETURNED 328 329/* 330 * The CSSM_KEY_PTR returned by this function has a lifetime 331 * which is the same as the SecPkcs12CoderRef which created it. 332 */ 333OSStatus SecPkcs12GetCssmPrivateKey( 334 SecPkcs12CoderRef coder, 335 CFIndex keyNum, 336 CSSM_KEY_PTR *privateKey, // RETURNED 337 CFStringRef *friendlyName, // optional, RETURNED 338 CFDataRef *localKeyId, // optional, RETURNED 339 SecPkcs12AttrsRef *attrs); // optional, RETURNED 340 341/* 342 * Catch-all for other components not currently understood 343 * or supported by this library. An "opaque blob" component 344 * is identified by an OID and is obtained as an opaque data 345 * blob. 346 */ 347OSStatus SecPkcs12OpaqueBlobCount( 348 SecPkcs12CoderRef coder, 349 CFIndex *numBlobs); // RETURNED 350 351OSStatus SecPkcs12CopyOpaqueBlob( 352 SecPkcs12CoderRef coder, 353 CFIndex blobNum, 354 CFDataRef *blobOid, // RETURNED 355 CFDataRef *opaqueBlob, // RETURNED 356 CFStringRef *friendlyName, // optional, RETURNED 357 CFDataRef *localKeyId, // optional, RETURNED 358 SecPkcs12AttrsRef *attrs); // optional, RETURNED 359 360#pragma mark --- Encoder Functions --- 361 362/* 363 * Add individual components. "Getter" functions are available 364 * as described above (under "Functions used for decoding"). 365 */ 366OSStatus SecPkcs12AddCertificate( 367 SecPkcs12CoderRef coder, 368 SecCertificateRef cert, 369 CFStringRef friendlyName, // optional 370 CFDataRef localKeyId, // optional 371 SecPkcs12AttrsRef attrs); // optional 372 373OSStatus SecPkcs12AddCrl( 374 SecPkcs12CoderRef coder, 375 SecCrlRef crl, 376 CFStringRef friendlyName, // optional 377 CFDataRef localKeyId, // optional 378 SecPkcs12AttrsRef attrs); // optional 379 380OSStatus SecPkcs12AddPrivateKey( 381 SecPkcs12CoderRef coder, 382 SecKeyRef privateKey, 383 CFStringRef friendlyName, // optional 384 CFDataRef localKeyId, // optional 385 SecPkcs12AttrsRef attrs); // optional 386 387OSStatus SecPkcs12AddOpaqueBlob( 388 SecPkcs12CoderRef coder, 389 CFDataRef blobOid, 390 CFDataRef opaqueBlob, 391 CFStringRef friendlyName, // optional 392 CFDataRef localKeyId, // optional 393 SecPkcs12AttrsRef attrs); // optional 394 395 396#pragma mark --- Optional Functions --- 397 398/************************************************************ 399 *** Optional, rarely used SecPkcs12CoderRef manipulation *** 400 ************************************************************/ 401 402/*** 403 *** SecPkcs12AttrsRef manipulation. Optional and in fact expected to 404 *** be rarely used, if ever. 405 ***/ 406 407/* 408 * A SecPkcs12AttrsRef is an opaque handle referring to an aribtrary 409 * collection of OID/value pairs which can be attached to any 410 * component of a SecPkcs12CoderRef. OIDs and values are expressed 411 * as CFDataRefs. Each OID can have associated with it an arbitrary 412 * number of values. 413 */ 414 415/* 416 * Create/destroy. 417 */ 418OSStatus SecPkcs12AttrsCreate( 419 SecPkcs12AttrsRef *attrs); // RETURNED 420 421OSStatus SecPkcs12AttrsRelease( 422 SecPkcs12AttrsRef attrs); 423 424/* 425 * Add an OID/value set to an existing SecPkcs12AttrsRef. 426 * Values are a CFArray containing an arbitrary number of 427 * CFDataRefs. 428 */ 429OSStatus SecPkcs12AttrsAddAttr( 430 SecPkcs12AttrsRef attrs, 431 CFDataRef attrOid, 432 CFArrayRef attrValues); // an array of CFDataRefs 433 434OSStatus SecPkcs12AttrCount( 435 SecPkcs12AttrsRef attrs, 436 CFIndex *numAttrs); // RETURNED 437 438/* 439 * Obtain n'th oid/value set from an existing SecPkcs12AttrsRef. 440 */ 441OSStatus SecPkcs12AttrsGetAttr( 442 SecPkcs12AttrsRef attrs, 443 CFIndex attrNum, 444 CFDataRef *attrOid, // RETURNED 445 CFArrayRef *attrValues); // RETURNED 446 447/*** 448 *** Integrity and Privacy Modes 449 ***/ 450 451/* 452 * PKCS12 allows for two different modes for each of {privacy, 453 * integrity}. Each of these can be implemented via password 454 * or public key. Per the PKCS12 spec, all four combinations 455 * of these modes are legal. In the current version of this 456 * library, only password privacy and integrity modes are 457 * implemented. These functions are defined here for the 458 * completeness of the API and need never be called by users of 459 * the current implementation. 460 */ 461typedef enum { 462 kSecPkcs12ModeUnknown, // uninitialized 463 kSecPkcs12ModePassword, 464 kSecPkcs12ModePublicKey 465} SecPkcs12Mode; 466 467OSStatus SecPkcs12SetIntegrityMode( 468 SecPkcs12CoderRef coder, 469 SecPkcs12Mode mode); 470 471OSStatus SecPkcs12GetIntegrityMode( 472 SecPkcs12CoderRef coder, 473 SecPkcs12Mode *mode); // RETURNED 474 475OSStatus SecPkcs12SetPrivacyMode( 476 SecPkcs12CoderRef coder, 477 SecPkcs12Mode mode); 478 479OSStatus SecPkcs12GetPrivacyMode( 480 SecPkcs12CoderRef coder, 481 SecPkcs12Mode *mode); // RETURNED 482 483/*** 484 *** Encryption algorithms 485 ***/ 486 487/* 488 * Each individual component of a PKCS12 PFX can be encrypted with 489 * a different encryption algorithm. Typically, Certs and CRLs are 490 * all encrypted with one weak algorithm, and private keys are 491 * encrypted with a stronger algorithm. 492 * 493 * The following functions allow the app to specify, during encoding, 494 * the encryption algorithms to use for the different kinds of 495 * components. These are optional; this library provides appropriate 496 * defaults for these algorithms. 497 */ 498OSStatus SecPkcs12SetKeyEncryptionAlg( 499 SecPkcs12CoderRef coder, 500 CFDataRef encryptionAlg); 501 502OSStatus SecPkcs12SetCertCrlEncryptionAlg( 503 SecPkcs12CoderRef coder, 504 CFDataRef encryptionAlg); 505 506/* 507 * Along with an encryption algorithm is an iteration count used for 508 * deriving keys. All of these are optional; reasonable defaults 509 * are provided. 510 * 511 * NOTE: salt is not visible at this API. During encoding, 512 * random values of salt are generated by this module. 513 */ 514OSStatus SecPkcs12SetKeyEncryptionIterCount( 515 SecPkcs12CoderRef coder, 516 unsigned iterCount); 517 518OSStatus SecPkcs12SetCertCrlEncryptionIterCount( 519 SecPkcs12CoderRef coder, 520 unsigned iterCount); 521 522OSStatus SecPkcs12SetMacIterCount( 523 SecPkcs12CoderRef coder, 524 unsigned iterCount); 525 526/* 527 * "Getter" versions of the above. During decryption, the values 528 * returned here refer to the *first* such element found (e.g., 529 * the encryption algorithm for the first key). 530 */ 531OSStatus SecPkcs12CopyKeyEncryptionAlg( 532 SecPkcs12CoderRef coder, 533 CFDataRef *encryptionAlg); // RETURNED 534 535OSStatus SecPkcs12CopyCertCrlEncryptionAlg( 536 SecPkcs12CoderRef coder, 537 CFDataRef *encryptionAlg); // RETURNED 538 539OSStatus SecPkcs12CopyKeyEncryptionIterCount( 540 SecPkcs12CoderRef coder, 541 unsigned *iterCount); // RETURNED 542 543OSStatus SecPkcs12CopyCertCrlEncryptionIterCount( 544 SecPkcs12CoderRef coder, 545 unsigned *iterCount); // RETURNED 546 547OSStatus SecPkcs12CopyMacIterCount( 548 SecPkcs12CoderRef coder, 549 unsigned *iterCount); // RETURNED 550 551/* 552 * Avoid importing multiple private keys. Primarily for use by 553 * SecKeychainItemImport(). Behavior depends on the foundOneKey 554 * argument, which indicates whether the current high-level import 555 * has already imported at least one key. If foundOneKey is true, 556 * SecPkcs12Decode() will return errSecMultiplePrivKeys upon 557 * the detection of *any* private keys in the incoming PFX. 558 * If foundOneKey is false, SecPkcs12Decode() will return 559 * errSecMultiplePrivKeys if more than one private key is 560 * found in the incoming PFX. 561 */ 562OSStatus SecPkcs12LimitPrivateKeyImport( 563 SecPkcs12CoderRef coder, 564 bool foundOneKey); 565 566#ifdef __cplusplus 567} 568#endif 569 570#endif /* _SEC_PKCS12_H_ */ 571 572