1/* 2 * Copyright (c) 2006-2009,2011-2013 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/*! 25 @header SecKey 26 The functions provided in SecKey.h implement and manage a particular 27 type of keychain item that represents a key. A key can be stored in a 28 keychain, but a key can also be a transient object. 29 30 You can use a key as a keychain item in most functions. 31*/ 32 33#ifndef _SECURITY_SECKEY_H_ 34#define _SECURITY_SECKEY_H_ 35 36#include <Security/SecBase.h> 37#include <CoreFoundation/CFDictionary.h> 38#include <sys/types.h> 39 40__BEGIN_DECLS 41 42/* Padding Types (iPhone OS 2.0 and later only). */ 43typedef uint32_t SecPadding; 44enum 45{ 46 kSecPaddingNone = 0, 47 kSecPaddingPKCS1 = 1, 48 kSecPaddingOAEP = 2, 49 50 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD2 51 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 52 of the underlying RSA operation. */ 53 kSecPaddingPKCS1MD2 = 0x8000, /* Unsupported as of iOS 5.0 */ 54 55 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD5 56 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 57 of the underlying RSA operation. */ 58 kSecPaddingPKCS1MD5 = 0x8001, /* Unsupported as of iOS 5.0 */ 59 60 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA1 61 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 62 of the underlying RSA operation. */ 63 kSecPaddingPKCS1SHA1 = 0x8002, 64 65 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA224 66 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 67 of the underlying RSA operation. */ 68 kSecPaddingPKCS1SHA224 = 0x8003, 69 70 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA256 71 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 72 of the underlying RSA operation. */ 73 kSecPaddingPKCS1SHA256 = 0x8004, 74 75 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA384 76 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 77 of the underlying RSA operation. */ 78 kSecPaddingPKCS1SHA384 = 0x8005, 79 80 /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA512 81 hash; standard ASN.1 padding will be done, as well as PKCS1 padding 82 of the underlying RSA operation. */ 83 kSecPaddingPKCS1SHA512 = 0x8006, 84}; 85 86 87/*! 88 @function SecKeyGetTypeID 89 @abstract Returns the type identifier of SecKey instances. 90 @result The CFTypeID of SecKey instances. 91*/ 92CFTypeID SecKeyGetTypeID(void) 93 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); 94 95/*! 96 @enum Dictionary key constants for SecKeyGeneratePair API. 97 @discussion Predefined key constants used to get or set values 98 in a dictionary. 99 @constant kSecPrivateKeyAttrs The value for this key is a CFDictionaryRef 100 containing attributes specific for the private key to be generated. 101 @constant kSecPublicKeyAttrs The value for this key is a CFDictionaryRef 102 containing attributes specific for the public key to be generated. 103*/ 104extern CFTypeRef kSecPrivateKeyAttrs 105 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); 106extern CFTypeRef kSecPublicKeyAttrs 107 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); 108 109/*! 110 @function SecKeyGeneratePair 111 @abstract Generate a private/public keypair. 112 @param parameters A dictionary containing one or more key-value pairs. 113 See the discussion sections below for a complete overview of options. 114 @param publicKey On return, a SecKeyRef reference to the public key. 115 @param privateKey On return, a SecKeyRef reference to the private key. 116 @result A result code. See "Security Error Codes" (SecBase.h). 117 @discussion In order to generate a keypair the parameters dictionary must 118 at least contain the following keys: 119 120 * kSecAttrKeyType with a value being kSecAttrKeyTypeRSA or any other 121 kSecAttrKeyType defined in SecItem.h 122 * kSecAttrKeySizeInBits with a value being a CFNumberRef or CFStringRef 123 containing the requested key size in bits. Example sizes for RSA 124 keys are: 512, 768, 1024, 2048. 125 126 The values below may be set either in the top-level dictionary or in a 127 dictionary that is the value of the kSecPrivateKeyAttrs or 128 kSecPublicKeyAttrs key in the top-level dictionary. Setting these 129 attributes explicitly will override the defaults below. See SecItem.h 130 for detailed information on these attributes including the types of 131 the values. 132 133 * kSecAttrLabel default NULL 134 * kSecAttrIsPermanent if this key is present and has a Boolean 135 value of true, the key or key pair will be added to the default 136 keychain. 137 * kSecAttrApplicationTag default NULL 138 * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits 139 * kSecAttrCanEncrypt default false for private keys, true for public keys 140 * kSecAttrCanDecrypt default true for private keys, false for public keys 141 * kSecAttrCanDerive default true 142 * kSecAttrCanSign default true for private keys, false for public keys 143 * kSecAttrCanVerify default false for private keys, true for public keys 144 * kSecAttrCanWrap default false for private keys, true for public keys 145 * kSecAttrCanUnwrap default true for private keys, false for public keys 146 147*/ 148OSStatus SecKeyGeneratePair(CFDictionaryRef parameters, SecKeyRef *publicKey, 149 SecKeyRef *privateKey) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 150 151 152/*! 153 @function SecKeyRawSign 154 @abstract Given a private key and data to sign, generate a digital 155 signature. 156 @param key Private key with which to sign. 157 @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1. 158 @param dataToSign The data to be signed, typically the digest of the 159 actual data. 160 @param dataToSignLen Length of dataToSign in bytes. 161 @param sig Pointer to buffer in which the signature will be returned. 162 @param sigLen IN/OUT maximum length of sig buffer on input, actualy 163 length of sig on output. 164 @result A result code. See "Security Error Codes" (SecBase.h). 165 @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding 166 will be performed prior to signing. If this argument is kSecPaddingNone, 167 the incoming data will be signed "as is". 168 169 When PKCS1 padding is performed, the maximum length of data that can 170 be signed is the value returned by SecKeyGetBlockSize() - 11. 171 172 NOTE: The behavior this function with kSecPaddingNone is undefined if the 173 first byte of dataToSign is zero; there is no way to verify leading zeroes 174 as they are discarded during the calculation. 175 176 If you want to generate a proper PKCS1 style signature with DER encoding 177 of the digest type - and the dataToSign is a SHA1 digest - use 178 kSecPaddingPKCS1SHA1. 179 */ 180OSStatus SecKeyRawSign( 181 SecKeyRef key, 182 SecPadding padding, 183 const uint8_t *dataToSign, 184 size_t dataToSignLen, 185 uint8_t *sig, 186 size_t *sigLen) 187 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 188 189 190/*! 191 @function SecKeyRawVerify 192 @abstract Given a public key, data which has been signed, and a signature, 193 verify the signature. 194 @param key Public key with which to verify the signature. 195 @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1. 196 @param signedData The data over which sig is being verified, typically 197 the digest of the actual data. 198 @param signedDataLen Length of signedData in bytes. 199 @param sig Pointer to the signature to verify. 200 @param sigLen Length of sig in bytes. 201 @result A result code. See "Security Error Codes" (SecBase.h). 202 @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding 203 will be checked during verification. If this argument is kSecPaddingNone, 204 the incoming data will be compared directly to sig. 205 206 If you are verifying a proper PKCS1-style signature, with DER encoding 207 of the digest type - and the signedData is a SHA1 digest - use 208 kSecPaddingPKCS1SHA1. 209 */ 210OSStatus SecKeyRawVerify( 211 SecKeyRef key, 212 SecPadding padding, 213 const uint8_t *signedData, 214 size_t signedDataLen, 215 const uint8_t *sig, 216 size_t sigLen) 217 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 218 219 220/*! 221 @function SecKeyEncrypt 222 @abstract Encrypt a block of plaintext. 223 @param key Public key with which to encrypt the data. 224 @param padding See Padding Types above, typically kSecPaddingPKCS1. 225 @param plainText The data to encrypt. 226 @param plainTextLen Length of plainText in bytes, this must be less 227 or equal to the value returned by SecKeyGetBlockSize(). 228 @param cipherText Pointer to the output buffer. 229 @param cipherTextLen On input, specifies how much space is available at 230 cipherText; on return, it is the actual number of cipherText bytes written. 231 @result A result code. See "Security Error Codes" (SecBase.h). 232 @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding 233 will be performed prior to encryption. If this argument is kSecPaddingNone, 234 the incoming data will be encrypted "as is". 235 236 When PKCS1 padding is performed, the maximum length of data that can 237 be encrypted is the value returned by SecKeyGetBlockSize() - 11. 238 239 When memory usage is a critical issue, note that the input buffer 240 (plainText) can be the same as the output buffer (cipherText). 241 */ 242OSStatus SecKeyEncrypt( 243 SecKeyRef key, 244 SecPadding padding, 245 const uint8_t *plainText, 246 size_t plainTextLen, 247 uint8_t *cipherText, 248 size_t *cipherTextLen) 249 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 250 251 252/*! 253 @function SecKeyDecrypt 254 @abstract Decrypt a block of ciphertext. 255 @param key Private key with which to decrypt the data. 256 @param padding See Padding Types above, typically kSecPaddingPKCS1. 257 @param cipherText The data to decrypt. 258 @param cipherTextLen Length of cipherText in bytes, this must be less 259 or equal to the value returned by SecKeyGetBlockSize(). 260 @param plainText Pointer to the output buffer. 261 @param plainTextLen On input, specifies how much space is available at 262 plainText; on return, it is the actual number of plainText bytes written. 263 @result A result code. See "Security Error Codes" (SecBase.h). 264 @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding 265 will be removed after decryption. If this argument is kSecPaddingNone, 266 the decrypted data will be returned "as is". 267 268 When memory usage is a critical issue, note that the input buffer 269 (plainText) can be the same as the output buffer (cipherText). 270 */ 271OSStatus SecKeyDecrypt( 272 SecKeyRef key, /* Private key */ 273 SecPadding padding, /* kSecPaddingNone, 274 kSecPaddingPKCS1, 275 kSecPaddingOAEP */ 276 const uint8_t *cipherText, 277 size_t cipherTextLen, /* length of cipherText */ 278 uint8_t *plainText, 279 size_t *plainTextLen) /* IN/OUT */ 280 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 281 282/*! 283 @function SecKeyGetBlockSize 284 @abstract Decrypt a block of ciphertext. 285 @param key The key for which the block length is requested. 286 @result The block length of the key in bytes. 287 @discussion If for example key is an RSA key the value returned by 288 this function is the size of the modulus. 289 */ 290size_t SecKeyGetBlockSize(SecKeyRef key) 291 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); 292 293 294__END_DECLS 295 296#endif /* !_SECURITY_SECKEY_H_ */ 297