You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
684 lines
29 KiB
684 lines
29 KiB
9 years ago
|
/*
|
||
|
|
* Copyright (c) 2000-2011,2013-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@
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@header SecImportExport
|
||
|
|
contains import/export functionality for keys and certificates.
|
||
|
|
*/
|
||
|
|
#ifndef _SECURITY_SEC_IMPORT_EXPORT_H_
|
||
|
|
#define _SECURITY_SEC_IMPORT_EXPORT_H_
|
||
|
|
|
||
|
|
#include <Security/cssmtype.h>
|
||
|
|
#include <Security/SecAccess.h>
|
||
|
|
#include <Security/SecKeychain.h>
|
||
|
|
#include <CoreFoundation/CoreFoundation.h>
|
||
|
|
#include <stdint.h>
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
CF_ASSUME_NONNULL_BEGIN
|
||
|
|
CF_IMPLICIT_BRIDGING_ENABLED
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Supported import/export Formats
|
||
|
|
*/
|
||
|
|
typedef CF_ENUM(uint32_t, SecExternalFormat)
|
||
|
|
{
|
||
|
|
/*
|
||
|
|
* When importing: unknown format
|
||
|
|
* When exporting: default format for item
|
||
|
|
*/
|
||
|
|
kSecFormatUnknown = 0,
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Public and Private Key formats.
|
||
|
|
* Default for export is kSecFormatOpenSSL.
|
||
|
|
*/
|
||
|
|
kSecFormatOpenSSL, /* a.k.a. X509 for public keys */
|
||
|
|
kSecFormatSSH, /* OpenSSH v.1 */
|
||
|
|
kSecFormatBSAFE,
|
||
|
|
|
||
|
|
/* Symmetric Key Formats */
|
||
|
|
kSecFormatRawKey, /* raw unformatted key bits; default */
|
||
|
|
|
||
|
|
/* Formats for wrapped symmetric and private keys */
|
||
|
|
kSecFormatWrappedPKCS8,
|
||
|
|
kSecFormatWrappedOpenSSL, /* traditional openssl */
|
||
|
|
kSecFormatWrappedSSH, /* OpenSSH v.1 */
|
||
|
|
kSecFormatWrappedLSH,
|
||
|
|
|
||
|
|
/* Formats for certificates */
|
||
|
|
kSecFormatX509Cert, /* DER encoded; default */
|
||
|
|
|
||
|
|
/* Aggregate Types */
|
||
|
|
kSecFormatPEMSequence, /* sequence of certs and/or keys, implies PEM
|
||
|
|
* armour. Default format for multiple items */
|
||
|
|
kSecFormatPKCS7, /* sequence of certs */
|
||
|
|
kSecFormatPKCS12, /* set of certs and private keys */
|
||
|
|
kSecFormatNetscapeCertSequence, /* sequence of certs, form netscape-cert-sequence */
|
||
|
|
|
||
|
|
/* Added in Mac OS X 10.5 */
|
||
|
|
kSecFormatSSHv2 /* OpenSSH v.2. Note that OpenSSH v2 private keys
|
||
|
|
* are in format kSecFormatOpenSSL or
|
||
|
|
* kSecFormatWrappedOpenSSL. */
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Indication of basic item type when importing.
|
||
|
|
*/
|
||
|
|
typedef CF_ENUM(uint32_t, SecExternalItemType) {
|
||
|
|
kSecItemTypeUnknown, /* caller doesn't know what this is */
|
||
|
|
kSecItemTypePrivateKey,
|
||
|
|
kSecItemTypePublicKey,
|
||
|
|
kSecItemTypeSessionKey,
|
||
|
|
kSecItemTypeCertificate,
|
||
|
|
kSecItemTypeAggregate /* PKCS7, PKCS12, kSecFormatPEMSequence, etc. */
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Flags passed to SecKeychainItemExport() and SecKeychainItemImport().
|
||
|
|
*/
|
||
|
|
typedef CF_OPTIONS(uint32_t, SecItemImportExportFlags)
|
||
|
|
{
|
||
|
|
kSecItemPemArmour = 0x00000001, /* exported blob is PEM formatted */
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
* SecKeyRef-specific flags, specified in SecKeyImportExportParameters.flags
|
||
|
|
*/
|
||
|
|
typedef CF_OPTIONS(uint32_t, SecKeyImportExportFlags)
|
||
|
|
{
|
||
|
|
/*
|
||
|
|
* When true, prevents the importing of more than one private key
|
||
|
|
* in a given SecKeychainItemImport().
|
||
|
|
*/
|
||
|
|
kSecKeyImportOnlyOne = 0x00000001,
|
||
|
|
|
||
|
|
/*
|
||
|
|
* When true, passphrase for import/export is obtained by user prompt
|
||
|
|
* instead of by caller-supplied data (SecKeyImportExportParameters.passphrase).
|
||
|
|
* This is the preferred method for obtaining a user-supplied passphrase
|
||
|
|
* as it avoids having the cleartext passphrase appear in the app's
|
||
|
|
* address space at any time.
|
||
|
|
*/
|
||
|
|
kSecKeySecurePassphrase = 0x00000002,
|
||
|
|
|
||
|
|
/*
|
||
|
|
* When true, imported private keys will have no Access Control List
|
||
|
|
* (ACL) attached to them. In the absence of both this bit and the accessRef
|
||
|
|
* field in SecKeyImportExportParameters (see below), imported private
|
||
|
|
* keys are given a default ACL.
|
||
|
|
*/
|
||
|
|
kSecKeyNoAccessControl = 0x00000004
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Version of a SecKeyImportExportParameters.
|
||
|
|
*/
|
||
|
|
#define SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION 0
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Parameters specific to SecKeyRefs.
|
||
|
|
*/
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
/* for import and export */
|
||
|
|
uint32_t version; /* SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION */
|
||
|
|
SecKeyImportExportFlags flags; /* SecKeyImportExportFlags bits */
|
||
|
|
CFTypeRef passphrase; /* kSecFormatPKCS12, kSecFormatWrapped*
|
||
|
|
* formats only. Legal types are
|
||
|
|
* CFStringRef and CFDataRef. */
|
||
|
|
CFStringRef alertTitle; /* title of secure passphrase alert panel */
|
||
|
|
CFStringRef alertPrompt; /* prompt in secure passphrase alert panel */
|
||
|
|
|
||
|
|
/* for import only */
|
||
|
|
SecAccessRef __nullable accessRef; /* specifies the initial ACL of imported
|
||
|
|
* key(s) */
|
||
|
|
CSSM_KEYUSE keyUsage; /* CSSM_KEYUSE_DECRYPT, CSSM_KEYUSE_SIGN,
|
||
|
|
* etc. */
|
||
|
|
CSSM_KEYATTR_FLAGS keyAttributes; /* CSSM_KEYATTR_PERMANENT, etc. */
|
||
|
|
} SecKeyImportExportParameters;
|
||
|
|
|
||
|
|
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
/* for import and export */
|
||
|
|
uint32_t version; /* SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION */
|
||
|
|
SecKeyImportExportFlags flags; /* SecKeyImportExportFlags bits */
|
||
|
|
CFTypeRef passphrase; /* kSecFormatPKCS12, kSecFormatWrapped*
|
||
|
|
* formats only. Legal types are
|
||
|
|
* CFStringRef and CFDataRef. */
|
||
|
|
CFStringRef alertTitle; /* title of secure passphrase alert panel */
|
||
|
|
CFStringRef alertPrompt; /* prompt in secure passphrase alert panel */
|
||
|
|
|
||
|
|
/* for import only */
|
||
|
|
SecAccessRef __nullable accessRef; /* specifies the initial ACL of imported
|
||
|
|
* key(s) */
|
||
|
|
CFArrayRef __nullable keyUsage; /* An Array containing usage attributes from SecItem.h, e.g.
|
||
|
|
kSecAttrCanEncrypt;, kSecAttrCanDecrypt, kSecAttrCanDerive, etc.
|
||
|
|
*/
|
||
|
|
|
||
|
|
CFArrayRef __nullable keyAttributes; /* An array containing zero or more key attributes
|
||
|
|
for an imported key. Possible values (from SecItem.h):
|
||
|
|
kSecAttrIsPermanent, kSecAttrIsSensitive, kSecAttrIsExtractable
|
||
|
|
Pass NULL in this field to use default attributes:
|
||
|
|
- kSecAttrIsPermanent if a keychain is specified
|
||
|
|
- kSecAttrIsSensitive for private keys
|
||
|
|
- kSecAttrIsExtractable by default
|
||
|
|
*/
|
||
|
|
} SecItemImportExportKeyParameters;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* SecKeychainItemExport()
|
||
|
|
*
|
||
|
|
* This function takes one or more SecKeychainItemRefs and creates an
|
||
|
|
* external representation of the item(s) in the form of a CFDataRef.
|
||
|
|
* Caller specifies the format of the external representation via a
|
||
|
|
* SecExternalFormat enum. Caller may specify kSecFormatUnknown for
|
||
|
|
* the format, in which case a the default format for the item
|
||
|
|
* being exported is used (as described in the SecExternalFormat enums).
|
||
|
|
* PEM armouring is optional and is specified by the kSecItemPemArmour
|
||
|
|
* flag in importFlags.
|
||
|
|
*
|
||
|
|
* If exactly one item is to be exported, the keychainItemOrArray argument
|
||
|
|
* can be a SecKeychainItem. Otherwise this argument is a CFArrayRef
|
||
|
|
* containing a number of SecKeychainItems.
|
||
|
|
*
|
||
|
|
* The exported item(s) is (are) returned to the caller via the
|
||
|
|
* CFDataRef *exportedData argument. Caller must CFRelease the result.
|
||
|
|
*
|
||
|
|
* The following SecKeychainItems may be exported:
|
||
|
|
*
|
||
|
|
* SecCertificateRef
|
||
|
|
* SecKeyRef
|
||
|
|
* SecIdentityRef
|
||
|
|
*
|
||
|
|
*
|
||
|
|
* Key-related SecKeyImportExportParameters fields
|
||
|
|
* -----------------------------------------------
|
||
|
|
*
|
||
|
|
* When exporting SecKeyRefs in one of the wrapped formats
|
||
|
|
* (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
|
||
|
|
* kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
|
||
|
|
* either explicitly specify the passphrase field or set
|
||
|
|
* the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
|
||
|
|
*
|
||
|
|
* If kSecKeySecurePassphrase is selected, caller can optionally
|
||
|
|
* specify strings for the passphrase panel's title bar and for
|
||
|
|
* the prompt which appears in the panel via the alertTitle and
|
||
|
|
* alertPrompt fields in SecKeyImportExportParameters.
|
||
|
|
*
|
||
|
|
* If an explicit passphrase is specified, note that PKCS12
|
||
|
|
* explicitly requires that passphrases are in Unicode format;
|
||
|
|
* passing in a CFStringRef as the passphrase is the safest way
|
||
|
|
* to ensure that this requirement is met (and that the result
|
||
|
|
* will be compatible with other implementations). If a CFDataRef
|
||
|
|
* is supplied as the passphrase for a PKCS12 export operation,
|
||
|
|
* the referent data is assumed to be in UTF8 form and will be
|
||
|
|
* converted as appropriate.
|
||
|
|
*
|
||
|
|
* If no key items are being exported, the keyParams argument may be NULL.
|
||
|
|
* @discussion This API has been deprecated. Please us the SecItemExport API instead.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeychainItemExport(
|
||
|
|
CFTypeRef keychainItemOrArray,
|
||
|
|
SecExternalFormat outputFormat,
|
||
|
|
SecItemImportExportFlags flags, /* kSecItemPemArmor, etc. */
|
||
|
|
const SecKeyImportExportParameters * __nullable keyParams, /* optional */
|
||
|
|
CFDataRef * __nonnull CF_RETURNS_RETAINED exportedData) /* external representation returned here */
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* SecItemExport()
|
||
|
|
*
|
||
|
|
* This function takes one or more SecItemRefs and creates an
|
||
|
|
* external representation of the item(s) in the form of a CFDataRef.
|
||
|
|
* Caller specifies the format of the external representation via a
|
||
|
|
* SecExternalFormat enum. Caller may specify kSecFormatUnknown for
|
||
|
|
* the format, in which case a the default format for the item
|
||
|
|
* being exported is used (as described in the SecExternalFormat enums).
|
||
|
|
* PEM armouring is optional and is specified by the kSecItemPemArmour
|
||
|
|
* flag in importFlags.
|
||
|
|
*
|
||
|
|
* If exactly one item is to be exported, the keychainItemOrArray argument
|
||
|
|
* can be a SecKeychainItem. Otherwise this argument is a CFArrayRef
|
||
|
|
* containing a number of SecKeychainItems.
|
||
|
|
*
|
||
|
|
* The exported item(s) is (are) returned to the caller via the
|
||
|
|
* CFDataRef *exportedData argument. Caller must CFRelease the result.
|
||
|
|
*
|
||
|
|
* The following SecKeychainItems may be exported:
|
||
|
|
*
|
||
|
|
* SecCertificateRef
|
||
|
|
* SecKeyRef
|
||
|
|
* SecIdentityRef
|
||
|
|
*
|
||
|
|
*
|
||
|
|
* Key-related SecItemExport fields
|
||
|
|
* -----------------------------------------------
|
||
|
|
*
|
||
|
|
* When exporting SecKeyRefs in one of the wrapped formats
|
||
|
|
* (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
|
||
|
|
* kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
|
||
|
|
* either explicitly specify the passphrase field or set
|
||
|
|
* the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
|
||
|
|
*
|
||
|
|
* If kSecKeySecurePassphrase is selected, caller can optionally
|
||
|
|
* specify strings for the passphrase panel's title bar and for
|
||
|
|
* the prompt which appears in the panel via the alertTitle and
|
||
|
|
* alertPrompt fields in SecItemImportExportKeyParameters.
|
||
|
|
*
|
||
|
|
* If an explicit passphrase is specified, note that PKCS12
|
||
|
|
* explicitly requires that passphrases are in Unicode format;
|
||
|
|
* passing in a CFStringRef as the passphrase is the safest way
|
||
|
|
* to ensure that this requirement is met (and that the result
|
||
|
|
* will be compatible with other implementations). If a CFDataRef
|
||
|
|
* is supplied as the passphrase for a PKCS12 export operation,
|
||
|
|
* the referent data is assumed to be in UTF8 form and will be
|
||
|
|
* converted as appropriate.
|
||
|
|
*
|
||
|
|
* If no key items are being exported, the keyParams argument may be NULL.
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
OSStatus SecItemExport(
|
||
|
|
CFTypeRef secItemOrArray,
|
||
|
|
SecExternalFormat outputFormat,
|
||
|
|
SecItemImportExportFlags flags, /* kSecItemPemArmor, etc. */
|
||
|
|
const SecItemImportExportKeyParameters * __nullable keyParams, /* optional */
|
||
|
|
CFDataRef * __nonnull CF_RETURNS_RETAINED exportedData) /* external representation returned here */
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
/*
|
||
|
|
* SecKeychainItemImport()
|
||
|
|
*
|
||
|
|
* This function takes a CFDataRef containing the external representation
|
||
|
|
* of one or more objects and creates SecKeychainItems corresponding to
|
||
|
|
* those objects and optionally imports those SecKeychainItems into a
|
||
|
|
* specified keychain. The format of the incoming representation is
|
||
|
|
* specified by one or more of the following:
|
||
|
|
*
|
||
|
|
* -- A SecExternalFormat. This optional in/out argument is used when
|
||
|
|
* the caller knows exactly what format the external representation
|
||
|
|
* is in. It's also used to return to the caller the format which the
|
||
|
|
* function actually determines the external representation to be in.
|
||
|
|
* A value of kSecFormatUnknown is specified on entry when the caller
|
||
|
|
* wishes to know the inferred format on return.
|
||
|
|
*
|
||
|
|
* -- A SecExternalItemType - optional, in/out. Used to specify what kind
|
||
|
|
* of item is in the incoming representation, if known by the caller.
|
||
|
|
* It's also used to return to the caller the item type which the
|
||
|
|
* function actually determines the external representation to contain.
|
||
|
|
* A value of kSecItemTypeUnknown is specified on entry when the caller
|
||
|
|
* wishes to know the inferred item type on return.
|
||
|
|
*
|
||
|
|
* -- fileNameOrExtension, a CFStringRef. This optional argument contains
|
||
|
|
* the name of the file from which the external representation was
|
||
|
|
* obtained; it can also be simply an extension like CFSTR(".p7r").
|
||
|
|
* This is a convenience for apps like KeychainAccess which can import a
|
||
|
|
* number of different formats.
|
||
|
|
*
|
||
|
|
* The SecKeychainItemImport() call does its best to figure out what is
|
||
|
|
* in an incoming external item given the info provided by the above three
|
||
|
|
* arguments. In most cases, SecKeychainItemImport() can even figure out
|
||
|
|
* what's in an external item if none of these are specified, but it would
|
||
|
|
* be unwise for an application to count on that ability.
|
||
|
|
*
|
||
|
|
* PEM formatting is determined internally via inspection of the incoming
|
||
|
|
* data, so the kSecItemPemArmuor in the flags field is ignored.
|
||
|
|
*
|
||
|
|
* Zero, one, or both of the following occurs upon successful completion
|
||
|
|
* of this function:
|
||
|
|
*
|
||
|
|
* -- The imported item(s) is (are) imported to the specified importKeychain.
|
||
|
|
* If importKeychain is NULL, this step does not occur.
|
||
|
|
*
|
||
|
|
* -- The imported item(s) is (are) returned to the caller via the
|
||
|
|
* CFArrayRef *outItems argument. If outItems is NULL, this step
|
||
|
|
* does not occur. If outItems is NON-NULL, then *outItems will be
|
||
|
|
* a CFArrayRef containing a number of SecKeychainItems upon return.
|
||
|
|
* Caller must CFRelease the result.
|
||
|
|
*
|
||
|
|
* The possible types of returned SecKeychainItems are:
|
||
|
|
*
|
||
|
|
* SecCertificateRef
|
||
|
|
* SecKeyRef
|
||
|
|
* SecIdentityRef
|
||
|
|
*
|
||
|
|
* Note that when importing a PKCS12 blob, typically one SecIdentityRef
|
||
|
|
* and zero or more additional SecCertificateRefs are returned in
|
||
|
|
* outItems. No SecKeyRefs will appear there unless a key
|
||
|
|
* is found in the incoming blob with does not have a matching
|
||
|
|
* certificate.
|
||
|
|
*
|
||
|
|
* A typical case in which an app specifies the outItems
|
||
|
|
* argument and a NULL for importKeychain is when the app wishes to
|
||
|
|
* perform some user interaction, perhaps on a per-item basis, before
|
||
|
|
* committing to actually import the item(s). In this case, if the app
|
||
|
|
* does wish to proceed with the import, the standard import calls
|
||
|
|
* (SecCertificateAddToKeychain(), SecKeyAddToKeychain (implementation
|
||
|
|
* TBD)) would be used.
|
||
|
|
*
|
||
|
|
* Passing in NULL for both outItems and importKeychain
|
||
|
|
* is a perfectly acceptable way of using this function to determine,
|
||
|
|
* in a non-intrusive way, what is inside a given data blob. No effect
|
||
|
|
* other than returning inputFormat and/or itemType occurs in this
|
||
|
|
* case.
|
||
|
|
|
||
|
|
*
|
||
|
|
* Key-related SecKeyImportExportParameters fields
|
||
|
|
* -----------------------------------------------
|
||
|
|
*
|
||
|
|
* If importKeychain is NULL, the kSecKeyImportOnlyOne bit in the flags
|
||
|
|
* argument is ignored. Otherwise, if the kSecKeyImportOnlyOne bit is set, and
|
||
|
|
* there is more than one key in the incoming external representation, no
|
||
|
|
* items will be imported to the specified keychain and errSecMultipleKeys will
|
||
|
|
* be returned.
|
||
|
|
*
|
||
|
|
* The accessRef field allows the caller to specify the initial SecAccessRef
|
||
|
|
* for imported private keys. If more than one private key is being imported,
|
||
|
|
* all private keys get the same initial SecAccessRef. If this field is NULL
|
||
|
|
* when private keys are being imported, then the ACL attached to imported
|
||
|
|
* private keys depends on the kSecKeyNoAccessControl bit in the specified
|
||
|
|
* keyParams->flags. If this bit is 0, or keyParams is NULL, the default ACL
|
||
|
|
* will be used. If this bit is 1, no ACL will be attached to imported
|
||
|
|
* private keys.
|
||
|
|
*
|
||
|
|
* keyUsage and keyAttributes specify the low-level usage and attribute flags
|
||
|
|
* of imported keys. Each is a word of bits. The default value for keyUsage
|
||
|
|
* (used when keyParams is NULL or if keyParams->keyUsage is zero) is
|
||
|
|
* CSSM_KEYUSE_ANY. The default value for keyAttributes defaults is
|
||
|
|
* CSSM_KEYATTR_SENSITIVE | CSSM_KEYATTR_EXTRACTABLE; the CSSM_KEYATTR_PERMANENT
|
||
|
|
* bit is also added to the default if a non-NULL importKeychain is provided.
|
||
|
|
*
|
||
|
|
* The following are valid bits in keyAttributes:
|
||
|
|
*
|
||
|
|
* CSSM_KEYATTR_PERMANENT
|
||
|
|
* CSSM_KEYATTR_SENSITIVE
|
||
|
|
* CSSM_KEYATTR_EXTRACTABLE
|
||
|
|
*
|
||
|
|
* If the CSSM_KEYATTR_PERMANENT is set then the importKeychain argument must
|
||
|
|
* be valid or errSecInvalidKeychain will be returned if in fact any keys are found
|
||
|
|
* in the external representation.
|
||
|
|
*
|
||
|
|
* Note that if the caller does not set the CSSM_KEYATTR_EXTRACTABLE, this key
|
||
|
|
* will never be able to be extracted from the keychain in any form, not even
|
||
|
|
* in wrapped form. The CSSM_KEYATTR_SENSITIVE indicates that the key can only
|
||
|
|
* be extracted in wrapped form.
|
||
|
|
*
|
||
|
|
* The CSSM_KEYATTR_RETURN_xxx bits are always forced to
|
||
|
|
* CSSM_KEYATTR_RETURN_REF regardless of the specified keyAttributes
|
||
|
|
* field.
|
||
|
|
*
|
||
|
|
* When importing SecKeyRefs in one of the wrapped formats
|
||
|
|
* (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
|
||
|
|
* kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
|
||
|
|
* either explicitly specify the passphrase field or set
|
||
|
|
* the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
|
||
|
|
*
|
||
|
|
* If kSecKeySecurePassphrase is selected, caller can optionally
|
||
|
|
* specify strings for the passphrase panel's title bar and for
|
||
|
|
* the prompt which appears in the panel via the alertTitle and
|
||
|
|
* alertPrompt fields in SecKeyImportExportParameters.
|
||
|
|
*
|
||
|
|
* If an explicit passphrase is specified, note that PKCS12
|
||
|
|
* explicitly requires that passphrases are in Unicode format;
|
||
|
|
* passing in a CFStringRef as the passphrase is the safest way
|
||
|
|
* to ensure that this requirement is met (and that the result
|
||
|
|
* will be compatible with other implementations). If a CFDataRef
|
||
|
|
* is supplied as the passphrase for a PKCS12 export operation,
|
||
|
|
* the referent data is assumed to be in UTF8 form and will be
|
||
|
|
* converted as appropriate.
|
||
|
|
|
||
|
|
* If no key items are being imported, the keyParams argument may be NULL.
|
||
|
|
*
|
||
|
|
* The SecItemImportExportFlags argument is currently unused; caller should pass
|
||
|
|
* in 0.
|
||
|
|
*
|
||
|
|
* @discussion This API has been deprecated. Please use the SecItemImport API instead.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeychainItemImport(
|
||
|
|
CFDataRef importedData,
|
||
|
|
CFStringRef __nullable fileNameOrExtension, /* optional */
|
||
|
|
SecExternalFormat * __nullable inputFormat, /* optional, IN/OUT */
|
||
|
|
SecExternalItemType * __nullable itemType, /* optional, IN/OUT */
|
||
|
|
SecItemImportExportFlags flags,
|
||
|
|
const SecKeyImportExportParameters * __nullable keyParams, /* optional */
|
||
|
|
SecKeychainRef __nullable importKeychain, /* optional */
|
||
|
|
CFArrayRef * __nullable CF_RETURNS_RETAINED outItems) /* optional */
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* SecItemImport()
|
||
|
|
*
|
||
|
|
* This function takes a CFDataRef containing the external representation
|
||
|
|
* of one or more objects and creates SecKeychainItems corresponding to
|
||
|
|
* those objects and optionally imports those SecKeychainItems into a
|
||
|
|
* specified keychain. The format of the incoming representation is
|
||
|
|
* specified by one or more of the following:
|
||
|
|
*
|
||
|
|
* -- A SecExternalFormat. This optional in/out argument is used when
|
||
|
|
* the caller knows exactly what format the external representation
|
||
|
|
* is in. It's also used to return to the caller the format which the
|
||
|
|
* function actually determines the external representation to be in.
|
||
|
|
* A value of kSecFormatUnknown is specified on entry when the caller
|
||
|
|
* wishes to know the inferred format on return.
|
||
|
|
*
|
||
|
|
* -- A SecExternalItemType - optional, in/out. Used to specify what kind
|
||
|
|
* of item is in the incoming representation, if known by the caller.
|
||
|
|
* It's also used to return to the caller the item type which the
|
||
|
|
* function actually determines the external representation to contain.
|
||
|
|
* A value of kSecItemTypeUnknown is specified on entry when the caller
|
||
|
|
* wishes to know the inferred item type on return.
|
||
|
|
*
|
||
|
|
* -- fileNameOrExtension, a CFStringRef. This optional argument contains
|
||
|
|
* the name of the file from which the external representation was
|
||
|
|
* obtained; it can also be simply an extension like CFSTR(".p7r").
|
||
|
|
* This is a convenience for apps like KeychainAccess which can import a
|
||
|
|
* number of different formats.
|
||
|
|
*
|
||
|
|
* The SecItemImport() call does its best to figure out what is
|
||
|
|
* in an incoming external item given the info provided by the above three
|
||
|
|
* arguments. In most cases, SecItemImport() can even figure out
|
||
|
|
* what's in an external item if none of these are specified, but it would
|
||
|
|
* be unwise for an application to count on that ability.
|
||
|
|
*
|
||
|
|
* PEM formatting is determined internally via inspection of the incoming
|
||
|
|
* data, so the kSecItemPemArmuor in the flags field is ignored.
|
||
|
|
*
|
||
|
|
* Zero, one, or both of the following occurs upon successful completion
|
||
|
|
* of this function:
|
||
|
|
*
|
||
|
|
* -- The imported item(s) is (are) imported to the specified importKeychain.
|
||
|
|
* If importKeychain is NULL, this step does not occur.
|
||
|
|
*
|
||
|
|
* -- The imported item(s) is (are) returned to the caller via the
|
||
|
|
* CFArrayRef *outItems argument. If outItems is NULL, this step
|
||
|
|
* does not occur. If outItems is NON-NULL, then *outItems will be
|
||
|
|
* a CFArrayRef containing a number of SecKeychainItems upon return.
|
||
|
|
* Caller must CFRelease the result.
|
||
|
|
*
|
||
|
|
* The possible types of returned SecKeychainItems are:
|
||
|
|
*
|
||
|
|
* SecCertificateRef
|
||
|
|
* SecKeyRef
|
||
|
|
* SecIdentityRef
|
||
|
|
*
|
||
|
|
* Note that when importing a PKCS12 blob, typically one SecIdentityRef
|
||
|
|
* and zero or more additional SecCertificateRefs are returned in
|
||
|
|
* outItems. No SecKeyRefs will appear there unless a key
|
||
|
|
* is found in the incoming blob with does not have a matching
|
||
|
|
* certificate.
|
||
|
|
*
|
||
|
|
* A typical case in which an app specifies the outItems
|
||
|
|
* argument and a NULL for importKeychain is when the app wishes to
|
||
|
|
* perform some user interaction, perhaps on a per-item basis, before
|
||
|
|
* committing to actually import the item(s). In this case, if the app
|
||
|
|
* does wish to proceed with the import, the standard import calls
|
||
|
|
* (SecCertificateAddToKeychain(), SecKeyAddToKeychain (implementation
|
||
|
|
* TBD)) would be used.
|
||
|
|
*
|
||
|
|
* Passing in NULL for both outItems and importKeychain
|
||
|
|
* is a perfectly acceptable way of using this function to determine,
|
||
|
|
* in a non-intrusive way, what is inside a given data blob. No effect
|
||
|
|
* other than returning inputFormat and/or itemType occurs in this
|
||
|
|
* case.
|
||
|
|
|
||
|
|
*
|
||
|
|
* Key-related SecItemImportExportKeyParameters fields
|
||
|
|
* -----------------------------------------------
|
||
|
|
*
|
||
|
|
* If importKeychain is NULL, the kSecKeyImportOnlyOne bit in the flags
|
||
|
|
* argument is ignored. Otherwise, if the kSecKeyImportOnlyOne bit is set, and
|
||
|
|
* there is more than one key in the incoming external representation, no
|
||
|
|
* items will be imported to the specified keychain and errSecMultipleKeys will
|
||
|
|
* be returned.
|
||
|
|
*
|
||
|
|
* The accessRef field allows the caller to specify the initial SecAccessRef
|
||
|
|
* for imported private keys. If more than one private key is being imported,
|
||
|
|
* all private keys get the same initial SecAccessRef. If this field is NULL
|
||
|
|
* when private keys are being imported, then the ACL attached to imported
|
||
|
|
* private keys depends on the kSecKeyNoAccessControl bit in the specified
|
||
|
|
* keyParams->flags. If this bit is 0, or keyParams is NULL, the default ACL
|
||
|
|
* will be used. If this bit is 1, no ACL will be attached to imported
|
||
|
|
* private keys.
|
||
|
|
*
|
||
|
|
* keyUsage and keyAttributes specify the low-level usage and attribute flags
|
||
|
|
* of imported keys. These fields contain a CFArray whose values are constants
|
||
|
|
* from SecItem.h.
|
||
|
|
*
|
||
|
|
* Possible values in the keyUsage array:
|
||
|
|
*
|
||
|
|
* kSecAttrCanEncrypt
|
||
|
|
* kSecAttrCanDecrypt
|
||
|
|
* kSecAttrCanDerive
|
||
|
|
* kSecAttrCanSign
|
||
|
|
* kSecAttrCanVerify
|
||
|
|
* kSecAttrCanWrap
|
||
|
|
* kSecAttrCanUnwrap
|
||
|
|
*
|
||
|
|
* If keyUsage is set to NULL, then any key usage is permitted.
|
||
|
|
*
|
||
|
|
* Possible values in the keyAttributes array:
|
||
|
|
*
|
||
|
|
* kSecAttrIsPermanent
|
||
|
|
* kSecAttrIsSensitive
|
||
|
|
* kSecAttrIsExtractable
|
||
|
|
*
|
||
|
|
* If keyAttributes is set to NULL, then default values are used:
|
||
|
|
* kSecAttrIsPermanent if an import keychain is specified
|
||
|
|
* kSecAttrIsSensitive for non-public keys
|
||
|
|
* kSecAttrIsExtractable
|
||
|
|
*
|
||
|
|
* If the kSecAttrIsPermanent attribute is set, then the
|
||
|
|
* importKeychain argument must be valid or errSecInvalidKeychain
|
||
|
|
* will be returned even if keys were able to be imported.
|
||
|
|
*
|
||
|
|
* Note that if the caller provides a keyAttributes array but
|
||
|
|
* does not set kSecAttrIsExtractable, this key will never be
|
||
|
|
* able to be extracted from the keychain in any form, not even
|
||
|
|
* in wrapped form. kSecAttrIsSensitive indicates that the key
|
||
|
|
* can only be extracted in wrapped form.
|
||
|
|
*
|
||
|
|
* When importing SecKeyRefs in one of the wrapped formats
|
||
|
|
* (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
|
||
|
|
* kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
|
||
|
|
* either explicitly specify the passphrase field or set
|
||
|
|
* the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
|
||
|
|
*
|
||
|
|
* If kSecKeySecurePassphrase is selected, caller can optionally
|
||
|
|
* specify strings for the passphrase panel's title bar and for
|
||
|
|
* the prompt which appears in the panel via the alertTitle and
|
||
|
|
* alertPrompt fields in SecItemImportExportKeyParameters.
|
||
|
|
*
|
||
|
|
* If an explicit passphrase is specified, note that PKCS12
|
||
|
|
* explicitly requires that passphrases are in Unicode format;
|
||
|
|
* passing in a CFStringRef as the passphrase is the safest way
|
||
|
|
* to ensure that this requirement is met (and that the result
|
||
|
|
* will be compatible with other implementations). If a CFDataRef
|
||
|
|
* is supplied as the passphrase for a PKCS12 export operation,
|
||
|
|
* the referent data is assumed to be in UTF8 form and will be
|
||
|
|
* converted as appropriate.
|
||
|
|
|
||
|
|
* If no key items are being imported, the keyParams argument may be NULL.
|
||
|
|
*
|
||
|
|
* The SecItemImportExportFlags argument is currently unused; caller should pass
|
||
|
|
* in 0.
|
||
|
|
*/
|
||
|
|
|
||
|
|
OSStatus SecItemImport(
|
||
|
|
CFDataRef importedData,
|
||
|
|
CFStringRef __nullable fileNameOrExtension, /* optional */
|
||
|
|
SecExternalFormat * __nullable inputFormat, /* optional, IN/OUT */
|
||
|
|
SecExternalItemType * __nullable itemType, /* optional, IN/OUT */
|
||
|
|
SecItemImportExportFlags flags,
|
||
|
|
const SecItemImportExportKeyParameters * __nullable keyParams, /* optional */
|
||
|
|
SecKeychainRef __nullable importKeychain, /* optional */
|
||
|
|
CFArrayRef * __nullable CF_RETURNS_RETAINED outItems) /* optional */
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
/*!
|
||
|
|
@enum Import/Export options
|
||
|
|
@discussion Predefined key constants used when passing dictionary-based arguments to import/export functions.
|
||
|
|
@constant kSecImportExportPassphrase Specifies a passphrase represented by a CFStringRef to be used when exporting to (or importing from) PKCS#12 format.
|
||
|
|
@constant kSecImportExportKeychain Specifies a keychain represented by a SecKeychainRef to be used as the target when importing from PKCS#12 format.
|
||
|
|
@constant kSecImportExportAccess Specifies an access represented by a SecAccessRef for the initial access (ACL) of a key imported from PKCS#12 format.
|
||
|
|
*/
|
||
|
|
extern const CFStringRef kSecImportExportPassphrase;
|
||
|
|
extern const CFStringRef kSecImportExportKeychain;
|
||
|
|
extern const CFStringRef kSecImportExportAccess;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum Import/Export item description
|
||
|
|
@discussion Predefined key constants used by functions which return a CFArray with a CFDictionary per item.
|
||
|
|
@constant kSecImportItemLabel A CFStringRef representing the item label. This implementation specific identifier cannot be expected to have any format.
|
||
|
|
@constant kSecImportItemKeyID A CFDataRef representing the key id. Typically this is the SHA-1 digest of the public key.
|
||
|
|
@constant kSecImportItemIdentity A SecIdentityRef representing the identity.
|
||
|
|
@constant kSecImportItemTrust A SecTrustRef set up with all relevant certificates. Not guaranteed to succesfully evaluate.
|
||
|
|
@constant kSecImportItemCertChain A CFArrayRef holding all relevant certificates for this item's identity.
|
||
|
|
*/
|
||
|
|
extern const CFStringRef kSecImportItemLabel;
|
||
|
|
extern const CFStringRef kSecImportItemKeyID;
|
||
|
|
extern const CFStringRef kSecImportItemTrust;
|
||
|
|
extern const CFStringRef kSecImportItemCertChain;
|
||
|
|
extern const CFStringRef kSecImportItemIdentity;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecPKCS12Import
|
||
|
|
@abstract Imports the contents of a PKCS12 formatted blob.
|
||
|
|
@param pkcs12_data The PKCS12 data to be imported.
|
||
|
|
@param options A dictionary containing import options. A kSecImportExportPassphrase entry is required at minimum. Only password-based PKCS12 blobs are currently supported.
|
||
|
|
@param items On return, an array containing a dictionary for every item extracted. Use kSecImportItem constants to access specific elements of these dictionaries. Your code must CFRelease the array when it is no longer needed.
|
||
|
|
@result errSecSuccess in case of success. errSecDecode means either the blob can't be read or it is malformed.
|
||
|
|
errSecAuthFailed means an incorrect password was supplied, or data in the container is damaged.
|
||
|
|
*/
|
||
|
|
OSStatus SecPKCS12Import(CFDataRef pkcs12_data, CFDictionaryRef options, CFArrayRef * __nonnull CF_RETURNS_RETAINED items);
|
||
|
|
|
||
|
|
CF_IMPLICIT_BRIDGING_DISABLED
|
||
|
|
CF_ASSUME_NONNULL_END
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* _SECURITY_SEC_IMPORT_EXPORT_H_ */
|