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