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.
612 lines
28 KiB
612 lines
28 KiB
/* |
|
* 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_ */
|
|
|