Keychain/SecKey.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header SecKey
  20         The functions provided in SecKey implement a particular type of SecKeychainItem which represents a key.  SecKeys might be stored in a SecKeychain, but can also be used as transient object representing keys.
  21
  22         Most SecKeychainItem* functions will work on an SecKeyRef.
  23 */
  24
  25 #ifndef _SECURITY_SECKEY_H_
  26 #define _SECURITY_SECKEY_H_
  27
  28 #include <Security/SecBase.h>
  29 #include <Security/cssmtype.h>
  30
  31
  32 #if defined(__cplusplus)
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37         @function SecKeyGetTypeID
  38         @abstract Returns the type identifier of SecKey instances.
  39         @result The CFTypeID of SecKey instances.
  40 */
  41 CFTypeID SecKeyGetTypeID(void);
  42
  43 /*!
  44         @function SecKeyCreatePair
  45         @abstract Creates an asymmetric key pair and stores it in the keychain specified by the keychain parameter.
  46         @param keychain A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
  47     @param algorithm An algorithm for the key pair.
  48     @param keySizeInBits A key size for the key pair.
  49     @param publicKeyUsage A bit mask indicating all permitted uses for the new public key. The bit mask values are defined in cssmtype.h
  50     @param publicKeyAttr A bit mask defining attribute values for the new public key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h
  51     @param publicKey A pointer to the keychain item reference of the new public key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The public key item must be of class type kSecAppleKeyItemClass.
  52     @param privateKeyUsage A bit mask indicating all permitted uses for the new private key. The bit mask values are defined in cssmtype.h
  53     @param privateKeyAttr A bit mask defining attribute values for the new private key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h
  54     @param privateKey A pointer to the keychain item reference of the new private key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The private key item must be of class type kSecAppleKeyItemClass.
  55     @param initialAccess A reference to an initial access to use for each of the keys returned.
  56         @result A result code.  See "Security Error Codes" (SecBase.h).
  57 */
  58 OSStatus SecKeyCreatePair(
  59         SecKeychainRef keychain,
  60         CSSM_ALGORITHMS algorithm,
  61         uint32 keySizeInBits,
  62         CSSM_KEYUSE publicKeyUsage,
  63         uint32 publicKeyAttr,
  64         SecKeyRef* publicKey,
  65         CSSM_KEYUSE privateKeyUsage,
  66         uint32 privateKeyAttr,
  67         SecKeyRef* privateKey,
  68         SecAccessRef initialAccess);
  69
  70 /*!
  71         @function SecKeyGetCSSMKey
  72         @abstract Returns a pointer to the CSSM_KEY for the given key item reference.
  73     @param key A keychain key item reference. The key item must be of class type kSecAppleKeyItemClass.
  74     @param cssmKey A pointer to a CSSM_KEY structure for the given key. The caller should not modify or free this data as it is owned by the library.
  75     @result A result code.  See "Security Error Codes" (SecBase.h).
  76         @discussion  The CSSM_KEY is valid until the key item reference is released.
  77 */
  78 OSStatus SecKeyGetCSSMKey(SecKeyRef key, const CSSM_KEY **cssmKey);
  79
  80
  81 #if defined(__cplusplus)
  82 }
  83 #endif
  84
  85 #endif /* !_SECURITY_SECKEY_H_ */