1/* 2 * Copyright (c) 2010 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#ifndef _CC_ECCRYPTOR_H_ 25#define _CC_ECCRYPTOR_H_ 26 27#include <Availability.h> 28 29#include <CommonCrypto/CommonCryptor.h> 30#include <CommonCrypto/CommonDigestSPI.h> 31#include "CommonRSACryptor.h" 32 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/*! 39 @typedef CCECCryptorRef 40 @abstract Opaque reference to a CCECCryptor object. 41 */ 42 43typedef struct _CCECCryptor *CCECCryptorRef; 44 45 46/* 47 EC Key Types 48 */ 49 50enum { 51 ccECKeyPublic = 0, 52 ccECKeyPrivate = 1, 53 ccECBlankPublicKey = 97, 54 ccECBlankPrivateKey = 98, 55 ccECBadKey = 99, 56}; 57typedef uint32_t CCECKeyType; 58 59/* 60 EC Key Import/Export Formats 61 */ 62 63enum { 64 kCCImportKeyBinary = 0, 65 kCCImportKeyDER = 1, 66}; 67typedef uint32_t CCECKeyExternalFormat; 68 69/*! 70 @discussion 71 72 Key sizes for this set of interfaces must be between 128 and 384 bits. 73 The key size must also be evenly divisible by 8 74*/ 75 76/*! 77 @function CCECCryptorGeneratePair 78 @abstract Generate an EC public and private key. A curve will be chosen from 79 ECC-256 or ECC-384. 80 81 @param keysize Must be between 192 and 521 (inclusive) 82 83 @param publicKey A (required) pointer for the returned public CCECCryptorRef. 84 85 @param privateKey A (required) pointer for the returned private CCECCryptorRef. 86 87 88 @result Possible error returns are kCCParamError and kCCMemoryFailure. 89*/ 90 91CCCryptorStatus 92CCECCryptorGeneratePair( size_t keysize, 93 CCECCryptorRef *publicKey, 94 CCECCryptorRef *privateKey) 95__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 96 97/*! 98 @function CCECCryptorGetPublicKeyFromPrivateKey 99 @abstract Grab the parts from a private key to make a public key. 100 101 @param privateKey A pointer to a private CCECCryptorRef. 102 103 104 @result Possible error returns are kCCParamError and kCCMemoryFailure. 105 */ 106 107CCECCryptorRef 108CCECCryptorGetPublicKeyFromPrivateKey(CCECCryptorRef privateKey) 109__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 110 111 112/*! 113 @function CCECCryptorImportPublicKey 114 @abstract Import an Elliptic Curve public key from data. This imports public 115 keys in ANSI X.9.63 format. 116 117 @param keyPackage The data package containing the encoded key. 118 119 @param keyPackageLen The length of the encoded key package. 120 121 @param key A CCECCryptorRef of the decoded key. 122 123 @result Possible error returns are kCCParamError and kCCMemoryFailure. 124*/ 125 126 127CCCryptorStatus CCECCryptorImportPublicKey( void *keyPackage, 128 size_t keyPackageLen, 129 CCECCryptorRef *key) 130__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 131 132/*! 133 @function CCECCryptorImportKey 134 @abstract Import an Elliptic Curve public key from data. 135 136 @param format The format in which the key is encoded. 137 138 @param keyPackage The data package containing the encoded key. 139 140 @param keyPackageLen The length of the encoded key package. 141 142 @param keyType The type of key to be imported (public or private). 143 144 @param key A CCECCryptorRef of the decoded key. 145 146 @result Possible error returns are kCCParamError and kCCMemoryFailure. 147 */ 148 149CCCryptorStatus CCECCryptorImportKey(CCECKeyExternalFormat format, void *keyPackage, size_t keyPackageLen, CCECKeyType keyType, CCECCryptorRef *key) 150__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 151 152 153/*! 154 @function CCECCryptorExportPublicKey 155 @abstract Export an Elliptic Curve public key from data. This exports public 156 keys in ANSI X.9.63 format. 157 158 @param key The CCECCryptorRef of the key to encode. 159 160 @param out The destination for the encoded key. 161 162 @param outLen A pointer to the length of the encoded key. 163 This is an in/out parameter. 164 165 166 @result Possible error returns are kCCParamError and kCCMemoryFailure. 167 */ 168 169CCCryptorStatus CCECCryptorExportPublicKey( CCECCryptorRef key, 170 void *out, 171 size_t *outLen) 172__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 173 174 175// We'll remove the CCECCryptorExportPublicKey later - we like this better. 176CCCryptorStatus CCECCryptorExportKey(CCECKeyExternalFormat format, void *keyPackage, size_t *keyPackageLen, CCECKeyType keyType, CCECCryptorRef key) 177__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 178 179 180/*! 181 @function CCECGetKeyType 182 @abstract Determine whether a CCECCryptorRef is public or private 183 184 @param key The CCECCryptorRef. 185 @result Return values are ccECKeyPublic, ccECKeyPrivate, or ccECBadKey 186 187*/ 188 189CCECKeyType CCECGetKeyType(CCECCryptorRef key) 190__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 191 192/*! 193 @function CCECGetKeySize 194 @abstract Return the key size 195 196 @param key The CCECCryptorRef. 197 @result Returns the keysize in bits or kCCParamError. 198 199*/ 200 201int CCECGetKeySize(CCECCryptorRef key) 202__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 203 204 205/*! 206 @function CCECCryptorRelease 207 @abstract Clear and release a CCECCryptorRef. 208 209 @param key The CCECCryptorRef of the key to release. 210*/ 211 212 213void CCECCryptorRelease(CCECCryptorRef key) 214__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 215 216/*! 217 @function CCECCryptorSignHash 218 219 @abstract Compute a signature for a hash with an EC private key. 220 221 @param privateKey A pointer to a private CCECCryptorRef. 222 223 @param hashToSign A pointer to the bytes of the value to be signed. 224 225 @param hashSignLen Length of data to be signed. 226 227 @param signedData The signature bytes. 228 229 @param signedDataLen A pointer to the length of signature material. 230 This is an in/out parameter value. 231 232 @result Possible error returns are kCCParamError and kCCMemoryFailure. 233*/ 234 235 236CCCryptorStatus 237CCECCryptorSignHash( CCECCryptorRef privateKey, 238 const void *hashToSign, 239 size_t hashSignLen, 240 void *signedData, 241 size_t *signedDataLen) 242__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 243 244 245/*! 246 @function CCECCryptorVerifyHash 247 248 @abstract Verify a signature for data with an EC private key. 249 250 @param publicKey A pointer to a public CCECCryptorRef. 251 252 @param hash A pointer to the bytes of the hash of the data. 253 254 @param hashLen Length of hash. 255 256 @param signedData The bytes of the signature to be verified. 257 258 @param signedDataLen Length of data associated with the signature. 259 260 @param valid An indicator whether the signature was valid 261 262 @result Possible error returns are kCCParamError, kCCMemoryFailure 263 or kCCNotVerified. 264*/ 265 266CCCryptorStatus 267CCECCryptorVerifyHash( CCECCryptorRef publicKey, 268 const void *hash, 269 size_t hashLen, 270 const void *signedData, 271 size_t signedDataLen, 272 uint32_t *valid) 273__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 274 275 276 277/*! 278 @function CCECCryptorWrapKey 279 280 @abstract Encrypt data (wrap a symmetric key) with an EC public key. 281 282 @param publicKey A pointer to a public CCECCryptorRef. 283 284 @param plainText A pointer to the data to be encrypted. 285 286 @param plainTextLen Length of data to be encrypted. 287 288 @param cipherText The encrypted byte result. 289 290 @param cipherTextLen Length of encrypted bytes. 291 292 @param digestType The digest algorithm to use (See CommonDigestSPI.h). 293 294 @result Possible error returns are kCCParamError. 295*/ 296 297CCCryptorStatus 298CCECCryptorWrapKey(CCECCryptorRef publicKey, 299 const void *plainText, 300 size_t plainTextLen, 301 void *cipherText, 302 size_t *cipherTextLen, 303 CCDigestAlg digestType) 304__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 305 306 307/*! 308 @function CCECCryptorUnwrapKey 309 310 @abstract Decrypt data (unwrap a symmetric key) with an EC private key. 311 312 @param privateKey A pointer to a private CCECCryptorRef. 313 314 @param cipherText The encrypted bytes. 315 316 @param cipherTextLen Length of encrypted bytes. 317 318 @param plainText The decrypted data bytes. 319 320 @param plainTextLen A pointer to the length of data decrypted. 321 This is an in/out parameter. 322 323 @result Possible error returns are kCCParamError. 324*/ 325 326CCCryptorStatus 327CCECCryptorUnwrapKey(CCECCryptorRef privateKey, 328 const void *cipherText, 329 size_t cipherTextLen, 330 void *plainText, 331 size_t *plainTextLen) 332__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 333 334 335/*! 336 @function CCECCryptorComputeSharedSecret 337 338 @abstract Construct a Diffie-Hellman shared secret with a private and 339 public ECC key. 340 341 @param privateKey A pointer to a private CCECCryptorRef. 342 343 @param publicKey A pointer to a public CCECCryptorRef (usually 344 obtained from the other party in the session.) 345 346 @param out The output data buffer. 347 348 @param outLen The output data buffer size. This is an in-out 349 parameter. When the function returns this is set 350 to the length of the result. 351 352 @result Possible error returns are kCCParamError, kCCDecodeError 353 or kCCBufferTooSmall. 354 355*/ 356 357CCCryptorStatus 358CCECCryptorComputeSharedSecret( CCECCryptorRef privateKey, 359 CCECCryptorRef publicKey, 360 void *out, 361 size_t *outLen) 362__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 363 364/*======================================================================================*/ 365/* Only for FIPS Testing */ 366/*======================================================================================*/ 367 368/*! 369 @function CCECCryptorGetKeyComponents 370 @abstract Get EC Public Key Parameters for FIPS tests 371 372 @param ecKey The EC Key to deconstruct 373 @param keySize The EC Keysize. 374 @param qX, qXLength The pointer and length(return) for the X Parameter. 375 @param qY, qYLength The pointer and length(return) for the Y Parameter. 376 @param d, dLength The pointer and length(return) for the D (Private Key Only) 377 Parameter. 378 379 @result If the function is successful (kCCSuccess) the X and Y parameters contain the 380 discreet public key point coordinate values. If the key passed in is a Private 381 Key the D parameter will contain the private key. 382 All other errors result in kCCParamError. 383 */ 384 385CCCryptorStatus 386CCECCryptorGetKeyComponents(CCECCryptorRef ecKey, size_t *keySize, 387 uint8_t *qX, size_t *qXLength, 388 uint8_t *qY, size_t *qYLength, 389 uint8_t *d, size_t *dLength) 390__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 391 392 393/*! 394 @function CCECCryptorCreateFromData 395 @abstract For FIPS CAVS testing we need the ability to create an EC 396 key from an X and Y parameter set. 397 398 @param keySize The EC Keysize. 399 @param qX, qXLength The pointer and length for the X Parameter. 400 @param qY, qYLength The pointer and length for the Y Parameter. 401 @param ref A pointer to the CCECCryptorRef to contain the result. 402 @result If the function is successful (kCCSuccess) a CCECCryptorRef is 403 returned in the ref parameter. All other errors result in 404 kCCParamError. 405 */ 406 407CCCryptorStatus 408CCECCryptorCreateFromData(size_t keySize, 409 uint8_t *qX, size_t qXLength, 410 uint8_t *qY, size_t qYLength, 411 CCECCryptorRef *ref) 412__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 413 414/*! 415 @function CCECSignatureDecode 416 @abstract For FIPS CAVS testing we need the ability to get the binary S and R values 417 from the DER signature blob. 418 @param SignedData, signedDataLen The pointer and length of the DER formatted signature 419 @param r, rLength The pointer and length for the R component (return value). 420 @param s, sLength The pointer and length for the S component (return value). 421 @result If the function is successful (kCCSuccess) the r and s parameters have the 422 individual values from the signature. 423 */ 424 425CCCryptorStatus 426CCECSignatureDecode(const void *signedData, size_t signedDataLen, 427 uint8_t *r, size_t *rLength, 428 uint8_t *s, size_t *sLength) 429__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 430 431/*! 432 @function CCECSignatureEncode 433 @abstract For FIPS CAVS testing we need the ability to produce a DER formatted signature from 434 discreet R and S components. 435 @param r, rLength The pointer and length for the R component. 436 @param s, sLength The pointer and length for the S component. 437 @param signedData, signedDataLen The pointer and length of the DER formatted 438 signature ( return value) 439 @result If the function is successful (kCCSuccess) the signature is returned as a 440 DER-formatted blob. */ 441 442CCCryptorStatus 443CCECSignatureEncode(uint8_t *r, size_t rLength, 444 uint8_t *s, size_t sLength, 445 void *signedData, size_t *signedDataLen) 446__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0); 447 448#ifdef __cplusplus 449} 450#endif 451 452#endif /* _CC_ECCRYPTOR_H_ */ 453