OSX/Breadcrumb/SecBreadcrumb.h

   1 /*
   2  * Copyright (c) 2014 - 2016 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  @function      SecBreadcrumbCreateFromPassword
  26  @abstract      Encryptes the password using a random key and then returns
  27  the encrypted password (breadcrumb) and the password encrypted random key.
  28
  29  @param inPassword is the password to encrypt and use to encrypt the random key.
  30  @param outBreadcrumb is the password encrypted using a random key.
  31  @param outEncryptedKey is the random key encrypted using inPassword.
  32  @param outError An optional pointer to a CFErrorRef. This value is set
  33  if an error occurred. If not NULL, the caller is responsible for
  34  releasing the CFErrorRef.
  35  @result On return a Boolean indicating success or failure.
  36
  37  @discussion This function generates the breadcrumb that will be used to
  38  update the user's keychain password when their Apple ID Login password
  39  is changed on appleid.apple.com.
  40 */
  41
  42 Boolean
  43 SecBreadcrumbCreateFromPassword(CFStringRef inPassword,
  44         CFDataRef *outBreadcrumb,
  45         CFDataRef *outEncryptedKey,
  46         CFErrorRef *outError);
  47
  48
  49 /*!
  50  @function      SecBreadcrumbCopyPassword
  51  @abstract      Decryptes the encrypted key using the password and uses the key to
  52  decrypt the breadcrumb and returns the password stored in the breadcrumb.
  53
  54  @param inPassword is the password to decrypt the encrypted random key.
  55  @param inBreadcrumb is the breadcrumb encrypted by the key. It contains
  56  and encrypted version of the users old password.
  57  @param inEncryptedKey is an encrypted version of the key used to encrypt the
  58  breadcrumb.
  59  @param outPassword is the cleartext password that was stored in the breadcrumb.
  60  @param outError An optional pointer to a CFErrorRef. This value is set
  61  if an error occurred. If not NULL, the caller is responsible for
  62  releasing the CFErrorRef.
  63  @result On return a Boolean indicating success or failure.
  64
  65  @discussion This function uses the password to decrypt the encrypted key and then
  66  uses that key to decrypt the breadcrumb.
  67 */
  68
  69 Boolean
  70 SecBreadcrumbCopyPassword(CFStringRef inPassword,
  71         CFDataRef inBreadcrumb,
  72         CFDataRef inEncryptedKey,
  73         CFStringRef *outPassword,
  74         CFErrorRef *outError);
  75
  76 /*
  77  * Change password used to encrypt the key from old password to new password
  78  */
  79
  80 CFDataRef
  81 SecBreadcrumbCreateNewEncryptedKey(CFStringRef oldPassword,
  82                                    CFStringRef newPassword,
  83                                    CFDataRef encryptedKey,
  84                                    CFErrorRef *outError);