OSX/sec/Security/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_ */