OSX/libsecurity_keychain/lib/SecKeychain.h

   1 /*
   2  * Copyright (c) 2000-2004,2011,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 SecKeychain
  26         SecKeychain implements a repository for securely storing items with publicly visible attributes by which to find the items.
  27 */
  28
  29 #ifndef _SECURITY_SECKEYCHAIN_H_
  30 #define _SECURITY_SECKEYCHAIN_H_
  31
  32 #include <Security/SecBase.h>
  33 #include <Security/cssmapple.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <libkern/OSByteOrder.h>
  36 #include <Availability.h>
  37
  38 #if defined(__cplusplus)
  39 extern "C" {
  40 #endif
  41
  42 CF_ASSUME_NONNULL_BEGIN
  43
  44 /*!
  45         @enum KeychainStatus
  46         @abstract Defines the current status of a keychain.
  47         @constant kSecUnlockStateStatus Indicates the keychain is unlocked.
  48         @constant kSecReadPermStatus Indicates the keychain is readable.
  49         @constant kSecWritePermStatus Indicates the keychain is writable.
  50 */
  51 CF_ENUM(UInt32)
  52 {
  53     kSecUnlockStateStatus        = 1,
  54     kSecReadPermStatus           = 2,
  55     kSecWritePermStatus          = 4
  56 };
  57
  58 #define SEC_KEYCHAIN_SETTINGS_VERS1 1
  59
  60
  61 /*!
  62         @typedef SecKeychainSettings
  63         @abstract Contains keychain settings.
  64         @field version An unsigned 32-bit integer representing the keychain version.
  65         @field lockOnSleep A boolean value indicating whether the keychain locks when the system sleeps.
  66         @field useLockInterval A boolean value indicating whether the keychain automatically locks after a certain period of time.
  67         @field lockInterval An unsigned 32-bit integer representing the number of seconds before the keychain locks.
  68 */
  69 struct SecKeychainSettings
  70 {
  71         UInt32          version;
  72         Boolean         lockOnSleep;
  73         Boolean         useLockInterval;
  74         UInt32          lockInterval;
  75 };
  76 typedef struct SecKeychainSettings              SecKeychainSettings;
  77
  78 /*!
  79         @enum AuthenticationConstants
  80         @abstract Defines constants you can use to identify the type of authentication to use for an Internet password.
  81         @constant kSecAuthenticationTypeNTLM Specifies Windows NT LAN Manager authentication.
  82         @constant kSecAuthenticationTypeMSN Specifies Microsoft Network default authentication.
  83         @constant kSecAuthenticationTypeDPA Specifies Distributed Password authentication.
  84         @constant kSecAuthenticationTypeRPA Specifies Remote Password authentication.
  85         @constant kSecAuthenticationTypeHTTPBasic Specifies HTTP Basic authentication.
  86         @constant kSecAuthenticationTypeHTTPDigest Specifies HTTP Digest Access authentication.
  87         @constant kSecAuthenticationTypeHTMLForm Specifies HTML form based authentication.
  88         @constant kSecAuthenticationTypeDefault Specifies the default authentication type.
  89         @constant kSecAuthenticationTypeAny Specifies that any authentication type is acceptable. When performing a search, use this constant to avoid constraining your search results to a particular authentication type.
  90 */
  91 #ifdef __LITTLE_ENDIAN__
  92 #define AUTH_TYPE_FIX_(x) OSSwapConstInt32(x)
  93 #else
  94 #define AUTH_TYPE_FIX_(x) (x)
  95 #endif
  96
  97 typedef CF_ENUM(FourCharCode, SecAuthenticationType)
  98 {
  99     kSecAuthenticationTypeNTLM             = AUTH_TYPE_FIX_ ('ntlm'),
 100     kSecAuthenticationTypeMSN              = AUTH_TYPE_FIX_ ('msna'),
 101     kSecAuthenticationTypeDPA              = AUTH_TYPE_FIX_ ('dpaa'),
 102     kSecAuthenticationTypeRPA              = AUTH_TYPE_FIX_ ('rpaa'),
 103     kSecAuthenticationTypeHTTPBasic        = AUTH_TYPE_FIX_ ('http'),
 104     kSecAuthenticationTypeHTTPDigest       = AUTH_TYPE_FIX_ ('httd'),
 105     kSecAuthenticationTypeHTMLForm         = AUTH_TYPE_FIX_ ('form'),
 106     kSecAuthenticationTypeDefault          = AUTH_TYPE_FIX_ ('dflt'),
 107     kSecAuthenticationTypeAny              = AUTH_TYPE_FIX_ ( 0 )
 108 };
 109
 110 /*!
 111         @enum ProtocolTypeConstants
 112         @abstract Defines the protocol type associated with an AppleShare or Internet password.
 113         @constant kSecProtocolTypeFTP Indicates FTP.
 114         @constant kSecProtocolTypeFTPAccount Indicates FTP Account (client side), usage deprecated.
 115         @constant kSecProtocolTypeHTTP Indicates HTTP.
 116         @constant kSecProtocolTypeIRC Indicates IRC.
 117         @constant kSecProtocolTypeNNTP Indicates NNTP.
 118         @constant kSecProtocolTypePOP3 Indicates POP3.
 119         @constant kSecProtocolTypeSMTP Indicates SMTP.
 120         @constant kSecProtocolTypeSOCKS Indicates SOCKS.
 121         @constant kSecProtocolTypeIMAP Indicates IMAP.
 122         @constant kSecProtocolTypeLDAP Indicates LDAP.
 123         @constant kSecProtocolTypeAppleTalk Indicates AFP over AppleTalk.
 124         @constant kSecProtocolTypeAFP Indicates AFP over TCP.
 125         @constant kSecProtocolTypeTelnet Indicates Telnet.
 126         @constant kSecProtocolTypeSSH Indicates SSH.
 127         @constant kSecProtocolTypeFTPS Indicates FTPS (FTP over TLS/SSL).
 128         @constant kSecProtocolTypeHTTPS Indicates HTTPS (HTTP over TLS/SSL).
 129         @constant kSecProtocolTypeHTTPProxy Indicates HTTP proxy.
 130         @constant kSecProtocolTypeHTTPSProxy Indicates HTTPS proxy.
 131         @constant kSecProtocolTypeFTPProxy Indicates FTP proxy.
 132         @constant kSecProtocolTypeSMB Indicates SMB.
 133         @constant kSecProtocolTypeRTSP Indicates RTSP.
 134         @constant kSecProtocolTypeRTSPProxy Indicates RTSP proxy.
 135         @constant kSecProtocolTypeDAAP Indicates DAAP.
 136         @constant kSecProtocolTypeEPPC Indicates EPPC (Remote Apple Events).
 137         @constant kSecProtocolTypeIPP Indicates IPP.
 138         @constant kSecProtocolTypeNNTPS Indicates NNTPS (NNTP over TLS/SSL).
 139         @constant kSecProtocolTypeLDAPS Indicates LDAPS (LDAP over TLS/SSL).
 140         @constant kSecProtocolTypeTelnetS Indicates Telnet over TLS/SSL.
 141         @constant kSecProtocolTypeIMAPS Indicates IMAPS (IMAP4 over TLS/SSL).
 142         @constant kSecProtocolTypeIRCS Indicates IRCS (IRC over TLS/SSL).
 143         @constant kSecProtocolTypePOP3S Indicates POP3S (POP3 over TLS/SSL).
 144         @constant kSecProtocolTypeCVSpserver Indicates CVS pserver.
 145         @constant kSecProtocolTypeSVN Indicates Subversion.
 146         @constant kSecProtocolTypeAny Indicates that any protocol is acceptable. When performing a search, use this constant to avoid constraining your search results to a particular protocol.
 147 */
 148 typedef CF_ENUM(FourCharCode, SecProtocolType)
 149 {
 150     kSecProtocolTypeFTP         = 'ftp ',
 151     kSecProtocolTypeFTPAccount  = 'ftpa',
 152     kSecProtocolTypeHTTP        = 'http',
 153     kSecProtocolTypeIRC         = 'irc ',
 154     kSecProtocolTypeNNTP        = 'nntp',
 155     kSecProtocolTypePOP3        = 'pop3',
 156     kSecProtocolTypeSMTP        = 'smtp',
 157     kSecProtocolTypeSOCKS       = 'sox ',
 158     kSecProtocolTypeIMAP        = 'imap',
 159     kSecProtocolTypeLDAP        = 'ldap',
 160     kSecProtocolTypeAppleTalk   = 'atlk',
 161     kSecProtocolTypeAFP         = 'afp ',
 162     kSecProtocolTypeTelnet      = 'teln',
 163     kSecProtocolTypeSSH         = 'ssh ',
 164     kSecProtocolTypeFTPS        = 'ftps',
 165     kSecProtocolTypeHTTPS       = 'htps',
 166     kSecProtocolTypeHTTPProxy   = 'htpx',
 167     kSecProtocolTypeHTTPSProxy  = 'htsx',
 168     kSecProtocolTypeFTPProxy    = 'ftpx',
 169     kSecProtocolTypeCIFS        = 'cifs',
 170     kSecProtocolTypeSMB         = 'smb ',
 171     kSecProtocolTypeRTSP        = 'rtsp',
 172     kSecProtocolTypeRTSPProxy   = 'rtsx',
 173     kSecProtocolTypeDAAP        = 'daap',
 174     kSecProtocolTypeEPPC        = 'eppc',
 175     kSecProtocolTypeIPP         = 'ipp ',
 176     kSecProtocolTypeNNTPS       = 'ntps',
 177     kSecProtocolTypeLDAPS       = 'ldps',
 178     kSecProtocolTypeTelnetS     = 'tels',
 179     kSecProtocolTypeIMAPS       = 'imps',
 180     kSecProtocolTypeIRCS        = 'ircs',
 181     kSecProtocolTypePOP3S       = 'pops',
 182     kSecProtocolTypeCVSpserver  = 'cvsp',
 183     kSecProtocolTypeSVN         = 'svn ',
 184     kSecProtocolTypeAny         =  0
 185 };
 186
 187 /*!
 188         @enum KeychainEventConstants
 189         @abstract Defines the keychain-related event.
 190         @constant kSecLockEvent Indicates a keychain was locked.
 191         @constant kSecUnlockEvent Indicates a keychain was unlocked.
 192         @constant kSecAddEvent Indicates an item was added to a keychain.
 193         @constant kSecDeleteEvent Indicates an item was deleted from a keychain.
 194         @constant kSecUpdateEvent Indicates a keychain item was updated.
 195         @constant kSecPasswordChangedEvent Indicates the keychain password was changed.
 196         @constant kSecDefaultChangedEvent Indicates that a different keychain was specified as the default.
 197         @constant kSecDataAccessEvent Indicates a process has accessed a keychain item's data.
 198         @constant kSecKeychainListChangedEvent Indicates the list of keychains has changed.
 199         @constant kSecTrustSettingsChangedEvent Indicates Trust Settings changed.
 200 */
 201 typedef CF_ENUM(UInt32, SecKeychainEvent)
 202 {
 203     kSecLockEvent                 = 1,
 204     kSecUnlockEvent               = 2,
 205     kSecAddEvent                  = 3,
 206     kSecDeleteEvent               = 4,
 207     kSecUpdateEvent               = 5,
 208     kSecPasswordChangedEvent      = 6,
 209     kSecDefaultChangedEvent       = 9,
 210     kSecDataAccessEvent __API_DEPRECATED("Read events are no longer posted", macos(10.10, 10.15)) = 10,
 211     kSecKeychainListChangedEvent  = 11,
 212         kSecTrustSettingsChangedEvent = 12
 213 };
 214
 215 /*!
 216         @enum KeychainEventConstants
 217         @abstract Defines keychain event constants
 218         @constant kSecLockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is locked.
 219         @constant kSecUnlockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is unlocked.
 220         @constant kSecAddEventMask If the bit specified by this mask is set, your callback function will be invoked when an item is added to a keychain.
 221         @constant kSecDeleteEventMask If the bit specified by this mask is set, your callback function will be invoked when an item is deleted from a keychain.
 222         @constant kSecUpdateEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain item is updated.
 223         @constant kSecPasswordChangedEventMask If the bit specified by this mask is set, your callback function will be invoked when the keychain password is changed.
 224         @constant kSecDefaultChangedEventMask If the bit specified by this mask is set, your callback function will be invoked when a different keychain is specified as the default.
 225         @constant kSecDataAccessEventMask If the bit specified by this mask is set, your callback function will be invoked when a process accesses a keychain item's data.
 226         @constant kSecTrustSettingsChangedEvent If the bit specified by this mask is set, your callback function will be invoked when there is a change in certificate Trust Settings.
 227         @constant kSecEveryEventMask If all the bits are set, your callback function will be invoked whenever any event occurs.
 228 */
 229 typedef CF_OPTIONS(UInt32, SecKeychainEventMask)
 230 {
 231     kSecLockEventMask                           = 1 << kSecLockEvent,
 232     kSecUnlockEventMask                         = 1 << kSecUnlockEvent,
 233     kSecAddEventMask                            = 1 << kSecAddEvent,
 234     kSecDeleteEventMask                         = 1 << kSecDeleteEvent,
 235     kSecUpdateEventMask                         = 1 << kSecUpdateEvent,
 236     kSecPasswordChangedEventMask                = 1 << kSecPasswordChangedEvent,
 237     kSecDefaultChangedEventMask                 = 1 << kSecDefaultChangedEvent,
 238     kSecDataAccessEventMask __API_DEPRECATED("Read events are no longer posted", macos(10.10, 10.15)) = 1 << kSecDataAccessEvent,
 239     kSecKeychainListChangedMask                 = 1 << kSecKeychainListChangedEvent,
 240         kSecTrustSettingsChangedEventMask       = 1 << kSecTrustSettingsChangedEvent,
 241     kSecEveryEventMask                          = 0xffffffff
 242 };
 243
 244 /*!
 245         @typedef SecKeychainCallbackInfo
 246         @abstract Contains information about a keychain event.
 247         @field version The version of this structure.
 248         @field item A reference to the keychain item associated with this event, if any. Note that some events do not involve a particular keychain item.
 249         @field keychain A reference to the keychain in which the event occurred.
 250         @field pid The id of the process that generated this event.
 251         @discussion The SecKeychainCallbackInfo type represents a structure that contains information about the keychain event for which your application is being notified. For information on how to write a keychain event callback function, see SecKeychainCallback.
 252 */
 253 struct API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst) SecKeychainCallbackInfo
 254 {
 255     UInt32                          version;
 256     SecKeychainItemRef __nonnull        item;
 257     SecKeychainRef __nonnull            keychain;
 258         pid_t                           pid;
 259 };
 260 typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 261
 262 /*!
 263         @function SecKeychainGetTypeID
 264         @abstract Returns the type identifier of SecKeychain instances.
 265         @result The CFTypeID of SecKeychain instances.
 266 */
 267 CFTypeID SecKeychainGetTypeID(void);
 268
 269 /*!
 270         @function SecKeychainGetVersion
 271         @abstract Determines the version of the Keychain Manager installed on the userÕs system.
 272         @param returnVers On return, a pointer to the version number of the Keychain Manager installed on the current system.
 273         @result A result code.  See "Security Error Codes" (SecBase.h).
 274 */
 275 OSStatus SecKeychainGetVersion(UInt32 * __nonnull returnVers);
 276
 277 #pragma mark ---- Keychain Management ----
 278 /*!
 279     @function SecKeychainOpen
 280     @abstract Create a SecKeychainRef for a keychain at pathName.  This keychain might
 281         not currently exist, use SecKeychainGetStatus if you want to confirm the existence
 282         of this keychain.
 283         @param pathName The POSIX path to a keychain.
 284     @param keychain On return, a pointer to the keychain reference. The memory that keychain occupies must be released by calling CFRelease when finished with it.
 285         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if the keychain parameter is invalid (NULL).
 286 */
 287 OSStatus SecKeychainOpen(const char *pathName, SecKeychainRef * __nonnull CF_RETURNS_RETAINED keychain);
 288
 289 /*!
 290         @function SecKeychainCreate
 291     @abstract Creates a new keychain.
 292     @param pathName The POSIX path to a keychain file.
 293     @param passwordLength An unsigned 32-bit integer representing the length of the password buffer.
 294     @param password A pointer to the buffer containing the password. The password must be in canonical UTF8 encoding.
 295         @param promptUser A boolean representing whether to display a password dialog to the user.
 296         @param initialAccess An access reference.
 297     @param keychain On return, a pointer to a keychain reference. The memory that keychain occupies must be released by calling CFRelease when finished with it.
 298         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if the keychain parameter is invalid (NULL).
 299 */
 300 OSStatus SecKeychainCreate(const char *pathName, UInt32 passwordLength, const void * __nullable password, Boolean promptUser, SecAccessRef __nullable initialAccess, SecKeychainRef * __nonnull CF_RETURNS_RETAINED keychain) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 301
 302 /*!
 303         @function SecKeychainDelete
 304     @abstract Removes one or more keychains from the current keychain searchlist, and deletes the keychain storage (if the keychains are file-based).
 305     @param keychainOrArray A single keychain reference or a reference to an array of keychains to delete. IMPORTANT: SecKeychainDelete does not dispose the memory occupied by keychain references; use the CFRelease function when you are completely finished with a keychain.
 306         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecInvalidKeychain (-25295) may be returned if the keychain parameter is invalid (NULL).
 307 */
 308 OSStatus SecKeychainDelete(SecKeychainRef __nullable keychainOrArray) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 309
 310 /*!
 311         @function SecKeychainSetSettings
 312         @abstract Changes the settings of a keychain.
 313     @param keychain A reference to a keychain.
 314         @param newSettings A pointer to the new keychain settings.
 315         @result A result code.  See "Security Error Codes" (SecBase.h).
 316 */
 317 OSStatus SecKeychainSetSettings(SecKeychainRef __nullable keychain, const SecKeychainSettings *newSettings) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 318
 319 /*!
 320         @function SecKeychainCopySettings
 321         @abstract Copy the keychain settings.
 322     @param keychain A reference to the keychain from which to copy its settings.
 323     @param outSettings  A pointer to a keychain settings structure. Since this structure is versioned, you must preallocate it and fill in the version of the structure.
 324  @result A result code.  See "Security Error Codes" (SecBase.h).
 325 */
 326 OSStatus SecKeychainCopySettings(SecKeychainRef __nullable keychain, SecKeychainSettings *outSettings) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 327
 328 /*!
 329         @function SecKeychainUnlock
 330         @abstract Unlocks the specified keychain.
 331     @param keychain A reference to the keychain to unlock. Pass NULL to specify the default keychain. If you pass NULL and the default keychain is currently locked, the keychain will appear as the default choice. If you pass a locked keychain, SecKeychainUnlock will use the password provided to unlock it. If the default keychain is currently unlocked, SecKeychainUnlock returns errSecSuccess.
 332         @param passwordLength An unsigned 32-bit integer representing the length of the password buffer.
 333         @param password A buffer containing the password for the keychain. Pass NULL if the user password is unknown. In this case, SecKeychainUnlock displays the Unlock Keychain dialog box, and the authentication user interface associated with the keychain about to be unlocked.
 334         @param usePassword A boolean indicating whether the password parameter is used.  You should pass TRUE if it is used or FALSE if it is ignored.
 335         @result A result code.  See "Security Error Codes" (SecBase.h).
 336         @discussion In most cases, your application does not need to call the SecKeychainUnlock function directly, since most Keychain Manager functions that require an unlocked keychain call SecKeychainUnlock automatically. If your application needs to verify that a keychain is unlocked, call the function SecKeychainGetStatus.
 337 */
 338 OSStatus SecKeychainUnlock(SecKeychainRef __nullable keychain, UInt32 passwordLength, const void * __nullable password, Boolean usePassword) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 339
 340 /*!
 341         @function SecKeychainLock
 342         @abstract Locks the specified keychain.
 343     @param keychain A reference to the keychain to lock.
 344         @result A result code.  See "Security Error Codes" (SecBase.h).
 345 */
 346 OSStatus SecKeychainLock(SecKeychainRef __nullable keychain) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 347
 348 /*!
 349         @function SecKeychainLockAll
 350         @abstract Locks all keychains belonging to the current user.
 351         @result A result code.  See "Security Error Codes" (SecBase.h).
 352 */
 353 OSStatus SecKeychainLockAll(void) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 354
 355 /*!
 356         @function SecKeychainCopyDefault
 357         @abstract Retrieves a reference to the default keychain.
 358         @param keychain On return, a pointer to the default keychain reference.
 359         @result A result code.  See "Security Error Codes" (SecBase.h).
 360 */
 361 OSStatus SecKeychainCopyDefault(SecKeychainRef * __nonnull CF_RETURNS_RETAINED keychain) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 362
 363 /*!
 364         @function SecKeychainSetDefault
 365         @abstract Sets the default keychain.
 366         @param keychain A reference to the keychain to set as default.
 367         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if the keychain parameter is invalid (NULL).
 368 */
 369 OSStatus SecKeychainSetDefault(SecKeychainRef __nullable keychain) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 370
 371 /*!
 372         @function SecKeychainCopySearchList
 373         @abstract Retrieves a keychain search list.
 374         @param searchList The returned list of keychains to search. When finished with the array, you must call CFRelease() to release the memory.
 375         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if the keychain list is not specified (NULL).
 376 */
 377 OSStatus SecKeychainCopySearchList(CFArrayRef * __nonnull CF_RETURNS_RETAINED searchList) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 378
 379 /*!
 380         @function SecKeychainSetSearchList
 381         @abstract Specifies the list of keychains to use in a keychain search list.
 382         @param searchList The list of keychains to use in a search list when the SecKeychainCopySearchList function is called. An empty array clears the search list.
 383         @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if the keychain list is not specified (NULL).
 384 */
 385 OSStatus SecKeychainSetSearchList(CFArrayRef searchList) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 386
 387
 388 /*
 389  *      New versions of {Copy,Get}{SearchList,Default} that address multiple preference domains.
 390  *      These calls subsume the old forms with domain == kPreferenceDomainUser.
 391  */
 392 typedef CF_ENUM(int, SecPreferencesDomain) {
 393         kSecPreferencesDomainUser,                      /* user domain */
 394         kSecPreferencesDomainSystem,            /* system (daemon) domain */
 395         kSecPreferencesDomainCommon,            /* preferences to be merged to everyone */
 396         kSecPreferencesDomainDynamic            /* dynamic searchlist (typically removable keychains like smartcards) */
 397 };
 398
 399 OSStatus SecKeychainCopyDomainDefault(SecPreferencesDomain domain, SecKeychainRef * __nonnull CF_RETURNS_RETAINED keychain);
 400 OSStatus SecKeychainSetDomainDefault(SecPreferencesDomain domain, SecKeychainRef __nullable keychain);
 401 OSStatus SecKeychainCopyDomainSearchList(SecPreferencesDomain domain, CFArrayRef * __nonnull CF_RETURNS_RETAINED searchList);
 402 OSStatus SecKeychainSetDomainSearchList(SecPreferencesDomain domain, CFArrayRef searchList);
 403 OSStatus SecKeychainSetPreferenceDomain(SecPreferencesDomain domain);
 404 OSStatus SecKeychainGetPreferenceDomain(SecPreferencesDomain *domain);
 405
 406
 407 /*!
 408         @function SecKeychainGetStatus
 409         @abstract Retrieves status information for the specified keychain.
 410         @param keychain A keychain reference. Pass NULL to specify the default keychain.
 411         @param keychainStatus On return, a pointer to the status of the specified keychain.  See KeychainStatus for valid status constants.
 412     @result A result code.  See "Security Error Codes" (SecBase.h).
 413 */
 414 OSStatus SecKeychainGetStatus(SecKeychainRef __nullable keychain, SecKeychainStatus *keychainStatus) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 415
 416 /*!
 417         @function SecKeychainGetPath
 418         @abstract Get the path of the specified keychain.
 419     @param keychain A reference to a keychain.
 420     @param ioPathLength On input, a pointer to the size of the buffer pointed to by pathName. On return, the size of the buffer without the zero termination.
 421         @param pathName On return, the POSIX path to the keychain.
 422     @result A result code.  See "Security Error Codes" (SecBase.h).
 423 */
 424 OSStatus SecKeychainGetPath(SecKeychainRef __nullable keychain, UInt32 *ioPathLength, char *pathName) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 425
 426 #pragma mark ---- Keychain Item Attribute Information ----
 427 /*!
 428         @function SecKeychainAttributeInfoForItemID
 429         @abstract Obtains tags for all possible attributes for a given item class.
 430     @param keychain A keychain reference.
 431         @param itemID The relation identifier of the item tags (an itemID is a CSSM_DB_RECORDTYPE defined in cssmapple.h).
 432         @param info On return, a pointer to the keychain attribute information. User should call the SecKeychainFreeAttributeInfo function to release the structure when done with it.
 433     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if not enough valid parameters were supplied (NULL).
 434         @discussion Warning, this call returns more attributes than are support by the old style Keychain API and passing them into older calls will yield an invalid attribute error. The recommended call to retrieve the attribute values is the SecKeychainItemCopyAttributesAndData function.
 435 */
 436 OSStatus SecKeychainAttributeInfoForItemID(SecKeychainRef __nullable keychain,  UInt32 itemID, SecKeychainAttributeInfo * __nullable * __nonnull info) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 437
 438 /*!
 439         @function SecKeychainFreeAttributeInfo
 440         @abstract Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.
 441         @param info A pointer to the keychain attribute information to release.
 442     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if not enough valid parameters were supplied (NULL).
 443 */
 444 OSStatus SecKeychainFreeAttributeInfo(SecKeychainAttributeInfo *info) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 445
 446 #pragma mark ---- Keychain Manager Callbacks ----
 447
 448 /*!
 449         @typedef SecKeychainCallback
 450         @abstract Defines a pointer to a customized callback function.  You supply the customized callback function to do a callback tailored to your application's needs.
 451         @param keychainEvent The keychain event that your application wishes to be notified of. See SecKeychainEvent for a description of possible values. The type of event that can trigger your callback depends on the bit mask you passed in the eventMask parameter of the function SecKeychainAddCallback. For more information, see the discussion.
 452         @param info A pointer to a structure of type SecKeychainCallbackInfo. On return, the structure contains information about the keychain event that occurred. The Keychain Manager passes this information to your callback function via the info parameter.
 453         @param context A pointer to application-defined storage that your application previously passed to the function SecKeychainAddCallback. You can use this value to perform operations like track which instance of a function is operating.
 454         @result A result code.  See "Security Error Codes" (SecBase.h).
 455         @discussion If you name your function MyKeychainEventCallback, you would declare it like this:
 456         OSStatus MyKeychainEventCallback (
 457                 SecKeychainEvent keychainEvent,
 458                 SecKeychainCallbackInfo *info,
 459                 void *context);
 460
 461         To add your callback function, use the SecKeychainAddCallback function.  To remove your callback function, use the SecKeychainRemoveCallback function.
 462 */
 463 typedef OSStatus (*SecKeychainCallback)(SecKeychainEvent keychainEvent, SecKeychainCallbackInfo *info, void * __nullable context) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 464
 465 /*!
 466         @function SecKeychainAddCallback
 467         @abstract Registers your keychain event callback function
 468         @param callbackFunction A pointer to your keychain event callback function, described in SecKeychainCallback. You indicate the type of keychain events you want to receive by passing a bit mask of the desired events in the eventMask parameter.
 469         @param eventMask A bit mask indicating the keychain events that your application wishes to be notified of. See SecKeychainEventMask for a description of this bit mask. The Keychain Manager tests this mask to determine the keychain events that you wish to receive, and passes these events in the keychainEvent parameter of your callback function. See SecKeychainEvent for a description of these events.
 470         @param userContext A pointer to application-defined storage that will be passed to your callback function. Your application can use this to associate any particular call of SecKeychainAddCallback with any particular call of your keychain event callback function.
 471     @result A result code.  See "Security Error Codes" (SecBase.h).
 472 */
 473 OSStatus SecKeychainAddCallback(SecKeychainCallback callbackFunction, SecKeychainEventMask eventMask, void * __nullable userContext) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 474
 475 /*!
 476         @function SecKeychainRemoveCallback
 477         @abstract Unregisters your keychain event callback function. Once removed, keychain events won't be sent to the owner of the callback.
 478         @param callbackFunction The callback function pointer to remove
 479         @result A result code.  See "Security Error Codes" (SecBase.h).
 480 */
 481 OSStatus SecKeychainRemoveCallback(SecKeychainCallback callbackFunction) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 482
 483 #pragma mark ---- High Level Keychain Manager Calls ----
 484 /*!
 485         @function SecKeychainAddInternetPassword
 486         @abstract Adds an Internet password to the specified keychain.
 487         @param keychain A reference to a keychain in which to store an Internet password. Pass NULL to specify the user's default keychain.
 488         @param serverNameLength The length of the buffer pointed to by serverName.
 489         @param serverName A pointer to a string containing the server name associated with this password.
 490         @param securityDomainLength The length of the buffer pointed to by securityDomain.
 491         @param securityDomain A pointer to a string containing the security domain associated with this password, or NULL if there is no relevant security domain.
 492         @param accountNameLength The length of the buffer pointed to by accountName.
 493         @param accountName A pointer to a string containing the account name associated with this password.
 494         @param pathLength The length of the buffer pointed to by path.
 495         @param path A pointer to a string containing the path associated with this password, or NULL if there is no relevant path string.
 496         @param port The TCP/IP port number. If no specific port number is associated with this item, pass 0.
 497         @param protocol The protocol associated with this password. See SecProtocolType for a description of possible values.
 498         @param authenticationType The authentication scheme used. See SecAuthenticationType for a description of possible values. Pass the constant kSecAuthenticationTypeDefault to specify the default authentication scheme.
 499         @param passwordLength The length of the buffer pointed to by passwordData.
 500         @param passwordData A pointer to a buffer containing the password data to be stored in the keychain.
 501         @param itemRef On return, a reference to the new keychain item.
 502         @result A result code.  See "Security Error Codes" (SecBase.h).
 503         @discussion The SecKeychainAddInternetPassword function adds a new Internet server password to the specified keychain. Required parameters to identify the password are serverName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. SecKeychainAddInternetPassword optionally returns a reference to the newly added item.
 504 */
 505 OSStatus SecKeychainAddInternetPassword(SecKeychainRef __nullable keychain, UInt32 serverNameLength, const char * __nullable serverName, UInt32 securityDomainLength, const char * __nullable securityDomain, UInt32 accountNameLength, const char * __nullable accountName, UInt32 pathLength, const char * __nullable path, UInt16 port, SecProtocolType protocol, SecAuthenticationType authenticationType, UInt32 passwordLength, const void *passwordData, SecKeychainItemRef * __nullable CF_RETURNS_RETAINED itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 506
 507 /*!
 508         @function SecKeychainFindInternetPassword
 509         @abstract Finds an Internet password based on the attributes passed.
 510     @param keychainOrArray A reference to an array of keychains to search, a single keychain, or NULL to search the user's default keychain search list.
 511         @param serverNameLength The length of the buffer pointed to by serverName.
 512         @param serverName A pointer to a string containing the server name.
 513         @param securityDomainLength The length of the buffer pointed to by securityDomain.
 514         @param securityDomain A pointer to a string containing the security domain. This parameter is optional, as not all protocols will require it.
 515         @param accountNameLength The length of the buffer pointed to by accountName.
 516         @param accountName A pointer to a string containing the account name.
 517         @param pathLength The length of the buffer pointed to by path.
 518         @param path A pointer to a string containing the path.
 519         @param port The TCP/IP port number. Pass 0 to ignore the port number.
 520         @param protocol The protocol associated with this password. See SecProtocolType for a description of possible values.
 521         @param authenticationType The authentication scheme used. See SecAuthenticationType for a description of possible values. Pass the constant kSecAuthenticationTypeDefault to specify the default authentication scheme.
 522         @param passwordLength On return, the length of the buffer pointed to by passwordData.
 523         @param passwordData On return, a pointer to a data buffer containing the password. Your application must call SecKeychainItemFreeContent(NULL, passwordData) to release this data buffer when it is no longer needed. Pass NULL if you are not interested in retrieving the password data at this time, but simply want to find the item reference.
 524         @param itemRef On return, a reference to the keychain item which was found.
 525         @result A result code.  See "Security Error Codes" (SecBase.h).
 526         @discussion The SecKeychainFindInternetPassword function finds the first Internet password item which matches the attributes you provide. Most attributes are optional; you should pass only as many as you need to narrow the search sufficiently for your application's intended use. SecKeychainFindInternetPassword optionally returns a reference to the found item.
 527 */
 528 OSStatus SecKeychainFindInternetPassword(CFTypeRef __nullable keychainOrArray, UInt32 serverNameLength, const char * __nullable serverName, UInt32 securityDomainLength, const char * __nullable securityDomain, UInt32 accountNameLength, const char * __nullable accountName, UInt32 pathLength, const char * __nullable path, UInt16 port, SecProtocolType protocol, SecAuthenticationType authenticationType, UInt32 * __nullable passwordLength, void * __nullable * __nullable passwordData, SecKeychainItemRef * __nullable CF_RETURNS_RETAINED itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 529
 530 /*!
 531         @function SecKeychainAddGenericPassword
 532         @abstract Adds a generic password to the specified keychain.
 533         @param keychain A reference to the keychain in which to store a generic password. Pass NULL to specify the user's default keychain.
 534         @param serviceNameLength The length of the buffer pointed to by serviceName.
 535         @param serviceName A pointer to a string containing the service name associated with this password.
 536         @param accountNameLength The length of the buffer pointed to by accountName.
 537         @param accountName A pointer to a string containing the account name associated with this password.
 538         @param passwordLength The length of the buffer pointed to by passwordData.
 539         @param passwordData A pointer to a buffer containing the password data to be stored in the keychain.
 540         @param itemRef On return, a reference to the new keychain item.
 541         @result A result code. See "Security Error Codes" (SecBase.h).
 542         @discussion The SecKeychainAddGenericPassword function adds a new generic password to the default keychain. Required parameters to identify the password are serviceName and accountName, which are application-defined strings. SecKeychainAddGenericPassword optionally returns a reference to the newly added item.
 543 */
 544 OSStatus SecKeychainAddGenericPassword(SecKeychainRef __nullable keychain, UInt32 serviceNameLength, const char * __nullable serviceName, UInt32 accountNameLength, const char * __nullable accountName, UInt32 passwordLength, const void *passwordData, SecKeychainItemRef * __nullable CF_RETURNS_RETAINED itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 545
 546 /*!
 547         @function SecKeychainFindGenericPassword
 548         @abstract Find a generic password based on the attributes passed.
 549     @param keychainOrArray A reference to an array of keychains to search, a single keychain, or NULL to search the user's default keychain search list.
 550         @param serviceNameLength The length of the buffer pointed to by serviceName.
 551         @param serviceName A pointer to a string containing the service name.
 552         @param accountNameLength The length of the buffer pointed to by accountName.
 553         @param accountName A pointer to a string containing the account name.
 554         @param passwordLength On return, the length of the buffer pointed to by passwordData.
 555         @param passwordData On return, a pointer to a data buffer containing the password. Your application must call SecKeychainItemFreeContent(NULL, passwordData) to release this data buffer when it is no longer needed. Pass NULL if you are not interested in retrieving the password data at this time, but simply want to find the item reference.
 556         @param itemRef On return, a reference to the keychain item which was found.
 557         @result A result code.  See "Security Error Codes" (SecBase.h).
 558         @discussion The SecKeychainFindGenericPassword function finds the first generic password item which matches the attributes you provide. Most attributes are optional; you should pass only as many as you need to narrow the search sufficiently for your application's intended use. SecKeychainFindGenericPassword optionally returns a reference to the found item.
 559 */
 560 OSStatus SecKeychainFindGenericPassword(CFTypeRef __nullable keychainOrArray,  UInt32 serviceNameLength, const char * __nullable serviceName, UInt32 accountNameLength, const char * __nullable accountName, UInt32 * __nullable passwordLength, void * __nullable * __nullable passwordData, SecKeychainItemRef * __nullable CF_RETURNS_RETAINED itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 561
 562 #pragma mark ---- Managing User Interaction ----
 563 /*!
 564         @function SecKeychainSetUserInteractionAllowed
 565         @abstract Turns on or off any optional user interaction
 566         @param state A boolean representing the state of user interaction.  You should pass TRUE to allow user interaction, and FALSE to disallow user interaction
 567         @result A result code.  See "Security Error Codes" (SecBase.h).
 568 */
 569 OSStatus SecKeychainSetUserInteractionAllowed(Boolean state) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 570
 571 /*!
 572         @function SecKeychainGetUserInteractionAllowed
 573         @abstract Retrieves the current state of user interaction.
 574         @param state On return, a pointer to the current state of user interaction.  If this is TRUE then user interaction is allowed, if it is FALSE, then user interaction is not allowed.
 575         @result A result code.  See "Security Error Codes" (SecBase.h).
 576 */
 577 OSStatus SecKeychainGetUserInteractionAllowed(Boolean *state) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 578
 579 #pragma mark ---- CSSM Bridge Functions ----
 580 /*!
 581         @function SecKeychainGetCSPHandle
 582         @abstract Returns the CSSM_CSP_HANDLE attachment for the given keychain reference. The handle is valid until the keychain reference is released.
 583     @param keychain A keychain reference.
 584     @param cspHandle On return, a pointer to the CSSM_CSP_HANDLE for the given keychain.
 585     @result A result code.  See "Security Error Codes" (SecBase.h).
 586         @discussion This API is deprecated for 10.7. It should nho longer be needed.
 587 */
 588 OSStatus SecKeychainGetCSPHandle(SecKeychainRef __nullable keychain, CSSM_CSP_HANDLE *cspHandle)
 589         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 590
 591 /*!
 592         @function SecKeychainGetDLDBHandle
 593         @abstract Returns the CSSM_DL_DB_HANDLE for a given keychain reference. The handle is valid until the keychain reference is released.
 594     @param keychain A keychain reference.
 595     @param dldbHandle On return, a pointer to the CSSM_DL_DB_HANDLE for the given keychain.
 596     @result A result code.  See "Security Error Codes" (SecBase.h).
 597         @discussion This API is deprecated for 10.7. It should nho longer be needed.
 598 */
 599 OSStatus SecKeychainGetDLDBHandle(SecKeychainRef __nullable keychain, CSSM_DL_DB_HANDLE *dldbHandle)
 600         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 601
 602 #pragma mark ---- Keychain Access Management ----
 603 /*!
 604         @function SecKeychainCopyAccess
 605         @abstract Retrieves the access for a keychain.
 606         @param keychain A reference to the keychain from which to copy the access.
 607     @param access On return, a pointer to the access reference.
 608     @result A result code.  See "Security Error Codes" (SecBase.h).
 609 */
 610 OSStatus SecKeychainCopyAccess(SecKeychainRef __nullable keychain, SecAccessRef * __nonnull CF_RETURNS_RETAINED access)
 611         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_13, __IPHONE_NA, __IPHONE_NA);
 612
 613 /*!
 614         @function SecKeychainSetAccess
 615         @abstract Sets the access for a keychain.
 616     @param keychain A reference to the keychain for which to set the access.
 617     @param access An access reference.
 618     @result A result code.  See "Security Error Codes" (SecBase.h).
 619 */
 620 OSStatus SecKeychainSetAccess(SecKeychainRef __nullable keychain, SecAccessRef access)
 621         __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_13, __IPHONE_NA, __IPHONE_NA);
 622
 623 CF_ASSUME_NONNULL_END
 624
 625 #if defined(__cplusplus)
 626 }
 627 #endif
 628
 629 #endif /* !_SECURITY_SECKEYCHAIN_H_ */