OSX/sec/Security/SecKey.h

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