X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/72a12576750f52947eb043106ba5c12c0d07decf..b1ab9ed8d0e0f1c3b66d7daa8fd5564444c56195:/sec/Security/SecKey.h diff --git a/sec/Security/SecKey.h b/sec/Security/SecKey.h new file mode 100644 index 00000000..c0d26c60 --- /dev/null +++ b/sec/Security/SecKey.h @@ -0,0 +1,280 @@ +/* + * 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 +#include +#include + +#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_ */