--- /dev/null
+/*
+ * Copyright (c) 2003-2004,2011,2014 Apple Inc. All Rights Reserved.
+ *
+ * @APPLE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_LICENSE_HEADER_END@
+ */
+
+/*******************************************************************
+ *
+ * SecPkcs12.h
+ *
+ * This module is an implementation of the logic required to create
+ * and parse PKCS12 "blobs", known as PFXs in PKCS12 lingo. The user
+ * of this module need not know anything about the details of
+ * PKCS12 PFX construction. All one needs to know at this level
+ * is that a PKCS12 PFX is a collection of the following items:
+ *
+ * -- Zero or more certificates
+ * -- Zero or more Certficate Revocation Lists (CRLs)
+ * -- Zero or more private keys. (If this number is zero, using this
+ * module is probably not what you want to do)
+ * -- Zero or more other opaque types, not understood or parsed
+ * by this module.
+ *
+ * Each individual component of a PFX contains zero or more
+ * attributes; commonly the only two such attributes used in
+ * the PKCS12 world are "FriendlyName", a Unicode string, and
+ * "LocalKeyId", an opaque data blob which serves solely to tie
+ * a specific cert to a specific key in the context of this specific
+ * PFX.
+ *
+ * Individual components of a PKCS12 PFX are typically encrypted with
+ * a key derived from a user-supplied passphrase. The entire PFX
+ * is protected with a MAC whose key is also derived from a user-
+ * supplied passphrase. Typically these two passphrases are identical
+ * but they don't have to be.
+ *
+ * There are a number of options and modes which, while described in
+ * the PKCS12 spec and provided for in the interface in this file,
+ * are rarely if ever used. The following is a description of the
+ * actual, typical, real-world use of this module.
+ *
+ * Decoding a PKCS12 blob
+ * ----------------------
+ *
+ * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate().
+ *
+ * 2. App specifies supplies a (small) number of options such as
+ * passphrase(s) and SecKeychainRefs.
+ *
+ * 3. App calls SecPkcs12Decode(), providing the raw PKCS12 PFX
+ * blob which is to be decoded. This performs all of the actual
+ * decoding and decryption.
+ *
+ * 4. At this point the app optionally obtains the resulting
+ * components by a set of calls which return individual
+ * certs, CRLS, and keys.
+ *
+ * 5. Also, per the configuration performed in step 2, individual
+ * components (certs, keys) found in the PFX have been added
+ * to a specified keychain, rendering step 4 superfluous.
+ *
+ *
+ * Creating a PKCS12 blob
+ * ----------------------
+ *
+ * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate().
+ *
+ * 2. App specifies supplies a (small) number of options such as
+ * passphrase(s).
+ *
+ * 3. App makes a set of calls which add individual components such
+ * as certs, CRLs, and private keys. A high-level call,
+ * SecPkcs12ExportKeychainItems(), allow the specification of
+ * all components to be exported at once.
+ *
+ * 4. App calls SecPkcs12Encode(), which does all of the required
+ * encryption and encoding. The result is an exportable PKCS12
+ * PFX blob.
+ */
+
+#ifndef _SEC_PKCS12_H_
+#define _SEC_PKCS12_H_
+
+#include <CoreFoundation/CoreFoundation.h>
+#include <Security/Security.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Opaque handle for a PKCS12 encoder/decoder.
+ */
+typedef void *SecPkcs12CoderRef;
+
+#pragma mark --- SecPkcs12CoderRef create/destroy ---
+
+/*
+ * Basic SecPkcs12CoderRef create/destroy.
+ */
+OSStatus SecPkcs12CoderCreate(
+ SecPkcs12CoderRef *coder); // RETURNED
+
+/*
+ * Destroy object created in SecPkcs12CoderCreate.
+ */
+OSStatus SecPkcs12CoderRelease(
+ SecPkcs12CoderRef coder);
+
+#pragma mark --- High-level API ---
+
+/*
+ * Keychain associated with encode/decode.
+ * Client must call exactly one of { SecPkcs12SetKeychain(),
+ * SecPkcs12SetCspHandle() } for both encoding and decoding.
+ * If SecPkcs12SetCspHandle() is used, components which are
+ * obtained during decode are ephemeral (i.e., they are not
+ * stored anywhere and only have a lifetime which is the same as
+ * the lifetime of the SecPkcs12CoderRef).
+ */
+OSStatus SecPkcs12SetKeychain(
+ SecPkcs12CoderRef coder,
+ SecKeychainRef keychain);
+
+/*
+ * Required iff SecPkcs12SetKeychain() is not called.
+ */
+OSStatus SecPkcs12SetCspHandle(
+ SecPkcs12CoderRef coder,
+ CSSM_CSP_HANDLE cspHandle);
+
+
+/*
+ * PKCS12 allows for separate passphrases for encryption and for
+ * verification (via MAC). Typically, in the real world, one
+ * passphrase is used for both; we provide the means to set them
+ * separately.
+ *
+ * Passphrases can be specified directly as CFStringRefs, or as
+ * CSSM_KEYs which represent secure passphrases obtained by the
+ * SecurityServer. This latter method is preferred since the
+ * plaintext passphrase never appears in the app's address space.
+ * Passphrases expressed in this manner are referred to as
+ * PassKeys.
+ *
+ * If one passphrase is to be used for both encryption and
+ * verification, use one of these two function to set it.
+ */
+OSStatus SecPkcs12SetMACPassphrase(
+ SecPkcs12CoderRef coder,
+ CFStringRef passphrase);
+
+OSStatus SecPkcs12SetMACPassKey(
+ SecPkcs12CoderRef coder,
+ const CSSM_KEY *passKey);
+
+/*
+ * Specify separate passphrase for encrypt/decrypt.
+ */
+OSStatus SecPkcs12SetCryptPassphrase(
+ SecPkcs12CoderRef coder,
+ CFStringRef passphrase);
+
+OSStatus SecPkcs12SetCryptPassKey(
+ SecPkcs12CoderRef coder,
+ const CSSM_KEY *passKey);
+
+/*
+ * Prior to decoding a PFX, client can specify whether individual
+ * components (certificates, CRLs, and keys) get stored in the
+ * keychain specified via SecPkcs12SetKeychain().
+ */
+enum {
+ kSecImportCertificates = 0x0001,
+ kSecImportCRLs = 0x0002,
+ kSecImportKeys = 0x0004,
+};
+
+typedef UInt32 SecPkcs12ImportFlags;
+
+OSStatus SecPkcs12SetImportToKeychain(
+ SecPkcs12CoderRef coder,
+ SecPkcs12ImportFlags flags);
+
+OSStatus SecPkcs12GetImportToKeychain(
+ SecPkcs12CoderRef coder,
+ SecPkcs12ImportFlags *flags); // RETURNED
+
+/*
+ * Specify individual SecKeychainItemRef to export, prior to encoding.
+ * The items argument is a CFArray containing any number of each
+ * of the following SecKeychainItemRef objects:
+ *
+ * SecKeyRef
+ * SecCertificateRef
+ * ...and others, in the future.
+ */
+OSStatus SecPkcs12ExportKeychainItems(
+ SecPkcs12CoderRef coder,
+ CFArrayRef items);
+
+/*
+ * Specify additional optional imported private key attributes:
+ * -- a SecAccessRef; default is the default ACL. Passing NULL here
+ * results in private keys being created with no ACL.
+ * -- CSSM_KEYUSE; default is CSSM_KEYUSE_ANY.
+ * -- CSSM_KEYATTR_FLAGS; default is CSSM_KEYATTR_RETURN_REF |
+ * CSSM_KEYATTR_EXTRACTABLE | CSSM_KEYATTR_SENSITIVE, plus
+ * CSSM_KEYATTR_PERMANENT if importing to a keychain
+ */
+OSStatus SecPkcs12SetAccess(
+ SecPkcs12CoderRef coder,
+ SecAccessRef access);
+
+OSStatus SecPkcs12SetKeyUsage(
+ SecPkcs12CoderRef coder,
+ CSSM_KEYUSE keyUsage);
+
+OSStatus SecPkcs12SetKeyAttrs(
+ SecPkcs12CoderRef coder,
+ CSSM_KEYATTR_FLAGS keyAttrs);
+
+/*
+ * Parse and decode.
+ */
+OSStatus SecPkcs12Decode(
+ SecPkcs12CoderRef coder,
+ CFDataRef pfx);
+
+/*
+ * This the final step to create an encoded PKCS12 PFX blob.
+ * This called after initial configuration of the SecPkcs12CoderRef,
+ * and either specifying items to export via either
+ * SecPkcs12ExportKeychainItems() or some number of SecPkcs12Add*
+ * function calls, described below.
+ *
+ * The result is a DER-encoded PFX in PKCS12 lingo.
+ */
+OSStatus SecPkcs12Encode(
+ SecPkcs12CoderRef coder,
+ CFDataRef *pfx); // RETURNED
+
+
+/*
+ * Opaque handle for optional attributes associated with any
+ * component of a SecPkcs12CoderRef.
+ *
+ * The use of SecPkcs12AttrsRefs is optional and in fact, in the real
+ * world, rare. Their appearance in this API is just for completeness
+ * and to allow access to all "legal" PKCS12 options.
+ *
+ * We define the type here to allow use elsewhere in this
+ * interface; actual SecPkcs12AttrsRef manipulation functions
+ * are described later in this header.
+ */
+typedef void *SecPkcs12AttrsRef;
+
+#pragma mark --- Decoder Functions ---
+
+/*
+ * Subsequent to decoding, obtain the components.
+ * These functions can also be used as "getter" functions while encoding.
+ *
+ * Certificates:
+ */
+OSStatus SecPkcs12CertificateCount(
+ SecPkcs12CoderRef coder,
+ CFIndex *numCerts); // RETURNED
+
+OSStatus SecPkcs12CopyCertificate(
+ SecPkcs12CoderRef coder,
+ CFIndex certNum,
+ SecCertificateRef *cert, // RETURNED
+ CFStringRef *friendlyName, // optional, RETURNED
+ CFDataRef *localKeyId, // optional, RETURNED
+ SecPkcs12AttrsRef *attrs); // optional, RETURNED
+
+/*
+ * CRLs. The might change if a SecCrl type is defined elsewhere.
+ * We'll typedef it here to preserve the semantics of this function.
+ */
+typedef CFDataRef SecCrlRef;
+
+OSStatus SecPkcs12CrlCount(
+ SecPkcs12CoderRef coder,
+ CFIndex *numCrls); // RETURNED
+
+OSStatus SecPkcs12CopyCrl(
+ SecPkcs12CoderRef coder,
+ CFIndex crlNum,
+ SecCrlRef *crl, // RETURNED
+ CFStringRef *friendlyName, // optional, RETURNED
+ CFDataRef *localKeyId, // optional, RETURNED
+ SecPkcs12AttrsRef *attrs); // optional, RETURNED
+
+/*
+ * Private keys.
+ */
+OSStatus SecPkcs12PrivateKeyCount(
+ SecPkcs12CoderRef coder,
+ CFIndex *numKeys); // RETURNED
+
+/* currently not implemented : use SecPkcs12GetCssmPrivateKey() */
+OSStatus SecPkcs12CopyPrivateKey(
+ SecPkcs12CoderRef coder,
+ CFIndex keyNum,
+ SecKeyRef *privateKey, // RETURNED
+ CFStringRef *friendlyName, // optional, RETURNED
+ CFDataRef *localKeyId, // optional, RETURNED
+ SecPkcs12AttrsRef *attrs); // optional, RETURNED
+
+/*
+ * The CSSM_KEY_PTR returned by this function has a lifetime
+ * which is the same as the SecPkcs12CoderRef which created it.
+ */
+OSStatus SecPkcs12GetCssmPrivateKey(
+ SecPkcs12CoderRef coder,
+ CFIndex keyNum,
+ CSSM_KEY_PTR *privateKey, // RETURNED
+ CFStringRef *friendlyName, // optional, RETURNED
+ CFDataRef *localKeyId, // optional, RETURNED
+ SecPkcs12AttrsRef *attrs); // optional, RETURNED
+
+/*
+ * Catch-all for other components not currently understood
+ * or supported by this library. An "opaque blob" component
+ * is identified by an OID and is obtained as an opaque data
+ * blob.
+ */
+OSStatus SecPkcs12OpaqueBlobCount(
+ SecPkcs12CoderRef coder,
+ CFIndex *numBlobs); // RETURNED
+
+OSStatus SecPkcs12CopyOpaqueBlob(
+ SecPkcs12CoderRef coder,
+ CFIndex blobNum,
+ CFDataRef *blobOid, // RETURNED
+ CFDataRef *opaqueBlob, // RETURNED
+ CFStringRef *friendlyName, // optional, RETURNED
+ CFDataRef *localKeyId, // optional, RETURNED
+ SecPkcs12AttrsRef *attrs); // optional, RETURNED
+
+#pragma mark --- Encoder Functions ---
+
+/*
+ * Add individual components. "Getter" functions are available
+ * as described above (under "Functions used for decoding").
+ */
+OSStatus SecPkcs12AddCertificate(
+ SecPkcs12CoderRef coder,
+ SecCertificateRef cert,
+ CFStringRef friendlyName, // optional
+ CFDataRef localKeyId, // optional
+ SecPkcs12AttrsRef attrs); // optional
+
+OSStatus SecPkcs12AddCrl(
+ SecPkcs12CoderRef coder,
+ SecCrlRef crl,
+ CFStringRef friendlyName, // optional
+ CFDataRef localKeyId, // optional
+ SecPkcs12AttrsRef attrs); // optional
+
+OSStatus SecPkcs12AddPrivateKey(
+ SecPkcs12CoderRef coder,
+ SecKeyRef privateKey,
+ CFStringRef friendlyName, // optional
+ CFDataRef localKeyId, // optional
+ SecPkcs12AttrsRef attrs); // optional
+
+OSStatus SecPkcs12AddOpaqueBlob(
+ SecPkcs12CoderRef coder,
+ CFDataRef blobOid,
+ CFDataRef opaqueBlob,
+ CFStringRef friendlyName, // optional
+ CFDataRef localKeyId, // optional
+ SecPkcs12AttrsRef attrs); // optional
+
+
+#pragma mark --- Optional Functions ---
+
+/************************************************************
+ *** Optional, rarely used SecPkcs12CoderRef manipulation ***
+ ************************************************************/
+
+/***
+ *** SecPkcs12AttrsRef manipulation. Optional and in fact expected to
+ *** be rarely used, if ever.
+ ***/
+
+/*
+ * A SecPkcs12AttrsRef is an opaque handle referring to an aribtrary
+ * collection of OID/value pairs which can be attached to any
+ * component of a SecPkcs12CoderRef. OIDs and values are expressed
+ * as CFDataRefs. Each OID can have associated with it an arbitrary
+ * number of values.
+ */
+
+/*
+ * Create/destroy.
+ */
+OSStatus SecPkcs12AttrsCreate(
+ SecPkcs12AttrsRef *attrs); // RETURNED
+
+OSStatus SecPkcs12AttrsRelease(
+ SecPkcs12AttrsRef attrs);
+
+/*
+ * Add an OID/value set to an existing SecPkcs12AttrsRef.
+ * Values are a CFArray containing an arbitrary number of
+ * CFDataRefs.
+ */
+OSStatus SecPkcs12AttrsAddAttr(
+ SecPkcs12AttrsRef attrs,
+ CFDataRef attrOid,
+ CFArrayRef attrValues); // an array of CFDataRefs
+
+OSStatus SecPkcs12AttrCount(
+ SecPkcs12AttrsRef attrs,
+ CFIndex *numAttrs); // RETURNED
+
+/*
+ * Obtain n'th oid/value set from an existing SecPkcs12AttrsRef.
+ */
+OSStatus SecPkcs12AttrsGetAttr(
+ SecPkcs12AttrsRef attrs,
+ CFIndex attrNum,
+ CFDataRef *attrOid, // RETURNED
+ CFArrayRef *attrValues); // RETURNED
+
+/***
+ *** Integrity and Privacy Modes
+ ***/
+
+/*
+ * PKCS12 allows for two different modes for each of {privacy,
+ * integrity}. Each of these can be implemented via password
+ * or public key. Per the PKCS12 spec, all four combinations
+ * of these modes are legal. In the current version of this
+ * library, only password privacy and integrity modes are
+ * implemented. These functions are defined here for the
+ * completeness of the API and need never be called by users of
+ * the current implementation.
+ */
+typedef enum {
+ kSecPkcs12ModeUnknown, // uninitialized
+ kSecPkcs12ModePassword,
+ kSecPkcs12ModePublicKey
+} SecPkcs12Mode;
+
+OSStatus SecPkcs12SetIntegrityMode(
+ SecPkcs12CoderRef coder,
+ SecPkcs12Mode mode);
+
+OSStatus SecPkcs12GetIntegrityMode(
+ SecPkcs12CoderRef coder,
+ SecPkcs12Mode *mode); // RETURNED
+
+OSStatus SecPkcs12SetPrivacyMode(
+ SecPkcs12CoderRef coder,
+ SecPkcs12Mode mode);
+
+OSStatus SecPkcs12GetPrivacyMode(
+ SecPkcs12CoderRef coder,
+ SecPkcs12Mode *mode); // RETURNED
+
+/***
+ *** Encryption algorithms
+ ***/
+
+/*
+ * Each individual component of a PKCS12 PFX can be encrypted with
+ * a different encryption algorithm. Typically, Certs and CRLs are
+ * all encrypted with one weak algorithm, and private keys are
+ * encrypted with a stronger algorithm.
+ *
+ * The following functions allow the app to specify, during encoding,
+ * the encryption algorithms to use for the different kinds of
+ * components. These are optional; this library provides appropriate
+ * defaults for these algorithms.
+ */
+OSStatus SecPkcs12SetKeyEncryptionAlg(
+ SecPkcs12CoderRef coder,
+ CFDataRef encryptionAlg);
+
+OSStatus SecPkcs12SetCertCrlEncryptionAlg(
+ SecPkcs12CoderRef coder,
+ CFDataRef encryptionAlg);
+
+/*
+ * Along with an encryption algorithm is an iteration count used for
+ * deriving keys. All of these are optional; reasonable defaults
+ * are provided.
+ *
+ * NOTE: salt is not visible at this API. During encoding,
+ * random values of salt are generated by this module.
+ */
+OSStatus SecPkcs12SetKeyEncryptionIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned iterCount);
+
+OSStatus SecPkcs12SetCertCrlEncryptionIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned iterCount);
+
+OSStatus SecPkcs12SetMacIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned iterCount);
+
+/*
+ * "Getter" versions of the above. During decryption, the values
+ * returned here refer to the *first* such element found (e.g.,
+ * the encryption algorithm for the first key).
+ */
+OSStatus SecPkcs12CopyKeyEncryptionAlg(
+ SecPkcs12CoderRef coder,
+ CFDataRef *encryptionAlg); // RETURNED
+
+OSStatus SecPkcs12CopyCertCrlEncryptionAlg(
+ SecPkcs12CoderRef coder,
+ CFDataRef *encryptionAlg); // RETURNED
+
+OSStatus SecPkcs12CopyKeyEncryptionIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned *iterCount); // RETURNED
+
+OSStatus SecPkcs12CopyCertCrlEncryptionIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned *iterCount); // RETURNED
+
+OSStatus SecPkcs12CopyMacIterCount(
+ SecPkcs12CoderRef coder,
+ unsigned *iterCount); // RETURNED
+
+/*
+ * Avoid importing multiple private keys. Primarily for use by
+ * SecKeychainItemImport(). Behavior depends on the foundOneKey
+ * argument, which indicates whether the current high-level import
+ * has already imported at least one key. If foundOneKey is true,
+ * SecPkcs12Decode() will return errSecMultiplePrivKeys upon
+ * the detection of *any* private keys in the incoming PFX.
+ * If foundOneKey is false, SecPkcs12Decode() will return
+ * errSecMultiplePrivKeys if more than one private key is
+ * found in the incoming PFX.
+ */
+OSStatus SecPkcs12LimitPrivateKeyImport(
+ SecPkcs12CoderRef coder,
+ bool foundOneKey);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _SEC_PKCS12_H_ */
+
projects / apple / security.git / blobdiff