Security-55471.14.8.tar.gz

[apple/security.git] / libsecurity_keychain / lib / SecKeyPriv.h

/*
 * Copyright (c) 2002-2009 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@
 *
 * SecKeyPriv.h - SPIs to SecKeyRef objects.
 */

/*!
	@header SecKeyPriv
	The functions provided in SecKeyPriv.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_SECKEYPRIV_H_
#define _SECURITY_SECKEYPRIV_H_

#include <Security/SecKey.h>
#include <Security/x509defs.h>
#include <Security/SecAsn1Types.h>
#include <AvailabilityMacros.h>

#if defined(__cplusplus)
extern "C" {
#endif

typedef struct SecRSAPublicKeyParams {
    uint8_t             *modulus;			/* modulus */
    CFIndex             modulusLength;
    uint8_t             *exponent;			/* public exponent */
    CFIndex             exponentLength;
} SecRSAPublicKeyParams;

typedef uint32_t SecKeyEncoding;
enum {
    /* Typically only used for symmetric keys. */
    kSecKeyEncodingRaw = 0,

    /* RSA keys are DER-encoded according to PKCS1. */
    kSecKeyEncodingPkcs1 = 1,

    /* RSA keys are DER-encoded according to PKCS1 with Apple Extensions. */
    kSecKeyEncodingApplePkcs1 = 2,

    /* RSA public key in SecRSAPublicKeyParams format.  keyData is a pointer
       to a SecRSAPublicKeyParams and keyDataLength is
       sizeof(SecRSAPublicKeyParams). */
    kSecKeyEncodingRSAPublicParams = 3,
};

typedef OSStatus (*SecKeyInitMethod)(SecKeyRef, const uint8_t *, CFIndex,
    SecKeyEncoding);
typedef void *(*SecKeyCopyMethod)(SecKeyRef);
typedef void  (*SecKeyDestroyMethod)(SecKeyRef);
typedef void  (*SecKeyDeleteMethod)(SecKeyRef);
typedef void  (*SecKeyShowMethod)(SecKeyRef);
typedef OSStatus (*SecKeyRawSignMethod)(SecKeyRef key, SecPadding padding,
	const uint8_t *dataToSign, size_t dataToSignLen,
	uint8_t *sig, size_t *sigLen);
typedef OSStatus (*SecKeyRawVerifyMethod)(
    SecKeyRef key, SecPadding padding, const uint8_t *signedData,
    size_t signedDataLen, const uint8_t *sig, size_t sigLen);
typedef OSStatus (*SecKeyEncryptMethod)(SecKeyRef key, SecPadding padding,
    const uint8_t *plainText, size_t plainTextLen,
	uint8_t *cipherText, size_t *cipherTextLen);
typedef OSStatus (*SecKeyDecryptMethod)(SecKeyRef key, SecPadding padding,
    const uint8_t *cipherText, size_t cipherTextLen,
    uint8_t *plainText, size_t *plainTextLen);
typedef size_t (*SecKeyBlockSizeMethod)(SecKeyRef key);
typedef CFDictionaryRef (*SecKeyCopyDictionaryMethod)(SecKeyRef key);

typedef struct {
    const char *name;
    SecKeyInitMethod init;
    SecKeyCopyMethod copy;
    SecKeyDestroyMethod destroy;
    SecKeyDeleteMethod remove;
    SecKeyShowMethod show;
    SecKeyRawSignMethod rawSign;
    SecKeyRawVerifyMethod rawVerify;
    SecKeyEncryptMethod encrypt;
    SecKeyDecryptMethod decrypt;
    SecKeyBlockSizeMethod blockSize;
    SecKeyCopyDictionaryMethod copyDictionary;
    /* If known, the number of bytes to allocate for the key field in the SecKey struct. */
    int extraBytes;
} SecKeyDescriptor;

/*!
	@function SecKeyGetAlgorithmID
	@abstract Returns a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure for the given key.
    @param key A key reference.
    @param algid On return, a pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure.
	@result A result code.  See "Security Error Codes" (SecBase.h).
*/
OSStatus SecKeyGetAlgorithmID(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER **algid)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_8_AND_LATER;

enum {
    kSecNullAlgorithmID = 0,
    kSecRSAAlgorithmID = 1,
    kSecDSAAlgorithmID = 2,   /* unsupported, just here for reference. */
    kSecECDSAAlgorithmID = 3,
};

/*!
	@function SecKeyGetAlgorithmId
	@abstract Returns an enumerated constant value which identifies the algorithm for the given key.
	@param key A key reference.
	@result An algorithm identifier.
*/
CFIndex SecKeyGetAlgorithmId(SecKeyRef key)
	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

/*!
	@function SecKeyGetStrengthInBits
	@abstract Returns key strength in bits for the given key.
    @param key A key reference.
    @param algid A pointer to a CSSM_X509_ALGORITHM_IDENTIFIER structure, as returned from a call to SecKeyGetAlgorithmID.
    @param strength On return, the key strength in bits.
	@result A result code.  See "Security Error Codes" (SecBase.h).
*/
OSStatus SecKeyGetStrengthInBits(SecKeyRef key, const CSSM_X509_ALGORITHM_IDENTIFIER *algid, unsigned int *strength);

/*!
	@function SecKeyImportPair
	@abstract Takes an asymmetric key pair and stores it in the keychain specified by the keychain parameter.
	@param keychainRef A reference to the keychain in which to store the private and public key items. Specify NULL for the default keychain.
    @param publicCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
    @param privateCssmKey A CSSM_KEY which is valid for the CSP returned by SecKeychainGetCSPHandle(). This may be a normal key or reference key.
    @param initialAccess A SecAccess object that determines the initial access rights to the private key. The public key is given an any/any acl by default.
    @param publicKey Optional output pointer to the keychain item reference of the imported public key. The caller must call CFRelease on this value if it is returned.
    @param privateKey Optional output pointer to the keychain item reference of the imported private key. The caller must call CFRelease on this value if it is returned.
	@result A result code.  See "Security Error Codes" (SecBase.h).
    @deprecated in 10.5 and later. Use the SecKeychainItemImport function instead; see <Security/SecImportExport.h>
*/
OSStatus SecKeyImportPair(
        SecKeychainRef keychainRef,
		const CSSM_KEY *publicCssmKey,
		const CSSM_KEY *privateCssmKey,
        SecAccessRef initialAccess,
        SecKeyRef* publicKey,
        SecKeyRef* privateKey)
		DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;

/*!
    @function SecKeyCreate
    @abstract Create a key reference from the supplied key data.
    @param allocator CFAllocator to allocate the key data. Pass NULL to use the default allocator.
    @param keyClass A descriptor for the particular class of key that is being created.
    @param keyData Data from which to create the key. Specify the format of this data in the encoding parameter.
    @param keyDataLength Length of the data pointed to by keyData.
    @param encoding A value of type SecKeyEncoding which describes the format of keyData.
    @result A key reference.
    @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
	IMPORTANT: on Mac OS X 10.5 and earlier, the SecKeyCreate function had a different parameter list.
	The current parameter list matches the iPhone OS implementation. Existing clients of this function
	on Mac OS X (and there should not be any outside the Security stack, per the warning above) must
	migrate to the replacement function, SecKeyCreateWithCSSMKey.
*/
SecKeyRef SecKeyCreate(CFAllocatorRef allocator,
    const SecKeyDescriptor *keyClass, const uint8_t *keyData,
	CFIndex keyDataLength, SecKeyEncoding encoding);

/*!
    @function SecKeyCreateWithCSSMKey
    @abstract Generate a temporary floating key reference for a CSSM_KEY.
    @param key A pointer to a CSSM_KEY structure.
    @param keyRef On return, a key reference.
    @result A result code. See "Security Error Codes" (SecBase.h).
    @discussion Warning: this function is NOT intended for use outside the Security stack in its current state. <rdar://3201885>
*/
OSStatus SecKeyCreateWithCSSMKey(const CSSM_KEY *key, SecKeyRef* keyRef);

/*!
	@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;
extern CFTypeRef kSecPublicKeyAttrs;

/*!
	@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);


/*!
	@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);


/*!
	@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);


/*!
	@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);


/*!
	@function SecKeyDecrypt
	@abstract Decrypt a block of ciphertext.
	@param key Private key with which to decrypt the data.
	@param padding See SecPadding 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 */

OSStatus SecKeyVerifyDigest(
	   SecKeyRef           key,            /* Private key */
	   const SecAsn1AlgId  *algId,         /* algorithm oid/params */
	   const uint8_t       *digestData,	   /* signature over this digest */
	   size_t              digestDataLen,  /* length of dataToDigest */
	   const uint8_t       *sig,           /* signature to verify */
	   size_t              sigLen);        /* length of sig */

OSStatus SecKeySignDigest(
	   SecKeyRef           key,            /* Private key */
	   const SecAsn1AlgId  *algId,         /* algorithm oid/params */
	   const uint8_t       *digestData,    /* signature over this digest */
	   size_t              digestDataLen,  /* length of digestData */
	   uint8_t             *sig,           /* signature, RETURNED */
	   size_t              *sigLen);       /* IN/OUT */


/* These are the named curves we support. These values come from RFC 4492
 section 5.1.1, with the exception of SSL_Curve_None which means
 "ECDSA not negotiated". */
typedef enum
{
	kSecECCurveNone = -1,
	kSecECCurveSecp256r1 = 23,
	kSecECCurveSecp384r1 = 24,
	kSecECCurveSecp521r1 = 25
} SecECNamedCurve;

/* Return a named curve enum for ecPrivateKey. */
SecECNamedCurve SecECKeyGetNamedCurve(SecKeyRef ecPrivateKey);
CFDataRef SecECKeyCopyPublicBits(SecKeyRef key);

/* Given an RSA public key in encoded form return a SecKeyRef representing
   that key. Supported encodings are kSecKeyEncodingPkcs1. */
SecKeyRef SecKeyCreateRSAPublicKey(CFAllocatorRef allocator,
                                   const uint8_t *keyData, CFIndex keyDataLength,
                                   SecKeyEncoding encoding);

CFDataRef SecKeyCopyModulus(SecKeyRef rsaPublicKey);
CFDataRef SecKeyCopyExponent(SecKeyRef rsaPublicKey);

/*!
 @function SecKeyCopyPublicBytes
 @abstract Gets the bits of a public key
 @param key Key to retrieve the bits.
 @param publicBytes An out parameter to receive the public key bits
 @result Errors if any when retrieving the public key bits..
 */
OSStatus SecKeyCopyPublicBytes(SecKeyRef key, CFDataRef* publicBytes);

/*!
	@function SecKeyCreatePublicFromPrivate
	@abstract Create a public SecKeyRef from a private SecKeyRef
	@param privateKey The private SecKeyRef for which you want the public key
	@result A public SecKeyRef, or NULL if the conversion failed
	@discussion This is a "best attempt" function, hence the SPI nature. If the public
    key bits are not in memory, it attempts to load from the keychain. If the public
    key was not tracked on the keychain, it will fail.
*/
SecKeyRef SecKeyCreatePublicFromPrivate(SecKeyRef privateKey);

/*!
	@function SecKeyCreateFromPublicData
*/
SecKeyRef SecKeyCreateFromPublicData(CFAllocatorRef allocator, CFIndex algorithmID, CFDataRef publicBytes);

OSStatus SecKeyRawVerifyOSX(
		 SecKeyRef           key,
		 SecPadding          padding,
		 const uint8_t       *signedData,
		 size_t              signedDataLen,
		 const uint8_t       *sig,
		 size_t              sigLen);
    
#if defined(__cplusplus)
}
#endif

#endif /* !_SECURITY_SECKEYPRIV_H_ */