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 keychainRef 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.  This parameter is ignored if contextHandle is non 0.
  48     @param keySizeInBits A key size for the key pair.  This parameter is ignored if contextHandle is non 0.
  49         @param contextHandle An optional CSSM_CC_HANDLE or 0.  If this argument is not 0 the algorithm and keySizeInBits parameters are ignored.  If extra parameters are need to generate a key (some algortihms require this) you should create a context using CSSM_CSP_CreateKeyGenContext(), using the CSPHandle obtained by calling SecKeychainGetCSPHandle(). Then use CSSM_UpdateContextAttributes() to add additional parameters and dispose of the context using CSSM_DeleteContext after calling this function.
  50         @param publicKeyUsage A bit mask indicating all permitted uses for the new public key. The bit mask values are defined in cssmtype.h
  51     @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
  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 initialAccess A SecAccess object that determines the initial access rights to the private key.  The public key is given an any/any acl by default.
  55     @param publicKey Optional output pointer to the keychain item reference of the imported public key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned.
  56     @param privateKey Optional output pointer to the keychain item reference of the imported private key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned.
  57         @result A result code.  See "Security Error Codes" (SecBase.h).
  58 */
  59 OSStatus SecKeyCreatePair(
  60         SecKeychainRef keychainRef,
  61         CSSM_ALGORITHMS algorithm,
  62         uint32 keySizeInBits,
  63         CSSM_CC_HANDLE contextHandle,
  64         CSSM_KEYUSE publicKeyUsage,
  65         uint32 publicKeyAttr,
  66         CSSM_KEYUSE privateKeyUsage,
  67         uint32 privateKeyAttr,
  68         SecAccessRef initialAccess,
  69         SecKeyRef* publicKey,
  70         SecKeyRef* privateKey);
  71
  72 /*!
  73         @function SecKeyGetCSSMKey
  74         @abstract Returns a pointer to the CSSM_KEY for the given key item reference.
  75     @param key A keychain key item reference. The key item must be of class type kSecAppleKeyItemClass.
  76     @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.
  77     @result A result code.  See "Security Error Codes" (SecBase.h).
  78         @discussion  The CSSM_KEY is valid until the key item reference is released.
  79 */
  80 OSStatus SecKeyGetCSSMKey(SecKeyRef key, const CSSM_KEY **cssmKey);
  81
  82
  83 #if defined(__cplusplus)
  84 }
  85 #endif
  86
  87 #endif /* !_SECURITY_SECKEY_H_ */