SecDH.h
1 /* 2 * Copyright (c) 2007-2008,2010,2012-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 SecDH 26 The functions provided in SecDH.h implement the crypto required 27 for a Diffie-Hellman key exchange. 28 */ 29 30 #ifndef _SECURITY_SECDH_H_ 31 #define _SECURITY_SECDH_H_ 32 33 #include <Security/SecBase.h> 34 #include <CoreFoundation/CoreFoundation.h> 35 #include <stdint.h> 36 #include <stdbool.h> 37 #include <sys/types.h> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 typedef struct OpaqueSecDHContext *SecDHContext; 44 45 /*! 46 @function SecDHCreate 47 @abstract Return a newly allocated SecDHContext object. 48 @param g generator (2 or 5) 49 @param p prime as a big-endian unsigned byte array 50 @param p_len length of p, in bytes 51 @param l (optional) minimum length of private key in bits, or 0 for default 52 @param recip (optional) reciprocal of p as a big-endian unsigned byte array 53 @param recip_len length of recip, in bytes 54 @param dh (output) pointer to a SecDHContext 55 @discussion The recip and recip_len parameters are constant for a given p. 56 They are optional, although providing them improves performance. 57 @result On success, a newly allocated SecDHContext is returned in dh and 58 errSecSuccess is returned. On failure, NULL is returned in dh and an OSStatus error 59 code is returned. 60 The caller should call SecDHDestroy once the returned context is no longer 61 needed. 62 */ 63 OSStatus SecDHCreate(uint32_t g, const uint8_t *p, size_t p_len, uint32_t l, 64 const uint8_t *recip, size_t recip_len, SecDHContext *dh); 65 66 /*! 67 @function SecDHCreateFromParameters 68 @param params A DER-encoded ASN.1 parameter object, as per PKCS3, containing 69 Diffie-Hellman key parameters 70 @param params_len Length of params, in bytes 71 @param dh (output) A pointer to a SecDHContext 72 @result On success, a newly allocated SecDHContext is returned in dh and 73 errSecSuccess is returned. On failure, NULL is returned in dh and an OSStatus error 74 code is returned. 75 The caller should call SecDHDestroy once the returned context is no longer 76 needed. 77 */ 78 OSStatus SecDHCreateFromParameters(const uint8_t *params, size_t params_len, 79 SecDHContext *dh); 80 81 /*! 82 @function SecDHCreateFromAlgorithmId 83 @param alg A DER-encoded ASN.1 Algorithm Identifier object, as per PKCS1, 84 containing DH parameters. 85 @param alg_len Length of alg, in bytes 86 @param dh (output) A pointer to a SecDHContext 87 @result On success, a newly allocated SecDHContext is returned in dh and 88 errSecSuccess is returned. On failure, NULL is returned in dh and an OSStatus error 89 code is returned. 90 The caller should call SecDHDestroy once the returned context is no longer 91 needed. 92 */ 93 OSStatus SecDHCreateFromAlgorithmId(const uint8_t *alg, size_t alg_len, 94 SecDHContext *dh); 95 96 /*! 97 @function SecDHGetMaxKeyLength 98 @abstract Return the maximum length in bytes of the pub_key returned by 99 SecDHGenerateKeypair(). 100 @param dh A context created by one of the SecDHCreate functions 101 @discussion The value returned by this function is also the largest number 102 of bytes returned by SecDHComputeKey(). If a caller used the 103 SecDHCreate() function to create the SecDHContext passed to this function, 104 the value returned will be less than or equal to the p_len parameter 105 passed to SecDHCreate(). 106 @result Return maximum length, in bytes, of keys returned by the passed-in 107 SecDHContext. 108 */ 109 size_t SecDHGetMaxKeyLength(SecDHContext dh); 110 111 /*! 112 @function SecDHGenerateKeypair 113 @abstract Generate a Diffie-Hellman private/public key pair and return 114 the public key as an unsigned big-endian byte array. 115 @param dh A context created by one of the SecDHCreate functions 116 @param pub_key On return, the public key to be shared with the other party. 117 @params pub_key_len On input, the number of bytes available in pub_key; 118 on output, the number of bytes actually in pub_key. 119 @discussion Reusing a SecDHContext for multiple SecDHGenerateKeypair() 120 invocations is permitted. 121 @result errSecSuccess on success, or an OSStatus error code on failure. 122 */ 123 OSStatus SecDHGenerateKeypair(SecDHContext dh, uint8_t *pub_key, 124 size_t *pub_key_len); 125 126 /*! 127 @function SecDHComputeKey 128 @abstract Given a SecDHContext and the other party's public key, 129 compute the shared secret. 130 @param dh A context created by one of the SecDHCreate functions, on which 131 SecDHGenerateKeypair() has been invoked first. 132 @param pub_key The other party's public key, as an unsigned big-endian byte 133 array. 134 @params pub_key_len The length of pub_key, in bytes 135 @param computed_key A pointer to a byte array in which the computed key 136 is returned. 137 @param computed_key_len On input, contains the number of 138 bytes requested to be returned in computed_key; on output, contains 139 the number of bytes returned in computed_key. 140 This will only be less than the requested number of bytes if the number 141 of bytes requested is larger than the number of bytes output by the 142 compute-key operation. 143 @discussion If *computed_key_len is less than the size of the actual 144 computed key, only the first *computed_key_len bytes will be returned. 145 No leading zero bytes will be returned, and the computed_key is returned 146 as an unsigned big-endian byte array. 147 @result errSecSuccess on success, or an OSStatus error code on failure. 148 */ 149 OSStatus SecDHComputeKey(SecDHContext dh, 150 const uint8_t *pub_key, size_t pub_key_len, 151 uint8_t *computed_key, size_t *computed_key_len); 152 153 /*! 154 @function SecDHDestroy 155 @abstract Destroy a SecDHContext created with one of the SecDHCreate functions. 156 @param dh A context created by one of the SecDHCreate functions 157 */ 158 void SecDHDestroy(SecDHContext dh); 159 160 161 /*! 162 @function SecDHEncodeParams 163 @abstract Encode parameters in a PKCS#3 blob 164 */ 165 OSStatus SecDHEncodeParams(CFDataRef g, CFDataRef p, 166 CFDataRef l, CFDataRef recip, 167 CFDataRef *params); 168 169 /*! 170 @function SecDHDecodeParams 171 @abstract Decode parameters in a PKCS#3 blob 172 */ 173 OSStatus SecDHDecodeParams(CFDataRef *g, CFDataRef *p, 174 CFDataRef *l, CFDataRef *r, 175 CFDataRef params); 176 177 #ifdef __cplusplus 178 } 179 #endif 180 181 #endif /* _SECURITY_SECDH_H_ */