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/* Padding Types (iPhone OS 2.0 and later only). */
43typedef uint32_t SecPadding;
44enum
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*/
92CFTypeID 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*/
104extern CFTypeRef kSecPrivateKeyAttrs
105    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_2_0);
106extern 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*/
148OSStatus 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 */
180OSStatus 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 */
210OSStatus 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 */
242OSStatus 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 */
271OSStatus 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 */
290size_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_ */
297