OSX/sec/Security/SecPBKDF.h

   1 /*
   2  *  SecPBKDF.h
   3  *
   4  *  Copyright (c) 2010,2012 Apple Inc. All Rights Reserved.
   5  *
   6  */
   7
   8 #include <CoreFoundation/CFData.h>
   9
  10 #include <CommonCrypto/CommonHMAC.h>
  11
  12 /* CC Based HMAC PRF functions */
  13 void hmac_sha1_PRF(const uint8_t *key,
  14                    size_t key_len,
  15                    const uint8_t *text,
  16                    size_t text_len,
  17                    uint8_t digest[CC_SHA1_DIGEST_LENGTH]);
  18
  19 void hmac_sha256_PRF(const uint8_t *key,
  20                    size_t key_len,
  21                    const uint8_t *text,
  22                    size_t text_len,
  23                    uint8_t digest[CC_SHA256_DIGEST_LENGTH]);
  24
  25
  26 /**
  27  PBKDF2 key derivation with HMAC-SHA1.
  28
  29  @param passwordPtr The pointer to the passsword data
  30  @param passwordLen The password data length
  31  @param saltPtr The pointer to the salt
  32  @param saltLen The salt length
  33  @param iterationCount Number of PBKDF2 iterations
  34  @param dkPtr The pointer to the derived key
  35  @param dkLen The derived key length
  36  @return errSecMemoryError on a failure to allocate the buffer. errSecSuccess otherwise.
  37  */
  38 OSStatus pbkdf2_hmac_sha1(const uint8_t *passwordPtr, size_t passwordLen,
  39                       const uint8_t *saltPtr, size_t saltLen,
  40                       uint32_t iterationCount,
  41                       void *dkPtr, size_t dkLen);
  42
  43 /**
  44  PBKDF2 key derivation with HMAC-SHA256.
  45
  46  @param passwordPtr The pointer to the passsword data
  47  @param passwordLen The password data length
  48  @param saltPtr The pointer to the salt
  49  @param saltLen The salt length
  50  @param iterationCount Number of PBKDF2 iterations
  51  @param dkPtr The pointer to the derived key
  52  @param dkLen The derived key length
  53  @return errSecMemoryError on a failure to allocate the buffer. errSecSuccess otherwise.
  54  */
  55 OSStatus pbkdf2_hmac_sha256(const uint8_t *passwordPtr, size_t passwordLen,
  56                       const uint8_t *saltPtr, size_t saltLen,
  57                       uint32_t iterationCount,
  58                       void *dkPtr, size_t dkLen);
  59
  60 /* Transformation conveninces from and to CFData where the password bytes used are the UTF-8 representation and 1000 iterations
  61
  62    This routine promises not to make any copies of the password or salt that aren't
  63    eradicated before completion.
  64
  65    The size of the result buffer is used to produce the derivedKey.
  66
  67    Be careful when using CFTypes for secrets, they tend to copy data more than you'd like.
  68    If your password and or salt aren't already in CF types use the buffer versions above.
  69
  70    If you already have the data in this form, the interface will unwrap and not copy the data anywhere extra for you.
  71
  72    void SecKeyFromPassword_HMAC_sha1(CFDataRef password, CFDataRef salt, uint32_t interationCount, CFMutableDataRef derivedKey)
  73    {
  74         pbkdf2_hmac_sha1(CFDataGetBytePtr(password), CFDataGetLength(password),
  75                          CFDataGetBytePtr(salt), CFDataGetLength(salt),
  76                          interationCount,
  77                          CFDataGetMutableBytePtr(derivedKey), CFDataGetLength(derivedKey));
  78    }
  79
  80    Suggested way to transform strings into data:
  81
  82     CFDataRef   *passwordData    = CFStringCreateExternalRepresentation(NULL, password, kCFStringEncodingUTF8, 0);
  83
  84     ...
  85
  86     CFReleaseSafe(passwordData);
  87
  88 */
  89
  90 /**
  91  PBKDF2 key derivation with HMAC-SHA1.
  92
  93  @param password Password data
  94  @param salt Salt data
  95  @param interationCount Number of PBKDF2 iterations
  96  @param derivedKey Mutable data reference to write the result of the key derivation
  97  @return errSecMemoryError on a failure to allocate the buffer. errSecSuccess otherwise.
  98  */
  99 OSStatus SecKeyFromPassphraseDataHMACSHA1(CFDataRef password, CFDataRef salt, uint32_t interationCount, CFMutableDataRef derivedKey);
 100
 101 /**
 102  PBKDF2 key derivation with HMAC-SHA256.
 103
 104  @param password Password data
 105  @param salt Salt data
 106  @param interationCount Number of PBKDF2 iterations
 107  @param derivedKey Mutable data reference to write the result of the key derivation
 108  @return errSecMemoryError on a failure to allocate the buffer. errSecSuccess otherwise.
 109  */
 110 OSStatus SecKeyFromPassphraseDataHMACSHA256(CFDataRef password, CFDataRef salt, uint32_t interationCount, CFMutableDataRef derivedKey);