SecPasswordGenerate.h
1 /* 2 * Copyright (c) 2000-2004,2013-2014 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 @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 34 extern "C" { 35 #endif 36 37 #include <CoreFoundation/CoreFoundation.h> 38 #include <Security/SecBase.h> 39 40 typedef uint32_t SecPasswordType; 41 enum { 42 kSecPasswordTypeSafari = 0, 43 kSecPasswordTypeiCloudRecovery = 1, 44 kSecPasswordTypeWifi = 2, 45 kSecPasswordTypePIN = 3, 46 kSecPasswordTypeiCloudRecoveryKey __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.4) = 4, 47 } __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 48 49 // Keys for external dictionaries with password generation requirements we read from plist. 50 extern CFStringRef kSecPasswordDefaultForType 51 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 52 53 extern CFStringRef kSecPasswordMinLengthKey 54 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 55 extern CFStringRef kSecPasswordMaxLengthKey 56 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 57 extern CFStringRef kSecPasswordAllowedCharactersKey 58 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 59 extern CFStringRef kSecPasswordRequiredCharactersKey 60 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 61 62 extern CFStringRef kSecPasswordDisallowedCharacters 63 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 64 extern CFStringRef kSecPasswordCantStartWithChars 65 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 66 extern CFStringRef kSecPasswordCantEndWithChars 67 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 68 69 extern CFStringRef kSecPasswordContainsNoMoreThanNSpecificCharacters 70 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 71 extern CFStringRef kSecPasswordContainsAtLeastNSpecificCharacters 72 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 73 extern CFStringRef kSecPasswordContainsNoMoreThanNConsecutiveIdenticalCharacters 74 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 75 76 extern CFStringRef kSecPasswordCharacters 77 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 78 extern CFStringRef kSecPasswordCharacterCount 79 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 80 81 extern CFStringRef kSecPasswordGroupSize 82 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 83 extern CFStringRef kSecPasswordNumberOfGroups 84 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 85 extern CFStringRef kSecPasswordSeparator 86 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 87 88 89 /* 90 @function SecPasswordCopyDefaultPasswordLength 91 @abstract Returns the default length/number of tuples of a defaultly generated password 92 @param type: default password types kSecPasswordTypeSafari, kSecPasswordTypeiCloudRecovery, kSecPasswordTypeWifi, kSecPasswordTypePIN 93 @param error: An error code will be returned if an unrecognized password type is passed to the routine. 94 @result Dictionary consisting of length of tuple and number of tuples or a NULL if the passed type isn't recognized. 95 */ 96 CFDictionaryRef SecPasswordCopyDefaultPasswordLength(SecPasswordType type, CFErrorRef *error) 97 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 98 99 /* 100 * Check that password is propery formated (groups, checksum). Make no claim about password quality. 101 */ 102 bool 103 SecPasswordValidatePasswordFormat(SecPasswordType type, CFStringRef password, CFErrorRef *error) 104 __OSX_AVAILABLE(10.12.4) __IOS_AVAILABLE(10.4) __WATCHOS_AVAILABLE(3.4) __TVOS_AVAILABLE(10.4); 105 106 /* 107 @function SecPasswordIsPasswordWeak 108 @abstract Evalutes the weakness of a passcode. This function can take any type of passcode. Currently 109 the function evaluates passcodes with only ASCII characters 110 @param passcode a string of any length and type (4 or 6 digit digit PIN, complex passcode) 111 @result True if the password is weak, False if the password is strong. 112 */ 113 114 bool SecPasswordIsPasswordWeak(CFStringRef passcode) 115 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 116 117 /* 118 @function SecPasswordIsPasswordWeak2 119 @abstract Evalutes the weakness of a passcode. This function can take any type of passcode. Currently 120 the function evaluates passcodes with only ASCII characters 121 ***conditions in which a passcode will be evaluated as weak*** 122 * all repeating characters 123 * repeating 2 digits 124 * is found in the black list of the top 10 most commonly used passcodes 125 * incrementing digits 126 * decrementing digits (including 0987) 127 * low enough levels of entropy (complex passcodes) 128 @param passcode a string of any length and type (4 or 6 digit PIN, complex passcode) 129 @param isSimple is to indicate whether we're evaluating a 4 or 6 digit PIN or a complex passcode 130 @result True if the password is weak, False if the password is strong. 131 */ 132 133 bool SecPasswordIsPasswordWeak2(bool isSimple, CFStringRef passcode) 134 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 135 136 /* 137 @function SecPasswordGenerate. Supports generating passwords for Safari, iCloud, Personal 138 Hotspot clients. Will also generate 4 or 6 digit pins. 139 @abstract Returns a generated password based on a set of constraints 140 @param type: type of password to generate. Pass enum types 141 kSecPasswordTypeSafari, kSecPasswordTypeiCloudRecovery, kSecPasswordTypeWifi, or kSecPasswordTypePIN 142 @param error: An error code will be returned if an error is encountered. Check SecBase.h for the list of codes. 143 @param passwordRequirements: a dictionary containing a set of password requirements. 144 ex: password type 'safari' requires at least: minLength, maxLength, string 145 of allowed characters, required characters 146 @return NULL or a CFStringRef password 147 148 *Note: This parameters is not required if kSecPasswordTypeiCloudRecovery or kSecPasswordTypePIN is supplied as the type. 149 If kSecPasswordTypeSafari or kSecPasswordTypeWifi is supplied, you must include these dictionary key/value pairs: 150 kSecPasswordMinLengthKey / CFNumberRef 151 kSecPasswordMaxLengthKey / CFNumberRef 152 kSecPasswordAllowedCharactersKey / CFStringRef 153 kSecPasswordRequiredCharactersKey / CFArrayRef of CFCharacterSetRefs 154 155 *Note: *If you would like a custom password type, file a bug in Sec Utilities requesting 156 a new type along with generation specifications (ex. should contain one upper case, one lower case etc) 157 158 *Note: Be sure to release the returned password when done using it. 159 */ 160 CF_RETURNS_RETAINED CFStringRef SecPasswordGenerate(SecPasswordType type, CFErrorRef *error, CFDictionaryRef passwordRequirements) 161 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 162 163 CFStringRef SecPasswordCreateWithRandomDigits(int n, CFErrorRef *error) 164 __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0); 165 166 #ifdef __cplusplus 167 } 168 #endif 169 170 #endif /* !_SECURITY_SECPASSWORDGENERATE_H_ */