/* * Copyright (c) 2006-2009,2011 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 <Security/SecBase.h> #include <CoreFoundation/CFDictionary.h> #include <sys/types.h> #if defined(__cplusplus) extern "C" { #endif /* Padding Types (iPhone OS 2.0 and later only). */ typedef uint32_t SecPadding; enum { kSecPaddingNone = 0, kSecPaddingPKCS1 = 1, kSecPaddingOAEP = 2, /* 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, /* Unsupported as of iOS 5.0 */ /* 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, /* Unsupported as of iOS 5.0 */ /* 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, }; /*! @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); /*! @enum Dictionary key constants for SecKeyGeneratePair API. @discussion Predefined key constants used to get or set values in a dictionary. @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 CFTypeRef kSecPrivateKeyAttrs __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); extern CFTypeRef kSecPublicKeyAttrs __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0); /*! @function SecKeyGeneratePair @abstract Generate a private/public keypair. @param parameters A dictionary containing one or more key-value pairs. See the discussion sections below for a complete overview of options. @param publicKey On return, a SecKeyRef reference to the public key. @param privateKey On return, a SecKeyRef reference to the private key. @result A result code. See "Security Error Codes" (SecBase.h). @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. 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 * 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 */ OSStatus SecKeyGeneratePair(CFDictionaryRef parameters, SecKeyRef *publicKey, SecKeyRef *privateKey) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); /*! @function SecKeyRawSign @abstract Given a private key and data to sign, generate a digital signature. @param key Private key with which to sign. @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1. @param dataToSign The data to be signed, typically the digest of the actual data. @param dataToSignLen Length of dataToSign in bytes. @param sig Pointer to buffer in which the signature will be returned. @param sigLen IN/OUT maximum length of sig buffer on input, actualy length of sig on output. @result A result code. See "Security Error Codes" (SecBase.h). @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding will be performed prior to signing. If this argument is kSecPaddingNone, the incoming data will be signed "as is". When PKCS1 padding is performed, the maximum length of data that can be signed is the value returned by SecKeyGetBlockSize() - 11. NOTE: The behavior this function with kSecPaddingNone is undefined if the first byte of dataToSign is zero; there is no way to verify leading zeroes as they are discarded during the calculation. If you want to generate a proper PKCS1 style signature with DER encoding of the digest type - and the dataToSign is a SHA1 digest - use kSecPaddingPKCS1SHA1. */ OSStatus SecKeyRawSign( SecKeyRef key, SecPadding padding, const uint8_t *dataToSign, size_t dataToSignLen, uint8_t *sig, size_t *sigLen) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); /*! @function SecKeyRawVerify @abstract Given a public key, data which has been signed, and a signature, verify the signature. @param key Public key with which to verify the signature. @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1. @param signedData The data over which sig is being verified, typically the digest of the actual data. @param signedDataLen Length of signedData in bytes. @param sig Pointer to the signature to verify. @param sigLen Length of sig in bytes. @result A result code. See "Security Error Codes" (SecBase.h). @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding will be checked during verification. If this argument is kSecPaddingNone, the incoming data will be compared directly to sig. If you are verifying a proper PKCS1-style signature, with DER encoding of the digest type - and the signedData is a SHA1 digest - use kSecPaddingPKCS1SHA1. */ OSStatus SecKeyRawVerify( SecKeyRef key, SecPadding padding, const uint8_t *signedData, size_t signedDataLen, const uint8_t *sig, size_t sigLen) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); /*! @function SecKeyEncrypt @abstract Encrypt a block of plaintext. @param key Public key with which to encrypt the data. @param padding See Padding Types above, typically kSecPaddingPKCS1. @param plainText The data to encrypt. @param plainTextLen Length of plainText in bytes, this must be less or equal to the value returned by SecKeyGetBlockSize(). @param cipherText Pointer to the output buffer. @param cipherTextLen On input, specifies how much space is available at cipherText; on return, it is the actual number of cipherText bytes written. @result A result code. See "Security Error Codes" (SecBase.h). @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding will be performed prior to encryption. If this argument is kSecPaddingNone, the incoming data will be encrypted "as is". When PKCS1 padding is performed, the maximum length of data that can be encrypted is the value returned by SecKeyGetBlockSize() - 11. When memory usage is a critical issue, note that the input buffer (plainText) can be the same as the output buffer (cipherText). */ OSStatus SecKeyEncrypt( SecKeyRef key, SecPadding padding, const uint8_t *plainText, size_t plainTextLen, uint8_t *cipherText, size_t *cipherTextLen) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); /*! @function SecKeyDecrypt @abstract Decrypt a block of ciphertext. @param key Private key with which to decrypt the data. @param padding See Padding Types above, typically kSecPaddingPKCS1. @param cipherText The data to decrypt. @param cipherTextLen Length of cipherText in bytes, this must be less or equal to the value returned by SecKeyGetBlockSize(). @param plainText Pointer to the output buffer. @param plainTextLen On input, specifies how much space is available at plainText; on return, it is the actual number of plainText bytes written. @result A result code. See "Security Error Codes" (SecBase.h). @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding will be removed after decryption. If this argument is kSecPaddingNone, the decrypted data will be returned "as is". When memory usage is a critical issue, note that the input buffer (plainText) can be the same as the output buffer (cipherText). */ OSStatus SecKeyDecrypt( SecKeyRef key, /* Private key */ SecPadding padding, /* kSecPaddingNone, kSecPaddingPKCS1, kSecPaddingOAEP */ const uint8_t *cipherText, size_t cipherTextLen, /* length of cipherText */ uint8_t *plainText, size_t *plainTextLen) /* IN/OUT */ __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0); /*! @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_7, __IPHONE_2_0); #if defined(__cplusplus) } #endif #endif /* !_SECURITY_SECKEY_H_ */