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.
613 lines
28 KiB
613 lines
28 KiB
9 years ago
|
/*
|
||
|
|
* Copyright (c) 2002-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 SecKey
|
||
|
|
The functions provided in SecKey.h implement and manage a particular
|
||
|
|
type of keychain item that represents a key. A key can be stored in a
|
||
|
|
keychain, but a key can also be a transient object.
|
||
|
|
|
||
|
|
You can use a key as a keychain item in most functions.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _SECURITY_SECKEY_H_
|
||
|
|
#define _SECURITY_SECKEY_H_
|
||
|
|
|
||
|
|
#include <dispatch/dispatch.h>
|
||
|
|
#include <Security/SecBase.h>
|
||
|
|
#include <Security/SecAccess.h>
|
||
|
|
#include <Security/cssmtype.h>
|
||
|
|
#include <CoreFoundation/CFBase.h>
|
||
|
|
#include <CoreFoundation/CFDictionary.h>
|
||
|
|
#include <sys/types.h>
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
CF_ASSUME_NONNULL_BEGIN
|
||
|
|
CF_IMPLICIT_BRIDGING_ENABLED
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum KeyItemAttributeConstants
|
||
|
|
@abstract Specifies keychain item attributes for keys.
|
||
|
|
@constant kSecKeyKeyClass type uint32 (CSSM_KEYCLASS), value
|
||
|
|
is one of CSSM_KEYCLASS_PUBLIC_KEY, CSSM_KEYCLASS_PRIVATE_KEY
|
||
|
|
or CSSM_KEYCLASS_SESSION_KEY.
|
||
|
|
@constant kSecKeyPrintName type blob, human readable name of
|
||
|
|
the key. Same as kSecLabelItemAttr for normal keychain items.
|
||
|
|
@constant kSecKeyAlias type blob, currently unused.
|
||
|
|
@constant kSecKeyPermanent type uint32, value is nonzero iff
|
||
|
|
this key is permanent (stored in some keychain). This is always
|
||
|
|
1.
|
||
|
|
@constant kSecKeyPrivate type uint32, value is nonzero iff this
|
||
|
|
key is protected by a user login or a password, or both.
|
||
|
|
@constant kSecKeyModifiable type uint32, value is nonzero iff
|
||
|
|
attributes of this key can be modified.
|
||
|
|
@constant kSecKeyLabel type blob, for private and public keys
|
||
|
|
this contains the hash of the public key. This is used to
|
||
|
|
associate certificates and keys. Its value matches the value
|
||
|
|
of the kSecPublicKeyHashItemAttr of a certificate and it's used
|
||
|
|
to construct an identity from a certificate and a key.
|
||
|
|
For symmetric keys this is whatever the creator of the key
|
||
|
|
passed in during the generate key call.
|
||
|
|
@constant kSecKeyApplicationTag type blob, currently unused.
|
||
|
|
@constant kSecKeyKeyCreator type data, the data points to a
|
||
|
|
CSSM_GUID structure representing the moduleid of the csp owning
|
||
|
|
this key.
|
||
|
|
@constant kSecKeyKeyType type uint32, value is a CSSM_ALGORITHMS
|
||
|
|
representing the algorithm associated with this key.
|
||
|
|
@constant kSecKeyKeySizeInBits type uint32, value is the number
|
||
|
|
of bits in this key.
|
||
|
|
@constant kSecKeyEffectiveKeySize type uint32, value is the
|
||
|
|
effective number of bits in this key. For example a des key
|
||
|
|
has a kSecKeyKeySizeInBits of 64 but a kSecKeyEffectiveKeySize
|
||
|
|
of 56.
|
||
|
|
@constant kSecKeyStartDate type CSSM_DATE. Earliest date from
|
||
|
|
which this key may be used. If the value is all zeros or not
|
||
|
|
present, no restriction applies.
|
||
|
|
@constant kSecKeyEndDate type CSSM_DATE. Latest date at
|
||
|
|
which this key may be used. If the value is all zeros or not
|
||
|
|
present, no restriction applies.
|
||
|
|
@constant kSecKeySensitive type uint32, iff value is nonzero
|
||
|
|
this key cannot be wrapped with CSSM_ALGID_NONE.
|
||
|
|
@constant kSecKeyAlwaysSensitive type uint32, value is nonzero
|
||
|
|
iff this key has always been marked sensitive.
|
||
|
|
@constant kSecKeyExtractable type uint32, value is nonzero iff
|
||
|
|
this key can be wrapped.
|
||
|
|
@constant kSecKeyNeverExtractable type uint32, value is nonzero
|
||
|
|
iff this key was never marked extractable.
|
||
|
|
@constant kSecKeyEncrypt type uint32, value is nonzero iff this
|
||
|
|
key can be used in an encrypt operation.
|
||
|
|
@constant kSecKeyDecrypt type uint32, value is nonzero iff this
|
||
|
|
key can be used in a decrypt operation.
|
||
|
|
@constant kSecKeyDerive type uint32, value is nonzero iff this
|
||
|
|
key can be used in a deriveKey operation.
|
||
|
|
@constant kSecKeySign type uint32, value is nonzero iff this
|
||
|
|
key can be used in a sign operation.
|
||
|
|
@constant kSecKeyVerify type uint32, value is nonzero iff this
|
||
|
|
key can be used in a verify operation.
|
||
|
|
@constant kSecKeySignRecover type uint32.
|
||
|
|
@constant kSecKeyVerifyRecover type uint32.
|
||
|
|
key can unwrap other keys.
|
||
|
|
@constant kSecKeyWrap type uint32, value is nonzero iff this
|
||
|
|
key can wrap other keys.
|
||
|
|
@constant kSecKeyUnwrap type uint32, value is nonzero iff this
|
||
|
|
key can unwrap other keys.
|
||
|
|
@discussion
|
||
|
|
The use of these enumerations has been deprecated. Please
|
||
|
|
use the equivalent items defined in SecItem.h
|
||
|
|
@@@.
|
||
|
|
*/
|
||
|
|
CF_ENUM(int)
|
||
|
|
{
|
||
|
|
kSecKeyKeyClass = 0,
|
||
|
|
kSecKeyPrintName = 1,
|
||
|
|
kSecKeyAlias = 2,
|
||
|
|
kSecKeyPermanent = 3,
|
||
|
|
kSecKeyPrivate = 4,
|
||
|
|
kSecKeyModifiable = 5,
|
||
|
|
kSecKeyLabel = 6,
|
||
|
|
kSecKeyApplicationTag = 7,
|
||
|
|
kSecKeyKeyCreator = 8,
|
||
|
|
kSecKeyKeyType = 9,
|
||
|
|
kSecKeyKeySizeInBits = 10,
|
||
|
|
kSecKeyEffectiveKeySize = 11,
|
||
|
|
kSecKeyStartDate = 12,
|
||
|
|
kSecKeyEndDate = 13,
|
||
|
|
kSecKeySensitive = 14,
|
||
|
|
kSecKeyAlwaysSensitive = 15,
|
||
|
|
kSecKeyExtractable = 16,
|
||
|
|
kSecKeyNeverExtractable = 17,
|
||
|
|
kSecKeyEncrypt = 18,
|
||
|
|
kSecKeyDecrypt = 19,
|
||
|
|
kSecKeyDerive = 20,
|
||
|
|
kSecKeySign = 21,
|
||
|
|
kSecKeyVerify = 22,
|
||
|
|
kSecKeySignRecover = 23,
|
||
|
|
kSecKeyVerifyRecover = 24,
|
||
|
|
kSecKeyWrap = 25,
|
||
|
|
kSecKeyUnwrap = 26
|
||
|
|
};
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum SecCredentialType
|
||
|
|
@abstract Determines the type of credential returned by SecKeyGetCredentials.
|
||
|
|
@constant kSecCredentialTypeWithUI Operations with this key are allowed to present UI if required.
|
||
|
|
@constant kSecCredentialTypeNoUI Operations with this key are not allowed to present UI, and will fail if UI is required.
|
||
|
|
@constant kSecCredentialTypeDefault The default setting for determining whether to present UI is used. This setting can be changed with a call to SecKeychainSetUserInteractionAllowed.
|
||
|
|
*/
|
||
|
|
typedef CF_ENUM(uint32, SecCredentialType)
|
||
|
|
{
|
||
|
|
kSecCredentialTypeDefault = 0,
|
||
|
|
kSecCredentialTypeWithUI,
|
||
|
|
kSecCredentialTypeNoUI
|
||
|
|
};
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@typedef SecPadding
|
||
|
|
@abstract Supported padding types.
|
||
|
|
*/
|
||
|
|
typedef CF_ENUM(uint32_t, SecPadding)
|
||
|
|
{
|
||
|
|
kSecPaddingNone = 0,
|
||
|
|
kSecPaddingPKCS1 = 1,
|
||
|
|
|
||
|
|
/* For SecKeyRawSign/SecKeyRawVerify only,
|
||
|
|
ECDSA signature is raw byte format {r,s}, big endian.
|
||
|
|
First half is r, second half is s */
|
||
|
|
kSecPaddingSigRaw = 0x4000,
|
||
|
|
|
||
|
|
/* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD2
|
||
|
|
hash; standard ASN.1 padding will be done, as well as PKCS1 padding
|
||
|
|
of the underlying RSA operation. */
|
||
|
|
kSecPaddingPKCS1MD2 = 0x8000,
|
||
|
|
|
||
|
|
/* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD5
|
||
|
|
hash; standard ASN.1 padding will be done, as well as PKCS1 padding
|
||
|
|
of the underlying RSA operation. */
|
||
|
|
kSecPaddingPKCS1MD5 = 0x8001,
|
||
|
|
|
||
|
|
/* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA1
|
||
|
|
hash; standard ASN.1 padding will be done, as well as PKCS1 padding
|
||
|
|
of the underlying RSA operation. */
|
||
|
|
kSecPaddingPKCS1SHA1 = 0x8002,
|
||
|
|
};
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@typedef SecKeySizes
|
||
|
|
@abstract Supported key lengths.
|
||
|
|
*/
|
||
|
|
typedef CF_ENUM(uint32_t, SecKeySizes)
|
||
|
|
{
|
||
|
|
kSecDefaultKeySize = 0,
|
||
|
|
|
||
|
|
// Symmetric Keysizes - default is currently kSecAES128 for AES.
|
||
|
|
kSec3DES192 = 192,
|
||
|
|
kSecAES128 = 128,
|
||
|
|
kSecAES192 = 192,
|
||
|
|
kSecAES256 = 256,
|
||
|
|
|
||
|
|
// Supported ECC Keys for Suite-B from RFC 4492 section 5.1.1.
|
||
|
|
// default is currently kSecp256r1
|
||
|
|
kSecp192r1 = 192,
|
||
|
|
kSecp256r1 = 256,
|
||
|
|
kSecp384r1 = 384,
|
||
|
|
kSecp521r1 = 521, // Yes, 521
|
||
|
|
|
||
|
|
// Boundaries for RSA KeySizes - default is currently 2048
|
||
|
|
// RSA keysizes must be multiples of 8
|
||
|
|
kSecRSAMin = 1024,
|
||
|
|
kSecRSAMax = 4096
|
||
|
|
};
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@enum Key Parameter Constants
|
||
|
|
@discussion Predefined key constants used to get or set values in a dictionary.
|
||
|
|
These are used to provide explicit parameters to key generation functions
|
||
|
|
when non-default values are desired. See the description of the
|
||
|
|
SecKeyGeneratePair API for usage information.
|
||
|
|
@constant kSecPrivateKeyAttrs The value for this key is a CFDictionaryRef
|
||
|
|
containing attributes specific for the private key to be generated.
|
||
|
|
@constant kSecPublicKeyAttrs The value for this key is a CFDictionaryRef
|
||
|
|
containing attributes specific for the public key to be generated.
|
||
|
|
*/
|
||
|
|
extern const CFStringRef kSecPrivateKeyAttrs
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
|
||
|
|
extern const CFStringRef kSecPublicKeyAttrs
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGetTypeID
|
||
|
|
@abstract Returns the type identifier of SecKey instances.
|
||
|
|
@result The CFTypeID of SecKey instances.
|
||
|
|
*/
|
||
|
|
CFTypeID SecKeyGetTypeID(void)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyCreatePair
|
||
|
|
@abstract Creates an asymmetric key pair and stores it in a specified keychain.
|
||
|
|
@param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
|
||
|
|
@param algorithm An algorithm for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
|
||
|
|
@param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
|
||
|
|
@param contextHandle (optional) A CSSM_CC_HANDLE, or 0. If this argument is supplied, the algorithm and keySizeInBits parameters are ignored. If extra parameters are needed to generate a key (some algorithms require this), you should create a context using CSSM_CSP_CreateKeyGenContext, using the CSPHandle obtained by calling SecKeychainGetCSPHandle. Then use CSSM_UpdateContextAttributes to add parameters, and dispose of the context using CSSM_DeleteContext after calling this function.
|
||
|
|
@param publicKeyUsage A bit mask indicating all permitted uses for the new public key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
|
||
|
|
@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.
|
||
|
|
@param privateKeyUsage A bit mask indicating all permitted uses for the new private key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
|
||
|
|
@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.
|
||
|
|
@param initialAccess (optional) A SecAccess object that determines the initial access rights to the private key. The public key is given "any/any" access rights by default.
|
||
|
|
@param publicKey (optional) On return, the keychain item reference of the generated public key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned. Pass NULL if a reference to this key is not required.
|
||
|
|
@param privateKey (optional) On return, the keychain item reference of the generated private key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned. Pass NULL if a reference to this key is not required.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h).
|
||
|
|
@discussion This API is deprecated for 10.7. Please use the SecKeyGeneratePair API instead.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyCreatePair(
|
||
|
|
SecKeychainRef __nullable keychainRef,
|
||
|
|
CSSM_ALGORITHMS algorithm,
|
||
|
|
uint32 keySizeInBits,
|
||
|
|
CSSM_CC_HANDLE contextHandle,
|
||
|
|
CSSM_KEYUSE publicKeyUsage,
|
||
|
|
uint32 publicKeyAttr,
|
||
|
|
CSSM_KEYUSE privateKeyUsage,
|
||
|
|
uint32 privateKeyAttr,
|
||
|
|
SecAccessRef __nullable initialAccess,
|
||
|
|
SecKeyRef* __nullable CF_RETURNS_RETAINED publicKey,
|
||
|
|
SecKeyRef* __nullable CF_RETURNS_RETAINED privateKey)
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGenerate
|
||
|
|
@abstract Creates a symmetric key and optionally stores it in a specified keychain.
|
||
|
|
@param keychainRef (optional) A reference to the keychain in which to store the generated key. Specify NULL to generate a transient key.
|
||
|
|
@param algorithm An algorithm for the symmetric key. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
|
||
|
|
@param keySizeInBits A key size for the key pair. This parameter is ignored if a valid (non-zero) contextHandle is supplied.
|
||
|
|
@param contextHandle (optional) A CSSM_CC_HANDLE, or 0. If this argument is supplied, the algorithm and keySizeInBits parameters are ignored. If extra parameters are needed to generate a key (some algorithms require this), you should create a context using CSSM_CSP_CreateKeyGenContext, using the CSPHandle obtained by calling SecKeychainGetCSPHandle. Then use CSSM_UpdateContextAttributes to add parameters, and dispose of the context using CSSM_DeleteContext after calling this function.
|
||
|
|
@param keyUsage A bit mask indicating all permitted uses for the new key. CSSM_KEYUSE bit mask values are defined in cssmtype.h.
|
||
|
|
@param keyAttr A bit mask defining attribute values for the new key. The bit mask values are equivalent to a CSSM_KEYATTR_FLAGS and are defined in cssmtype.h.
|
||
|
|
@param initialAccess (optional) A SecAccess object that determines the initial access rights for the key. This parameter is ignored if the keychainRef is NULL.
|
||
|
|
@param keyRef On return, a reference to the generated key. Use the SecKeyGetCSSMKey function to obtain the CSSM_KEY. The caller must call CFRelease on this value if it is returned.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h).
|
||
|
|
@discussion This API is deprecated for 10.7. Please use the SecKeyGenerateSymmetric API instead.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyGenerate(
|
||
|
|
SecKeychainRef __nullable keychainRef,
|
||
|
|
CSSM_ALGORITHMS algorithm,
|
||
|
|
uint32 keySizeInBits,
|
||
|
|
CSSM_CC_HANDLE contextHandle,
|
||
|
|
CSSM_KEYUSE keyUsage,
|
||
|
|
uint32 keyAttr,
|
||
|
|
SecAccessRef __nullable initialAccess,
|
||
|
|
SecKeyRef* __nullable CF_RETURNS_RETAINED keyRef)
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGetCSSMKey
|
||
|
|
@abstract Returns a pointer to the CSSM_KEY for the given key item reference.
|
||
|
|
@param key A keychain key item reference. The key item must be of class type kSecPublicKeyItemClass, kSecPrivateKeyItemClass, or kSecSymmetricKeyItemClass.
|
||
|
|
@param cssmKey On return, a pointer to a CSSM_KEY structure for the given key. This pointer remains valid until the key reference is released. The caller should not attempt to modify or free this data.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h).
|
||
|
|
@discussion The CSSM_KEY is valid until the key item reference is released. This API is deprecated in 10.7. Its use should no longer be needed.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyGetCSSMKey(SecKeyRef key, const CSSM_KEY * __nullable * __nonnull cssmKey)
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGetCSPHandle
|
||
|
|
@abstract Returns the CSSM_CSP_HANDLE for the given key reference. The handle is valid until the key reference is released.
|
||
|
|
@param keyRef A key reference.
|
||
|
|
@param cspHandle On return, the CSSM_CSP_HANDLE for the given keychain.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h).
|
||
|
|
@discussion This API is deprecated in 10.7. Its use should no longer be needed.
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyGetCSPHandle(SecKeyRef keyRef, CSSM_CSP_HANDLE *cspHandle)
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGetCredentials
|
||
|
|
@abstract For a given key, return a pointer to a CSSM_ACCESS_CREDENTIALS structure which will allow the key to be used.
|
||
|
|
@param keyRef The key for which a credential is requested.
|
||
|
|
@param operation The type of operation to be performed with this key. See "Authorization tag type" for defined operations (cssmtype.h).
|
||
|
|
@param credentialType The type of credential requested.
|
||
|
|
@param outCredentials On return, a pointer to a CSSM_ACCESS_CREDENTIALS structure. This pointer remains valid until the key reference is released. The caller should not attempt to modify or free this data.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h).
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyGetCredentials(
|
||
|
|
SecKeyRef keyRef,
|
||
|
|
CSSM_ACL_AUTHORIZATION_TAG operation,
|
||
|
|
SecCredentialType credentialType,
|
||
|
|
const CSSM_ACCESS_CREDENTIALS * __nullable * __nonnull outCredentials)
|
||
|
|
DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGetBlockSize
|
||
|
|
@abstract Decrypt a block of ciphertext.
|
||
|
|
@param key The key for which the block length is requested.
|
||
|
|
@result The block length of the key in bytes.
|
||
|
|
@discussion If for example key is an RSA key the value returned by
|
||
|
|
this function is the size of the modulus.
|
||
|
|
*/
|
||
|
|
size_t SecKeyGetBlockSize(SecKeyRef key)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGenerateSymmetric
|
||
|
|
@abstract Generates a random symmetric key with the specified length
|
||
|
|
and algorithm type.
|
||
|
|
|
||
|
|
@param parameters A dictionary containing one or more key-value pairs.
|
||
|
|
See the discussion sections below for a complete overview of options.
|
||
|
|
@param error An optional pointer to a CFErrorRef. This value is set
|
||
|
|
if an error occurred. If not NULL, the caller is responsible for
|
||
|
|
releasing the CFErrorRef.
|
||
|
|
@result On return, a SecKeyRef reference to the symmetric key, or
|
||
|
|
NULL if the key could not be created.
|
||
|
|
|
||
|
|
@discussion In order to generate a symmetric key, the parameters dictionary
|
||
|
|
must at least contain the following keys:
|
||
|
|
|
||
|
|
* kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other
|
||
|
|
kSecAttrKeyType defined in SecItem.h
|
||
|
|
* kSecAttrKeySizeInBits with a value being a CFNumberRef containing
|
||
|
|
the requested key size in bits. Example sizes for AES keys are:
|
||
|
|
128, 192, 256, 512.
|
||
|
|
|
||
|
|
To store the generated symmetric key in a keychain, set these keys:
|
||
|
|
* kSecUseKeychain (value is a SecKeychainRef)
|
||
|
|
* kSecAttrLabel (a user-visible label whose value is a CFStringRef,
|
||
|
|
e.g. "My App's Encryption Key")
|
||
|
|
* kSecAttrApplicationLabel (a label defined by your application, whose
|
||
|
|
value is a CFStringRef and which can be used to find this key in a
|
||
|
|
subsequent call to SecItemCopyMatching, e.g. "ID-1234567890-9876-0151")
|
||
|
|
|
||
|
|
To specify the generated key's access control settings, set this key:
|
||
|
|
* kSecAttrAccess (value is a SecAccessRef)
|
||
|
|
|
||
|
|
The keys below may be optionally set in the parameters dictionary
|
||
|
|
(with a CFBooleanRef value) to override the default usage values:
|
||
|
|
|
||
|
|
* kSecAttrCanEncrypt (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanDecrypt (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanWrap (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanUnwrap (defaults to true if not explicitly specified)
|
||
|
|
|
||
|
|
*/
|
||
|
|
__nullable
|
||
|
|
SecKeyRef SecKeyGenerateSymmetric(CFDictionaryRef parameters, CFErrorRef *error)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyCreateFromData
|
||
|
|
@abstract Creates a symmetric key with the given data and sets the
|
||
|
|
algorithm type specified.
|
||
|
|
|
||
|
|
@param parameters A dictionary containing one or more key-value pairs.
|
||
|
|
See the discussion sections below for a complete overview of options.
|
||
|
|
@result On return, a SecKeyRef reference to the symmetric key.
|
||
|
|
|
||
|
|
@discussion In order to generate a symmetric key the parameters dictionary must
|
||
|
|
at least contain the following keys:
|
||
|
|
|
||
|
|
* kSecAttrKeyType with a value of kSecAttrKeyTypeAES or any other
|
||
|
|
kSecAttrKeyType defined in SecItem.h
|
||
|
|
|
||
|
|
The keys below may be optionally set in the parameters dictionary
|
||
|
|
(with a CFBooleanRef value) to override the default usage values:
|
||
|
|
|
||
|
|
* kSecAttrCanEncrypt (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanDecrypt (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanWrap (defaults to true if not explicitly specified)
|
||
|
|
* kSecAttrCanUnwrap (defaults to true if not explicitly specified)
|
||
|
|
|
||
|
|
*/
|
||
|
|
__nullable
|
||
|
|
SecKeyRef SecKeyCreateFromData(CFDictionaryRef parameters,
|
||
|
|
CFDataRef keyData, CFErrorRef *error)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGeneratePair
|
||
|
|
@abstract Generate a private/public keypair.
|
||
|
|
@param parameters A dictionary containing one or more key-value pairs.
|
||
|
|
@result A result code. See "Security Error Codes" (SecBase.h). On success,
|
||
|
|
the result code will be errSecSuccess, and the output parameters will
|
||
|
|
contain the public SecKeyRef and private SecKeyRef. It is the caller's
|
||
|
|
responsibility to CFRelease these key references when finished with them.
|
||
|
|
|
||
|
|
@discussion In order to generate a keypair the parameters dictionary must
|
||
|
|
at least contain the following keys:
|
||
|
|
|
||
|
|
* kSecAttrKeyType with a value of kSecAttrKeyTypeRSA or any other
|
||
|
|
kSecAttrKeyType defined in SecItem.h
|
||
|
|
* kSecAttrKeySizeInBits with a value being a CFNumberRef containing
|
||
|
|
the requested key size in bits. Example sizes for RSA keys are:
|
||
|
|
512, 768, 1024, 2048.
|
||
|
|
|
||
|
|
The values below may be set either in the top-level dictionary or in a
|
||
|
|
dictionary that is the value of the kSecPrivateKeyAttrs or
|
||
|
|
kSecPublicKeyAttrs key in the top-level dictionary. Setting these
|
||
|
|
attributes explicitly will override the defaults below. See SecItem.h
|
||
|
|
for detailed information on these attributes including the types of
|
||
|
|
the values.
|
||
|
|
|
||
|
|
* kSecAttrLabel default NULL
|
||
|
|
* kSecUseKeychain default NULL, which specifies the default keychain
|
||
|
|
* kSecAttrApplicationTag default NULL
|
||
|
|
* kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits
|
||
|
|
* kSecAttrCanEncrypt default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanDecrypt default true for private keys, false for public keys
|
||
|
|
* kSecAttrCanDerive default true
|
||
|
|
* kSecAttrCanSign default true for private keys, false for public keys
|
||
|
|
* kSecAttrCanVerify default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanWrap default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanUnwrap default true for private keys, false for public keys
|
||
|
|
|
||
|
|
*/
|
||
|
|
OSStatus SecKeyGeneratePair(CFDictionaryRef parameters,
|
||
|
|
SecKeyRef * __nullable CF_RETURNS_RETAINED publicKey, SecKeyRef * __nullable CF_RETURNS_RETAINED privateKey)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@typedef SecKeyGeneratePairBlock
|
||
|
|
@abstract Delivers the result from an asynchronous key pair generation.
|
||
|
|
@param publicKey - the public key generated. You must retain publicKey if you wish to use it after your block returns.
|
||
|
|
@param privateKey - the private key generated. You must retain publicKey if you wish to use it after your block returns.
|
||
|
|
@param error - Any errors returned. You must retain error if you wish to use it after your block returns.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifdef __BLOCKS__
|
||
|
|
typedef void (^SecKeyGeneratePairBlock)(SecKeyRef publicKey, SecKeyRef privateKey, CFErrorRef error);
|
||
|
|
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyGeneratePairAsync
|
||
|
|
@abstract Generate a private/public keypair returning the values in a callback.
|
||
|
|
@param parameters A dictionary containing one or more key-value pairs.
|
||
|
|
@param deliveryQueue A dispatch queue to be used to deliver the results.
|
||
|
|
@param result A callback function to result when the operation has completed.
|
||
|
|
@result On success the function returns NULL.
|
||
|
|
|
||
|
|
@discussion In order to generate a keypair the parameters dictionary must
|
||
|
|
at least contain the following keys:
|
||
|
|
|
||
|
|
* kSecAttrKeyType with a value being kSecAttrKeyTypeRSA or any other
|
||
|
|
kSecAttrKeyType defined in SecItem.h
|
||
|
|
* kSecAttrKeySizeInBits with a value being a CFNumberRef or CFStringRef
|
||
|
|
containing the requested key size in bits. Example sizes for RSA
|
||
|
|
keys are: 512, 768, 1024, 2048.
|
||
|
|
|
||
|
|
Setting the following attributes explicitly will override the defaults below.
|
||
|
|
See SecItem.h for detailed information on these attributes including the types
|
||
|
|
of the values.
|
||
|
|
|
||
|
|
* kSecAttrLabel default NULL
|
||
|
|
* kSecAttrIsPermanent if this key is present and has a Boolean
|
||
|
|
value of true, the key or key pair will be added to the default
|
||
|
|
keychain.
|
||
|
|
* kSecAttrApplicationTag default NULL
|
||
|
|
* kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits
|
||
|
|
* kSecAttrCanEncrypt default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanDecrypt default true for private keys, false for public keys
|
||
|
|
* kSecAttrCanDerive default true
|
||
|
|
* kSecAttrCanSign default true for private keys, false for public keys
|
||
|
|
* kSecAttrCanVerify default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanWrap default false for private keys, true for public keys
|
||
|
|
* kSecAttrCanUnwrap default true for private keys, false for public keys
|
||
|
|
|
||
|
|
*/
|
||
|
|
void SecKeyGeneratePairAsync(CFDictionaryRef parameters,
|
||
|
|
dispatch_queue_t deliveryQueue, SecKeyGeneratePairBlock result)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
#endif /* __BLOCKS__ */
|
||
|
|
|
||
|
|
// Derive, Wrap, and Unwrap
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyDeriveFromPassword
|
||
|
|
@abstract Derives a symmetric key from a password.
|
||
|
|
|
||
|
|
@param password The password from which the keyis to be derived.
|
||
|
|
@param parameters A dictionary containing one or more key-value pairs.
|
||
|
|
@param error If the call fails this will contain the error code.
|
||
|
|
|
||
|
|
@discussion In order to derive a key the parameters dictionary must contain at least contain the following keys:
|
||
|
|
* kSecAttrSalt - a CFData for the salt value for mixing in the pseudo-random rounds.
|
||
|
|
* kSecAttrPRF - the algorithm to use for the pseudo-random-function.
|
||
|
|
If 0, this defaults to kSecAttrPRFHmacAlgSHA1. Possible values are:
|
||
|
|
|
||
|
|
* kSecAttrPRFHmacAlgSHA1
|
||
|
|
* kSecAttrPRFHmacAlgSHA224
|
||
|
|
* kSecAttrPRFHmacAlgSHA256
|
||
|
|
* kSecAttrPRFHmacAlgSHA384
|
||
|
|
* kSecAttrPRFHmacAlgSHA512
|
||
|
|
|
||
|
|
* kSecAttrRounds - the number of rounds to call the pseudo random function.
|
||
|
|
If 0, a count will be computed to average 1/10 of a second.
|
||
|
|
* kSecAttrKeySizeInBits with a value being a CFNumberRef
|
||
|
|
containing the requested key size in bits. Example sizes for RSA keys are:
|
||
|
|
512, 768, 1024, 2048.
|
||
|
|
|
||
|
|
@result On success a SecKeyRef is returned. On failure this result is NULL and the
|
||
|
|
error parameter contains the reason.
|
||
|
|
|
||
|
|
*/
|
||
|
|
__nullable
|
||
|
|
SecKeyRef SecKeyDeriveFromPassword(CFStringRef password,
|
||
|
|
CFDictionaryRef parameters, CFErrorRef *error)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyWrapSymmetric
|
||
|
|
@abstract Wraps a symmetric key with a symmetric key.
|
||
|
|
|
||
|
|
@param keyToWrap The key which is to be wrapped.
|
||
|
|
@param wrappingKey The key wrapping key.
|
||
|
|
@param parameters The parameter list to use for wrapping the key.
|
||
|
|
@param error If the call fails this will contain the error code.
|
||
|
|
|
||
|
|
@result On success a CFDataRef is returned. On failure this result is NULL and the
|
||
|
|
error parameter contains the reason.
|
||
|
|
|
||
|
|
@discussion In order to wrap a key the parameters dictionary may contain the following key:
|
||
|
|
* kSecSalt - a CFData for the salt value for the encrypt.
|
||
|
|
|
||
|
|
*/
|
||
|
|
__nullable
|
||
|
|
CFDataRef SecKeyWrapSymmetric(SecKeyRef keyToWrap,
|
||
|
|
SecKeyRef wrappingKey, CFDictionaryRef parameters, CFErrorRef *error)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@function SecKeyUnwrapSymmetric
|
||
|
|
@abstract Unwrap a wrapped symmetric key.
|
||
|
|
|
||
|
|
@param keyToUnwrap The wrapped key to unwrap.
|
||
|
|
@param unwrappingKey The key unwrapping key.
|
||
|
|
@param parameters The parameter list to use for unwrapping the key.
|
||
|
|
@param error If the call fails this will contain the error code.
|
||
|
|
|
||
|
|
@result On success a SecKeyRef is returned. On failure this result is NULL and the
|
||
|
|
error parameter contains the reason.
|
||
|
|
|
||
|
|
@discussion In order to unwrap a key the parameters dictionary may contain the following key:
|
||
|
|
* kSecSalt - a CFData for the salt value for the decrypt.
|
||
|
|
|
||
|
|
*/
|
||
|
|
__nullable
|
||
|
|
SecKeyRef SecKeyUnwrapSymmetric(CFDataRef __nullable * __nonnull keyToUnwrap,
|
||
|
|
SecKeyRef unwrappingKey, CFDictionaryRef parameters, CFErrorRef *error)
|
||
|
|
__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
|
||
|
|
|
||
|
|
CF_IMPLICIT_BRIDGING_DISABLED
|
||
|
|
CF_ASSUME_NONNULL_END
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* !_SECURITY_SECKEY_H_ */
|