X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/80e2389990082500d76eb566d4946be3e786c3ef..d8f41ccd20de16f8ebe2ccc84d47bf1cb2b26bbb:/sec/Security/SecKey.h?ds=inline diff --git a/sec/Security/SecKey.h b/sec/Security/SecKey.h deleted file mode 100644 index 74c08f46..00000000 --- a/sec/Security/SecKey.h +++ /dev/null @@ -1,296 +0,0 @@ -/* - * 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 - -__BEGIN_DECLS - -/* 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, - - /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA224 - hash; standard ASN.1 padding will be done, as well as PKCS1 padding - of the underlying RSA operation. */ - kSecPaddingPKCS1SHA224 = 0x8003, - - /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA256 - hash; standard ASN.1 padding will be done, as well as PKCS1 padding - of the underlying RSA operation. */ - kSecPaddingPKCS1SHA256 = 0x8004, - - /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA384 - hash; standard ASN.1 padding will be done, as well as PKCS1 padding - of the underlying RSA operation. */ - kSecPaddingPKCS1SHA384 = 0x8005, - - /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA512 - hash; standard ASN.1 padding will be done, as well as PKCS1 padding - of the underlying RSA operation. */ - kSecPaddingPKCS1SHA512 = 0x8006, -}; - - -/*! - @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); - - -__END_DECLS - -#endif /* !_SECURITY_SECKEY_H_ */