Security-59754.80.3.tar.gz

[apple/security.git] / OSX / libsecurity_keychain / lib / SecKeychain.h

/*
 * Copyright (c) 2000-2004,2011,2013-2014 Apple Inc. All Rights Reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
	@header SecKeychain
	SecKeychain implements a repository for securely storing items with publicly visible attributes by which to find the items.
*/

#ifndef _SECURITY_SECKEYCHAIN_H_
#define _SECURITY_SECKEYCHAIN_H_

#include <Security/SecBase.h>
#include <Security/cssmapple.h>
#include <CoreFoundation/CFArray.h>
#include <libkern/OSByteOrder.h>
#include <Availability.h>

#if defined(__cplusplus)
extern "C" {
#endif

CF_ASSUME_NONNULL_BEGIN

/*!
	@enum KeychainStatus
	@abstract Defines the current status of a keychain.
	@constant kSecUnlockStateStatus Indicates the keychain is unlocked.
	@constant kSecReadPermStatus Indicates the keychain is readable.
	@constant kSecWritePermStatus Indicates the keychain is writable.
*/
CF_ENUM(UInt32)
{
    kSecUnlockStateStatus        = 1,
    kSecReadPermStatus           = 2,
    kSecWritePermStatus          = 4
};

#define SEC_KEYCHAIN_SETTINGS_VERS1 1


/*!
	@typedef SecKeychainSettings
	@abstract Contains keychain settings.
	@field version An unsigned 32-bit integer representing the keychain version.
	@field lockOnSleep A boolean value indicating whether the keychain locks when the system sleeps.
	@field useLockInterval A boolean value indicating whether the keychain automatically locks after a certain period of time.
	@field lockInterval An unsigned 32-bit integer representing the number of seconds before the keychain locks.
*/
struct SecKeychainSettings
{
	UInt32		version;
	Boolean		lockOnSleep;
	Boolean		useLockInterval;
	UInt32		lockInterval;
};
typedef struct SecKeychainSettings		SecKeychainSettings;

/*!
	@enum AuthenticationConstants
	@abstract Defines constants you can use to identify the type of authentication to use for an Internet password.
	@constant kSecAuthenticationTypeNTLM Specifies Windows NT LAN Manager authentication.
	@constant kSecAuthenticationTypeMSN Specifies Microsoft Network default authentication.
	@constant kSecAuthenticationTypeDPA Specifies Distributed Password authentication.
	@constant kSecAuthenticationTypeRPA Specifies Remote Password authentication.
	@constant kSecAuthenticationTypeHTTPBasic Specifies HTTP Basic authentication.
	@constant kSecAuthenticationTypeHTTPDigest Specifies HTTP Digest Access authentication.
	@constant kSecAuthenticationTypeHTMLForm Specifies HTML form based authentication.
	@constant kSecAuthenticationTypeDefault Specifies the default authentication type.
	@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.
*/
#ifdef __LITTLE_ENDIAN__
#define AUTH_TYPE_FIX_(x) OSSwapConstInt32(x)
#else
#define AUTH_TYPE_FIX_(x) (x)
#endif

typedef CF_ENUM(FourCharCode, SecAuthenticationType)
{
    kSecAuthenticationTypeNTLM             = AUTH_TYPE_FIX_ ('ntlm'),
    kSecAuthenticationTypeMSN              = AUTH_TYPE_FIX_ ('msna'),
    kSecAuthenticationTypeDPA              = AUTH_TYPE_FIX_ ('dpaa'),
    kSecAuthenticationTypeRPA              = AUTH_TYPE_FIX_ ('rpaa'),
    kSecAuthenticationTypeHTTPBasic        = AUTH_TYPE_FIX_ ('http'),
    kSecAuthenticationTypeHTTPDigest       = AUTH_TYPE_FIX_ ('httd'),
    kSecAuthenticationTypeHTMLForm         = AUTH_TYPE_FIX_ ('form'),
    kSecAuthenticationTypeDefault          = AUTH_TYPE_FIX_ ('dflt'),
    kSecAuthenticationTypeAny              = AUTH_TYPE_FIX_ ( 0 )
};

/*!
	@enum ProtocolTypeConstants
	@abstract Defines the protocol type associated with an AppleShare or Internet password.
	@constant kSecProtocolTypeFTP Indicates FTP.
	@constant kSecProtocolTypeFTPAccount Indicates FTP Account (client side), usage deprecated.
	@constant kSecProtocolTypeHTTP Indicates HTTP.
	@constant kSecProtocolTypeIRC Indicates IRC.
	@constant kSecProtocolTypeNNTP Indicates NNTP.
	@constant kSecProtocolTypePOP3 Indicates POP3.
	@constant kSecProtocolTypeSMTP Indicates SMTP.
	@constant kSecProtocolTypeSOCKS Indicates SOCKS.
	@constant kSecProtocolTypeIMAP Indicates IMAP.
	@constant kSecProtocolTypeLDAP Indicates LDAP.
	@constant kSecProtocolTypeAppleTalk Indicates AFP over AppleTalk.
	@constant kSecProtocolTypeAFP Indicates AFP over TCP.
	@constant kSecProtocolTypeTelnet Indicates Telnet.
	@constant kSecProtocolTypeSSH Indicates SSH.
	@constant kSecProtocolTypeFTPS Indicates FTPS (FTP over TLS/SSL).
	@constant kSecProtocolTypeHTTPS Indicates HTTPS (HTTP over TLS/SSL).
	@constant kSecProtocolTypeHTTPProxy Indicates HTTP proxy.
	@constant kSecProtocolTypeHTTPSProxy Indicates HTTPS proxy.
	@constant kSecProtocolTypeFTPProxy Indicates FTP proxy.
	@constant kSecProtocolTypeSMB Indicates SMB.
	@constant kSecProtocolTypeRTSP Indicates RTSP.
	@constant kSecProtocolTypeRTSPProxy Indicates RTSP proxy.
	@constant kSecProtocolTypeDAAP Indicates DAAP.
	@constant kSecProtocolTypeEPPC Indicates EPPC (Remote Apple Events).
	@constant kSecProtocolTypeIPP Indicates IPP.
	@constant kSecProtocolTypeNNTPS Indicates NNTPS (NNTP over TLS/SSL).
	@constant kSecProtocolTypeLDAPS Indicates LDAPS (LDAP over TLS/SSL).
	@constant kSecProtocolTypeTelnetS Indicates Telnet over TLS/SSL.
	@constant kSecProtocolTypeIMAPS Indicates IMAPS (IMAP4 over TLS/SSL).
	@constant kSecProtocolTypeIRCS Indicates IRCS (IRC over TLS/SSL).
	@constant kSecProtocolTypePOP3S Indicates POP3S (POP3 over TLS/SSL).
	@constant kSecProtocolTypeCVSpserver Indicates CVS pserver.
	@constant kSecProtocolTypeSVN Indicates Subversion.
	@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.
*/
typedef CF_ENUM(FourCharCode, SecProtocolType)
{
    kSecProtocolTypeFTP         = 'ftp ',
    kSecProtocolTypeFTPAccount  = 'ftpa',
    kSecProtocolTypeHTTP        = 'http',
    kSecProtocolTypeIRC         = 'irc ',
    kSecProtocolTypeNNTP        = 'nntp',
    kSecProtocolTypePOP3        = 'pop3',
    kSecProtocolTypeSMTP        = 'smtp',
    kSecProtocolTypeSOCKS       = 'sox ',
    kSecProtocolTypeIMAP        = 'imap',
    kSecProtocolTypeLDAP        = 'ldap',
    kSecProtocolTypeAppleTalk   = 'atlk',
    kSecProtocolTypeAFP         = 'afp ',
    kSecProtocolTypeTelnet      = 'teln',
    kSecProtocolTypeSSH         = 'ssh ',
    kSecProtocolTypeFTPS        = 'ftps',
    kSecProtocolTypeHTTPS       = 'htps',
    kSecProtocolTypeHTTPProxy   = 'htpx',
    kSecProtocolTypeHTTPSProxy  = 'htsx',
    kSecProtocolTypeFTPProxy    = 'ftpx',
    kSecProtocolTypeCIFS        = 'cifs',
    kSecProtocolTypeSMB         = 'smb ',
    kSecProtocolTypeRTSP        = 'rtsp',
    kSecProtocolTypeRTSPProxy   = 'rtsx',
    kSecProtocolTypeDAAP        = 'daap',
    kSecProtocolTypeEPPC        = 'eppc',
    kSecProtocolTypeIPP         = 'ipp ',
    kSecProtocolTypeNNTPS       = 'ntps',
    kSecProtocolTypeLDAPS       = 'ldps',
    kSecProtocolTypeTelnetS     = 'tels',
    kSecProtocolTypeIMAPS       = 'imps',
    kSecProtocolTypeIRCS        = 'ircs',
    kSecProtocolTypePOP3S       = 'pops',
    kSecProtocolTypeCVSpserver  = 'cvsp',
    kSecProtocolTypeSVN         = 'svn ',
    kSecProtocolTypeAny         =  0
};

/*!
	@enum KeychainEventConstants
	@abstract Defines the keychain-related event.
	@constant kSecLockEvent Indicates a keychain was locked.
	@constant kSecUnlockEvent Indicates a keychain was unlocked.
	@constant kSecAddEvent Indicates an item was added to a keychain.
	@constant kSecDeleteEvent Indicates an item was deleted from a keychain.
	@constant kSecUpdateEvent Indicates a keychain item was updated.
	@constant kSecPasswordChangedEvent Indicates the keychain password was changed.
	@constant kSecDefaultChangedEvent Indicates that a different keychain was specified as the default.
	@constant kSecDataAccessEvent Indicates a process has accessed a keychain item's data.
	@constant kSecKeychainListChangedEvent Indicates the list of keychains has changed.
	@constant kSecTrustSettingsChangedEvent Indicates Trust Settings changed.
*/
typedef CF_ENUM(UInt32, SecKeychainEvent)
{
    kSecLockEvent                 = 1,
    kSecUnlockEvent               = 2,
    kSecAddEvent                  = 3,
    kSecDeleteEvent               = 4,
    kSecUpdateEvent               = 5,
    kSecPasswordChangedEvent      = 6,
    kSecDefaultChangedEvent       = 9,
    kSecDataAccessEvent __API_DEPRECATED("Read events are no longer posted", macos(10.10, 10.15)) = 10,
    kSecKeychainListChangedEvent  = 11,
	kSecTrustSettingsChangedEvent = 12
};

/*!
	@enum KeychainEventConstants
	@abstract Defines keychain event constants
	@constant kSecLockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is locked.
	@constant kSecUnlockEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain is unlocked.
	@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.
	@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.
	@constant kSecUpdateEventMask If the bit specified by this mask is set, your callback function will be invoked when a keychain item is updated.
	@constant kSecPasswordChangedEventMask If the bit specified by this mask is set, your callback function will be invoked when the keychain password is changed.
	@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.
	@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.
	@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.
	@constant kSecEveryEventMask If all the bits are set, your callback function will be invoked whenever any event occurs.
*/
typedef CF_OPTIONS(UInt32, SecKeychainEventMask)
{
    kSecLockEventMask            		= 1 << kSecLockEvent,
    kSecUnlockEventMask          		= 1 << kSecUnlockEvent,
    kSecAddEventMask             		= 1 << kSecAddEvent,
    kSecDeleteEventMask          		= 1 << kSecDeleteEvent,
    kSecUpdateEventMask          		= 1 << kSecUpdateEvent,
    kSecPasswordChangedEventMask 		= 1 << kSecPasswordChangedEvent,
    kSecDefaultChangedEventMask  		= 1 << kSecDefaultChangedEvent,
    kSecDataAccessEventMask __API_DEPRECATED("Read events are no longer posted", macos(10.10, 10.15)) = 1 << kSecDataAccessEvent,
    kSecKeychainListChangedMask  		= 1 << kSecKeychainListChangedEvent,
	kSecTrustSettingsChangedEventMask 	= 1 << kSecTrustSettingsChangedEvent,
    kSecEveryEventMask 			        = 0xffffffff
};

/*!
	@typedef SecKeychainCallbackInfo
	@abstract Contains information about a keychain event.
	@field version The version of this structure.
	@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.
	@field keychain A reference to the keychain in which the event occurred.
	@field pid The id of the process that generated this event.
	@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.
*/
struct API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst) SecKeychainCallbackInfo
{
    UInt32                          version;
    SecKeychainItemRef __nonnull	item;
    SecKeychainRef __nonnull		keychain;
	pid_t                           pid;
};
typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);

/*!
	@function SecKeychainGetTypeID
	@abstract Returns the type identifier of SecKeychain instances.
	@result The CFTypeID of SecKeychain instances.
*/
CFTypeID SecKeychainGetTypeID(void);

/*!
	@function SecKeychainGetVersion