OSX/Breadcrumb/SecBreadcrumb.h

   1 /*!
   2  @function      SecBreadcrumbCreateFromPassword
   3  @abstract      Encryptes the password using a random key and then returns
   4  the encrypted password (breadcrumb) and the password encrypted random key.
   5
   6  @param inPassword is the password to encrypt and use to encrypt the random key.
   7  @param outBreadcrumb is the password encrypted using a random key.
   8  @param outEncryptedKey is the random key encrypted using inPassword.
   9  @param error An optional pointer to a CFErrorRef. This value is set
  10  if an error occurred. If not NULL, the caller is responsible for
  11  releasing the CFErrorRef.
  12  @result On return a Boolean indicating success or failure.
  13
  14  @discussion This function generates the breadcrumb that will be used to
  15  update the user's keychain password when their Apple ID Login password
  16  is changed on appleid.apple.com.
  17 */
  18
  19 Boolean
  20 SecBreadcrumbCreateFromPassword(CFStringRef inPassword,
  21         CFDataRef *outBreadcrumb,
  22         CFDataRef *outEncryptedKey,
  23         CFErrorRef *outError);
  24
  25
  26 /*!
  27  @function      SecBreadcrumbCopyPassword
  28  @abstract      Decryptes the encrypted key using the password and uses the key to
  29  decrypt the breadcrumb and returns the password stored in the breadcrumb.
  30
  31  @param inPassword is the password to decrypt the encrypted random key.
  32  @param inBreadcrumb is the breadcrumb encrypted by the key. It contains
  33  and encrypted version of the users old password.
  34  @param inEcryptedKey is an encrypted version of the key used to encrypt the
  35  breadcrumb.
  36  @param outPassword is the cleartext password that was stored in the breadcrumb.
  37  @param error An optional pointer to a CFErrorRef. This value is set
  38  if an error occurred. If not NULL, the caller is responsible for
  39  releasing the CFErrorRef.
  40  @result On return a Boolean indicating success or failure.
  41
  42  @discussion This function uses the password to decrypt the encrypted key and then
  43  uses that key to decrypt the breadcrumb.
  44 */
  45
  46 Boolean
  47 SecBreadcrumbCopyPassword(CFStringRef inPassword,
  48         CFDataRef inBreadcrumb,
  49         CFDataRef inEncryptedKey,
  50         CFStringRef *outPassword,
  51         CFErrorRef *outError);
  52
  53 /*
  54  * Change password used to encrypt the key from old password to new password
  55  */
  56
  57 CFDataRef
  58 SecBreadcrumbCreateNewEncryptedKey(CFStringRef oldPassword,
  59                                    CFStringRef newPassword,
  60                                    CFDataRef encryptedKey,
  61                                    CFErrorRef *outError);