/*
* Copyright (c) 2000-2004 Apple Computer, 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@
*//*
* SecImportExport.h - high-level facilities for importing and exporting
* Sec layer objects.
*/
#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__cplusplusextern"C" {
#endif/*
* Supported import/export Formats
*/enum
{
/*
* 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. */
};
typedef uint32_t SecExternalFormat;
/*
* Indication of basic item type when importing.
*/enum {
kSecItemTypeUnknown, /* caller doesn't know what this is */
kSecItemTypePrivateKey,
kSecItemTypePublicKey,
kSecItemTypeSessionKey,
kSecItemTypeCertificate,
kSecItemTypeAggregate /* PKCS7, PKCS12, kSecFormatPEMSequence, etc. */
};
typedef uint32_t SecExternalItemType;
/*
* Flags passed to SecKeychainItemExport() and SecKeychainItemImport().
*/enum
{
kSecItemPemArmour = 0x00000001, /* exported blob is PEM formatted */
};
typedef uint32_t SecItemImportExportFlags;
/*
* SecKeyRef-specific flags, specified in SecKeyImportExportParameters.flags
*/enum
{
/*
* 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
};
typedef uint32_t SecKeyImportExportFlags;
/*
* Version of a SecKeyImportExportParameters.
*/
#defineSEC_KEY_IMPORT_EXPORT_PARAMS_VERSION 0
/*
* Parameters specific to SecKeyRefs.
*/typedefstruct
{
/* 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 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;
/*
* 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 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.
*/
OSStatus SecKeychainItemExport(
CFTypeRef keychainItemOrArray,
SecExternalFormat outputFormat,
SecItemImportExportFlags flags, /* kSecItemPemArmor, etc. */const SecKeyImportExportParameters *keyParams, /* optional */
CFDataRef *exportedData); /* external representation
* returned here *//*
* 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
* CRArrayRef *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.
*/
OSStatus SecKeychainItemImport(
CFDataRef importedData,
CFStringRef fileNameOrExtension, /* optional */
SecExternalFormat *inputFormat, /* optional, IN/OUT */
SecExternalItemType *itemType, /* optional, IN/OUT */
SecItemImportExportFlags flags,
const SecKeyImportExportParameters *keyParams, /* optional */
SecKeychainRef importKeychain, /* optional */
CFArrayRef *outItems); /* optional */
#ifdef__cplusplus
}
#endif
#endif/* _SECURITY_SEC_IMPORT_EXPORT_H_ */