sec/Security/SecKey.h

   1 /*
   2  * Copyright (c) 2006-2009,2011 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 #if defined(__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44 /* Padding Types (iPhone OS 2.0 and later only). */
  45 typedef uint32_t SecPadding;
  46 enum
  47 {
  48     kSecPaddingNone      = 0,
  49     kSecPaddingPKCS1     = 1,
  50     kSecPaddingOAEP      = 2,
  51
  52     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD2
  53        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
  54        of the underlying RSA operation. */
  55     kSecPaddingPKCS1MD2  = 0x8000,  /* Unsupported as of iOS 5.0 */
  56
  57     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is an MD5
  58        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
  59        of the underlying RSA operation. */
  60     kSecPaddingPKCS1MD5  = 0x8001,  /* Unsupported as of iOS 5.0 */
  61
  62     /* For SecKeyRawSign/SecKeyRawVerify only, data to be signed is a SHA1
  63        hash; standard ASN.1 padding will be done, as well as PKCS1 padding
  64        of the underlying RSA operation. */
  65     kSecPaddingPKCS1SHA1 = 0x8002,
  66 };
  67
  68
  69 /*!
  70         @function SecKeyGetTypeID
  71         @abstract Returns the type identifier of SecKey instances.
  72         @result The CFTypeID of SecKey instances.
  73 */
  74 CFTypeID SecKeyGetTypeID(void)
  75     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
  76
  77 /*!
  78     @enum Dictionary key constants for SecKeyGeneratePair API.
  79     @discussion Predefined key constants used to get or set values
  80                 in a dictionary.
  81     @constant kSecPrivateKeyAttrs The value for this key is a CFDictionaryRef
  82         containing attributes specific for the private key to be generated.
  83     @constant kSecPublicKeyAttrs The value for this key is a CFDictionaryRef
  84         containing attributes specific for the public key to be generated.
  85 */
  86 extern CFTypeRef kSecPrivateKeyAttrs
  87     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
  88 extern CFTypeRef kSecPublicKeyAttrs
  89     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
  90
  91 /*!
  92     @function SecKeyGeneratePair
  93     @abstract Generate a private/public keypair.
  94     @param parameters A dictionary containing one or more key-value pairs.
  95         See the discussion sections below for a complete overview of options.
  96     @param publicKey On return, a SecKeyRef reference to the public key.
  97     @param privateKey On return, a SecKeyRef reference to the private key.
  98     @result A result code. See "Security Error Codes" (SecBase.h).
  99     @discussion In order to generate a keypair the parameters dictionary must
 100         at least contain the following keys:
 101
 102           * kSecAttrKeyType with a value being kSecAttrKeyTypeRSA or any other
 103                 kSecAttrKeyType defined in SecItem.h
 104       * kSecAttrKeySizeInBits with a value being a CFNumberRef or CFStringRef
 105             containing the requested key size in bits.  Example sizes for RSA
 106                 keys are: 512, 768, 1024, 2048.
 107
 108           The values below may be set either in the top-level dictionary or in a
 109           dictionary that is the value of the kSecPrivateKeyAttrs or
 110           kSecPublicKeyAttrs key in the top-level dictionary.  Setting these
 111           attributes explicitly will override the defaults below.  See SecItem.h
 112           for detailed information on these attributes including the types of
 113       the values.
 114
 115       * kSecAttrLabel default NULL
 116           * kSecAttrIsPermanent if this key is present and has a Boolean
 117             value of true, the key or key pair will be added to the default
 118             keychain.
 119       * kSecAttrApplicationTag default NULL
 120       * kSecAttrEffectiveKeySize default NULL same as kSecAttrKeySizeInBits
 121       * kSecAttrCanEncrypt default false for private keys, true for public keys
 122       * kSecAttrCanDecrypt default true for private keys, false for public keys
 123       * kSecAttrCanDerive default true
 124       * kSecAttrCanSign default true for private keys, false for public keys
 125       * kSecAttrCanVerify default false for private keys, true for public keys
 126       * kSecAttrCanWrap default false for private keys, true for public keys
 127       * kSecAttrCanUnwrap default true for private keys, false for public keys
 128
 129 */
 130 OSStatus SecKeyGeneratePair(CFDictionaryRef parameters, SecKeyRef *publicKey,
 131     SecKeyRef *privateKey) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 132
 133
 134 /*!
 135     @function SecKeyRawSign
 136     @abstract Given a private key and data to sign, generate a digital
 137     signature.
 138     @param key Private key with which to sign.
 139     @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 140     @param dataToSign The data to be signed, typically the digest of the
 141     actual data.
 142     @param dataToSignLen Length of dataToSign in bytes.
 143     @param sig Pointer to buffer in which the signature will be returned.
 144     @param sigLen IN/OUT maximum length of sig buffer on input, actualy
 145     length of sig on output.
 146     @result A result code. See "Security Error Codes" (SecBase.h).
 147     @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 148     will be performed prior to signing. If this argument is kSecPaddingNone,
 149     the incoming data will be signed "as is".
 150
 151     When PKCS1 padding is performed, the maximum length of data that can
 152     be signed is the value returned by SecKeyGetBlockSize() - 11.
 153
 154     NOTE: The behavior this function with kSecPaddingNone is undefined if the
 155     first byte of dataToSign is zero; there is no way to verify leading zeroes
 156     as they are discarded during the calculation.
 157
 158     If you want to generate a proper PKCS1 style signature with DER encoding
 159     of the digest type - and the dataToSign is a SHA1 digest - use
 160     kSecPaddingPKCS1SHA1.
 161  */
 162 OSStatus SecKeyRawSign(
 163     SecKeyRef           key,
 164         SecPadding          padding,
 165         const uint8_t       *dataToSign,
 166         size_t              dataToSignLen,
 167         uint8_t             *sig,
 168         size_t              *sigLen)
 169     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 170
 171
 172 /*!
 173     @function SecKeyRawVerify
 174     @abstract Given a public key, data which has been signed, and a signature,
 175     verify the signature.
 176     @param key Public key with which to verify the signature.
 177     @param padding See Padding Types above, typically kSecPaddingPKCS1SHA1.
 178     @param signedData The data over which sig is being verified, typically
 179     the digest of the actual data.
 180     @param signedDataLen Length of signedData in bytes.
 181     @param sig Pointer to the signature to verify.
 182     @param sigLen Length of sig in  bytes.
 183     @result A result code. See "Security Error Codes" (SecBase.h).
 184     @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 185     will be checked during verification. If this argument is kSecPaddingNone,
 186     the incoming data will be compared directly to sig.
 187
 188     If you are verifying a proper PKCS1-style signature, with DER encoding
 189     of the digest type - and the signedData is a SHA1 digest - use
 190     kSecPaddingPKCS1SHA1.
 191  */
 192 OSStatus SecKeyRawVerify(
 193     SecKeyRef           key,
 194         SecPadding          padding,
 195         const uint8_t       *signedData,
 196         size_t              signedDataLen,
 197         const uint8_t       *sig,
 198         size_t              sigLen)
 199     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 200
 201
 202 /*!
 203     @function SecKeyEncrypt
 204     @abstract Encrypt a block of plaintext.
 205     @param key Public key with which to encrypt the data.
 206     @param padding See Padding Types above, typically kSecPaddingPKCS1.
 207     @param plainText The data to encrypt.
 208     @param plainTextLen Length of plainText in bytes, this must be less
 209     or equal to the value returned by SecKeyGetBlockSize().
 210     @param cipherText Pointer to the output buffer.
 211     @param cipherTextLen On input, specifies how much space is available at
 212     cipherText; on return, it is the actual number of cipherText bytes written.
 213     @result A result code. See "Security Error Codes" (SecBase.h).
 214     @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 215     will be performed prior to encryption. If this argument is kSecPaddingNone,
 216     the incoming data will be encrypted "as is".
 217
 218     When PKCS1 padding is performed, the maximum length of data that can
 219     be encrypted is the value returned by SecKeyGetBlockSize() - 11.
 220
 221     When memory usage is a critical issue, note that the input buffer
 222     (plainText) can be the same as the output buffer (cipherText).
 223  */
 224 OSStatus SecKeyEncrypt(
 225     SecKeyRef           key,
 226         SecPadding          padding,
 227         const uint8_t           *plainText,
 228         size_t              plainTextLen,
 229         uint8_t             *cipherText,
 230         size_t              *cipherTextLen)
 231     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 232
 233
 234 /*!
 235     @function SecKeyDecrypt
 236     @abstract Decrypt a block of ciphertext.
 237     @param key Private key with which to decrypt the data.
 238     @param padding See Padding Types above, typically kSecPaddingPKCS1.
 239     @param cipherText The data to decrypt.
 240     @param cipherTextLen Length of cipherText in bytes, this must be less
 241     or equal to the value returned by SecKeyGetBlockSize().
 242     @param plainText Pointer to the output buffer.
 243     @param plainTextLen On input, specifies how much space is available at
 244     plainText; on return, it is the actual number of plainText bytes written.
 245     @result A result code. See "Security Error Codes" (SecBase.h).
 246     @discussion If the padding argument is kSecPaddingPKCS1, PKCS1 padding
 247     will be removed after decryption. If this argument is kSecPaddingNone,
 248     the decrypted data will be returned "as is".
 249
 250     When memory usage is a critical issue, note that the input buffer
 251     (plainText) can be the same as the output buffer (cipherText).
 252  */
 253 OSStatus SecKeyDecrypt(
 254     SecKeyRef           key,                /* Private key */
 255         SecPadding          padding,                    /* kSecPaddingNone,
 256                                                kSecPaddingPKCS1,
 257                                                kSecPaddingOAEP */
 258         const uint8_t       *cipherText,
 259         size_t              cipherTextLen,              /* length of cipherText */
 260         uint8_t             *plainText,
 261         size_t              *plainTextLen)              /* IN/OUT */
 262     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 263
 264 /*!
 265     @function SecKeyGetBlockSize
 266     @abstract Decrypt a block of ciphertext.
 267     @param key The key for which the block length is requested.
 268     @result The block length of the key in bytes.
 269     @discussion If for example key is an RSA key the value returned by
 270     this function is the size of the modulus.
 271  */
 272 size_t SecKeyGetBlockSize(SecKeyRef key)
 273     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 274
 275
 276 #if defined(__cplusplus)
 277 }
 278 #endif
 279
 280 #endif /* !_SECURITY_SECKEY_H_ */