Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

SecImportExport.h

/*
 * 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      __cplusplus
extern "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,    
      kSecFormatBSAFE,  

      /* Symmetric Key Formats */
      kSecFormatRawKey,                   /* raw unformatted key bits; default */

      /* Formats for wrapped symmetric and private keys */
      kSecFormatWrappedPKCS8,
      kSecFormatWrappedOpenSSL,           /* traditional openssl */
      kSecFormatWrappedSSH,
      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 */
};
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.
 */
#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                  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 if keyParams->jeyUsage 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_ */

Generated by  Doxygen 1.6.0   Back to index