]> git.saurik.com Git - apple/security.git/blob - OSX/Breadcrumb/SecBreadcrumb.h
Security-59306.140.5.tar.gz
[apple/security.git] / 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);