OSX/libsecurity_pkcs12/lib/SecPkcs12.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 /*******************************************************************
  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
 105 extern "C" {
 106 #endif
 107
 108 /*
 109  * Opaque handle for a PKCS12 encoder/decoder.
 110  */
 111 typedef void    *SecPkcs12CoderRef;
 112
 113 #pragma mark --- SecPkcs12CoderRef create/destroy ---
 114
 115 /*
 116  * Basic SecPkcs12CoderRef create/destroy.
 117  */
 118 OSStatus SecPkcs12CoderCreate(
 119         SecPkcs12CoderRef       *coder);                // RETURNED
 120
 121 /*
 122  * Destroy object created in SecPkcs12CoderCreate.
 123  */
 124 OSStatus 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  */
 138 OSStatus SecPkcs12SetKeychain(
 139         SecPkcs12CoderRef               coder,
 140         SecKeychainRef                  keychain);
 141
 142 /*
 143  * Required iff SecPkcs12SetKeychain() is not called.
 144  */
 145 OSStatus 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  */
 166 OSStatus SecPkcs12SetMACPassphrase(
 167         SecPkcs12CoderRef       coder,
 168         CFStringRef                     passphrase);
 169
 170 OSStatus SecPkcs12SetMACPassKey(
 171         SecPkcs12CoderRef       coder,
 172         const CSSM_KEY          *passKey);
 173
 174 /*
 175  * Specify separate passphrase for encrypt/decrypt.
 176  */
 177 OSStatus SecPkcs12SetCryptPassphrase(
 178         SecPkcs12CoderRef       coder,
 179         CFStringRef                     passphrase);
 180
 181 OSStatus 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  */
 190 enum {
 191         kSecImportCertificates  = 0x0001,
 192         kSecImportCRLs                  = 0x0002,
 193         kSecImportKeys                  = 0x0004,
 194 };
 195
 196 typedef UInt32 SecPkcs12ImportFlags;
 197
 198 OSStatus SecPkcs12SetImportToKeychain(
 199         SecPkcs12CoderRef                       coder,
 200         SecPkcs12ImportFlags            flags);
 201
 202 OSStatus 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  */
 215 OSStatus 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  */
 228 OSStatus SecPkcs12SetAccess(
 229         SecPkcs12CoderRef               coder,
 230         SecAccessRef                    access);
 231
 232 OSStatus SecPkcs12SetKeyUsage(
 233         SecPkcs12CoderRef               coder,
 234         CSSM_KEYUSE                             keyUsage);
 235
 236 OSStatus SecPkcs12SetKeyAttrs(
 237         SecPkcs12CoderRef               coder,
 238         CSSM_KEYATTR_FLAGS              keyAttrs);
 239
 240 /*
 241  * Parse and decode.
 242  */
 243 OSStatus 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  */
 256 OSStatus 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  */
 273 typedef 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  */
 283 OSStatus SecPkcs12CertificateCount(
 284         SecPkcs12CoderRef               coder,
 285         CFIndex                                 *numCerts);             // RETURNED
 286
 287 OSStatus 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  */
 299 typedef CFDataRef       SecCrlRef;
 300
 301 OSStatus SecPkcs12CrlCount(
 302         SecPkcs12CoderRef               coder,
 303         CFIndex                                 *numCrls);              // RETURNED
 304
 305 OSStatus 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  */
 316 OSStatus SecPkcs12PrivateKeyCount(
 317         SecPkcs12CoderRef               coder,
 318         CFIndex                                 *numKeys);              // RETURNED
 319
 320 /* currently not implemented : use SecPkcs12GetCssmPrivateKey() */
 321 OSStatus 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  */
 333 OSStatus 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  */
 347 OSStatus SecPkcs12OpaqueBlobCount(
 348         SecPkcs12CoderRef               coder,
 349         CFIndex                                 *numBlobs);             // RETURNED
 350
 351 OSStatus 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  */
 366 OSStatus SecPkcs12AddCertificate(
 367         SecPkcs12CoderRef               coder,
 368         SecCertificateRef               cert,
 369         CFStringRef                             friendlyName,   // optional
 370         CFDataRef                               localKeyId,             // optional
 371         SecPkcs12AttrsRef               attrs);                 // optional
 372
 373 OSStatus SecPkcs12AddCrl(
 374         SecPkcs12CoderRef               coder,
 375         SecCrlRef                               crl,
 376         CFStringRef                             friendlyName,   // optional
 377         CFDataRef                               localKeyId,             // optional
 378         SecPkcs12AttrsRef               attrs);                 // optional
 379
 380 OSStatus SecPkcs12AddPrivateKey(
 381         SecPkcs12CoderRef               coder,
 382         SecKeyRef                               privateKey,
 383         CFStringRef                             friendlyName,   // optional
 384         CFDataRef                               localKeyId,             // optional
 385         SecPkcs12AttrsRef               attrs);                 // optional
 386
 387 OSStatus 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  */
 418 OSStatus SecPkcs12AttrsCreate(
 419         SecPkcs12AttrsRef       *attrs);                // RETURNED
 420
 421 OSStatus 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  */
 429 OSStatus SecPkcs12AttrsAddAttr(
 430         SecPkcs12AttrsRef       attrs,
 431         CFDataRef                       attrOid,
 432         CFArrayRef                      attrValues);    // an array of CFDataRefs
 433
 434 OSStatus SecPkcs12AttrCount(
 435         SecPkcs12AttrsRef       attrs,
 436         CFIndex                         *numAttrs);             // RETURNED
 437
 438 /*
 439  * Obtain n'th oid/value set from an existing SecPkcs12AttrsRef.
 440  */
 441 OSStatus 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  */
 461 typedef enum {
 462         kSecPkcs12ModeUnknown,          // uninitialized
 463         kSecPkcs12ModePassword,
 464         kSecPkcs12ModePublicKey
 465 } SecPkcs12Mode;
 466
 467 OSStatus SecPkcs12SetIntegrityMode(
 468         SecPkcs12CoderRef       coder,
 469         SecPkcs12Mode           mode);
 470
 471 OSStatus SecPkcs12GetIntegrityMode(
 472         SecPkcs12CoderRef       coder,
 473         SecPkcs12Mode           *mode);                 // RETURNED
 474
 475 OSStatus SecPkcs12SetPrivacyMode(
 476         SecPkcs12CoderRef       coder,
 477         SecPkcs12Mode           mode);
 478
 479 OSStatus 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  */
 498 OSStatus SecPkcs12SetKeyEncryptionAlg(
 499         SecPkcs12CoderRef       coder,
 500         CFDataRef                       encryptionAlg);
 501
 502 OSStatus 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  */
 514 OSStatus SecPkcs12SetKeyEncryptionIterCount(
 515         SecPkcs12CoderRef       coder,
 516         unsigned                        iterCount);
 517
 518 OSStatus SecPkcs12SetCertCrlEncryptionIterCount(
 519         SecPkcs12CoderRef       coder,
 520         unsigned                        iterCount);
 521
 522 OSStatus 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  */
 531 OSStatus SecPkcs12CopyKeyEncryptionAlg(
 532         SecPkcs12CoderRef       coder,
 533         CFDataRef                       *encryptionAlg);                // RETURNED
 534
 535 OSStatus SecPkcs12CopyCertCrlEncryptionAlg(
 536         SecPkcs12CoderRef       coder,
 537         CFDataRef                       *encryptionAlg);                // RETURNED
 538
 539 OSStatus SecPkcs12CopyKeyEncryptionIterCount(
 540         SecPkcs12CoderRef       coder,
 541         unsigned                        *iterCount);                    // RETURNED
 542
 543 OSStatus SecPkcs12CopyCertCrlEncryptionIterCount(
 544         SecPkcs12CoderRef       coder,
 545         unsigned                        *iterCount);                    // RETURNED
 546
 547 OSStatus 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  */
 562 OSStatus SecPkcs12LimitPrivateKeyImport(
 563         SecPkcs12CoderRef       coder,
 564         bool                            foundOneKey);
 565
 566 #ifdef __cplusplus
 567 }
 568 #endif
 569
 570 #endif  /* _SEC_PKCS12_H_ */
 571