1/*
2 * Copyright (c) 2000-2004 Apple Computer, 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 SecPasswordGenerate
26 SecPassword implements logic to use the system facilities for acquiring a password,
27 optionally stored and retrieved from the user's keychain.
28 */
29
30#ifndef _SECURITY_SECPASSWORDGENERATE_H_
31#define _SECURITY_SECPASSWORDGENERATE_H_
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#include <CoreFoundation/CoreFoundation.h>
38#include <Security/SecBase.h>
39
40typedef uint32_t SecPasswordType;
41enum {
42    kSecPasswordTypeSafari = 0,
43    kSecPasswordTypeiCloudRecovery = 1,
44    kSecPasswordTypeWifi = 2,
45    kSecPasswordTypePIN = 3
46} __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
47
48// Keys for external dictionaries with password generation requirements we read from plist.
49extern CFStringRef kSecPasswordDefaultForType
50    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
51
52extern CFStringRef kSecPasswordMinLengthKey
53    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
54extern CFStringRef kSecPasswordMaxLengthKey
55    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
56extern CFStringRef kSecPasswordAllowedCharactersKey
57    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
58extern CFStringRef kSecPasswordRequiredCharactersKey
59    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
60
61extern CFStringRef kSecPasswordDisallowedCharacters
62    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
63extern CFStringRef kSecPasswordCantStartWithChars
64    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
65extern CFStringRef kSecPasswordCantEndWithChars
66    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
67
68extern CFStringRef kSecPasswordContainsNoMoreThanNSpecificCharacters
69    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
70extern CFStringRef kSecPasswordContainsAtLeastNSpecificCharacters
71    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
72extern CFStringRef kSecPasswordContainsNoMoreThanNConsecutiveIdenticalCharacters
73    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
74
75extern CFStringRef kSecPasswordCharacters
76    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
77extern CFStringRef kSecPasswordCharacterCount
78    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
79
80extern CFStringRef kSecPasswordGroupSize
81    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
82extern CFStringRef kSecPasswordNumberOfGroups
83    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
84extern CFStringRef kSecPasswordSeparator
85    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
86
87
88/*
89    @function SecPasswordCopyDefaultPasswordLength
90    @abstract Returns the default length/number of tuples of a defaultly generated password
91    @param type: default password types kSecPasswordTypeSafari, kSecPasswordTypeiCloudRecovery, kSecPasswordTypeWifi, kSecPasswordTypePIN
92    @param error: An error code will be returned if an unrecognized password type is passed to the routine.
93    @result Dictionary consisting of length of tuple and number of tuples or a NULL if the passed type isn't recognized.
94*/
95CFDictionaryRef SecPasswordCopyDefaultPasswordLength(SecPasswordType type, CFErrorRef *error)
96    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
97
98
99/*
100 @function SecPasswordIsPasswordWeak
101 @abstract Evalutes the weakness of a passcode. This function can take any type of passcode.  Currently
102    the function evaluates passcodes with only ASCII characters
103 @param passcode a string of any length and type (4 digit PIN, complex passcode)
104 @result True if the password is weak, False if the password is strong.
105 */
106
107bool SecPasswordIsPasswordWeak(CFStringRef passcode)
108    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
109
110/*
111 @function SecPasswordGenerate.  Supports generating passwords for Safari, iCloud, Personal
112 Hotspot clients.  Will also generate 4 digit pins.
113 @abstract Returns a generated password based on a set of constraints
114 @param type: type of password to generate. Pass enum types
115 kSecPasswordTypeSafari, kSecPasswordTypeiCloudRecovery, kSecPasswordTypeWifi, or kSecPasswordTypePIN
116 @param error: An error code will be returned if an error is encountered.  Check SecBase.h for the list of codes.
117 @param passwordRequirements: a dictionary containing a set of password requirements.
118 ex: password type 'safari' requires at least: minLength, maxLength, string
119 of allowed characters, required characters
120 @return NULL or a CFStringRef password
121
122 *Note: This parameters is not required if kSecPasswordTypeiCloudRecovery or kSecPasswordTypePIN is supplied as the type.
123 If kSecPasswordTypeSafari or kSecPasswordTypeWifi is supplied, you must include these dictionary key/value pairs:
124 kSecPasswordMinLengthKey / CFNumberRef
125 kSecPasswordMaxLengthKey / CFNumberRef
126 kSecPasswordAllowedCharactersKey / CFStringRef
127 kSecPasswordRequiredCharactersKey / CFArrayRef of CFCharacterSetRefs
128
129 *Note: Be sure to release the returned password when done using it.
130 */
131CF_RETURNS_RETAINED CFStringRef SecPasswordGenerate(SecPasswordType type, CFErrorRef *error, CFDictionaryRef passwordRequirements)
132    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
133
134#ifdef __cplusplus
135}
136#endif
137
138#endif /* !_SECURITY_SECPASSWORDGENERATE_H_ */
139