Keychain/SecKeychainAPI.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 /*
  20  *  SecKeychainAPI.h
  21  *  SecurityCore
  22  *
  23  *    Copyright:  (c) 2000 by Apple Computer, Inc., all rights reserved
  24  *
  25  */
  26
  27 /*!
  28         @header SecKeychainAPI The Security Core API contains all the APIs need to create a Keychain management application, minus the HI.
  29
  30         NOTE: Any function with Create or Copy in the name returns an object that must be released.
  31 */
  32
  33 #if !defined(__SECKEYCHAINAPI__)
  34 #define __SECKEYCHAINAPI__ 1
  35
  36 #include <CoreServices/../Frameworks/CarbonCore.framework/Headers/MacTypes.h>
  37 #include <Security/cssmapple.h>
  38
  39
  40 #if defined(__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44 #ifndef __SEC_TYPES__
  45 #define __SEC_TYPES__
  46
  47 /*!
  48 @typedef SecKeychainRef
  49 Opaque Structure to a Keychain reference.
  50 */
  51 typedef struct OpaqueSecKeychainRef                             *SecKeychainRef;
  52 /*!
  53 @typedef SecKeychainItemRef
  54 Opaque Structure to a Keychain item reference.
  55 */
  56 typedef struct OpaqueSecKeychainItemRef                 *SecKeychainItemRef;
  57 /*!
  58 @typedef SecKeychainSearchRef
  59 Opaque Structure to a Keychain search reference.
  60 */
  61 typedef struct OpaqueSecKeychainSearchRef               *SecKeychainSearchRef;
  62
  63 typedef OSType  SecKeychainAttrType;
  64 /*!
  65 @struct SecKeychainAttribute
  66 Security Item attributes.
  67 */
  68 struct SecKeychainAttribute {
  69     SecKeychainAttrType          tag;                            /* 4-byte attribute tag */
  70     UInt32                       length;                         /* Length of attribute data */
  71     void *                       data;                           /* Pointer to attribute data */
  72 };
  73 typedef struct SecKeychainAttribute      SecKeychainAttribute;
  74 typedef SecKeychainAttribute *           SecKeychainAttributePtr;
  75
  76 /*!
  77 @struct SecKeychainAttributeList
  78 Security attribute list.
  79 */
  80 struct SecKeychainAttributeList {
  81     UInt32                                       count;                          /* How many attributes in the array */
  82     SecKeychainAttribute *               attr;                           /* Pointer to first attribute in array */
  83 };
  84 typedef struct SecKeychainAttributeList  SecKeychainAttributeList;
  85
  86 typedef UInt32 SecKeychainStatus;
  87
  88 #endif
  89
  90 /*!
  91 @enum TableIDs
  92 */
  93 enum {
  94     kSecGenericPasswordItemTableID = CSSM_DL_DB_RECORD_GENERIC_PASSWORD,                  /* Generic password */
  95     kSecInternetPasswordItemTableID = CSSM_DL_DB_RECORD_INTERNET_PASSWORD,                /* Internet password */
  96     kSecAppleSharePasswordItemTableID = CSSM_DL_DB_RECORD_APPLESHARE_PASSWORD             /* AppleShare password */
  97 };
  98
  99 /*!
 100 @struct SecKeychainAttributeInfo
 101 Security attribute tag list.
 102 */
 103 struct SecKeychainAttributeInfo {
 104     UInt32                                       count;                                  /* How many items in the array */
 105     UInt32 *                                             tag;                            /* Pointer to first attribute tag in array */
 106         UInt32 *                                         format;                         /* Pointer to first attribute format in array */
 107 };
 108 typedef struct SecKeychainAttributeInfo  SecKeychainAttributeInfo;
 109
 110
 111
 112 /*!
 113 @typedef SecTypeRef
 114 Opaque pointer to one a pointer to a security referece.
 115 Such as SecKeychainSearchRef, SecKeychainItemRef and SecKeychainItemRef.
 116 */
 117 typedef void                                                                    *SecTypeRef;
 118
 119 /*!
 120 @enum KeychainErrors
 121 */
 122 enum {
 123     errSecNotAvailable           = -25291,
 124     errSecReadOnly               = -25292,
 125     errSecAuthFailed             = -25293,
 126     errSecNoSuchKeychain         = -25294,
 127     errSecInvalidKeychain        = -25295,
 128     errSecDuplicateKeychain      = -25296,
 129     errSecDuplicateCallback      = -25297,
 130     errSecInvalidCallback        = -25298,
 131     errSecDuplicateItem          = -25299,
 132     errSecItemNotFound           = -25300,
 133     errSecBufferTooSmall         = -25301,
 134     errSecDataTooLarge           = -25302,
 135     errSecNoSuchAttr             = -25303,
 136     errSecInvalidItemRef         = -25304,
 137     errSecInvalidSearchRef       = -25305,
 138     errSecNoSuchClass            = -25306,
 139     errSecNoDefaultKeychain      = -25307,
 140     errSecInteractionNotAllowed  = -25308,
 141     errSecReadOnlyAttr           = -25309,
 142     errSecWrongSecVersion        = -25310,
 143     errSecKeySizeNotAllowed      = -25311,
 144     errSecNoStorageModule        = -25312,
 145     errSecNoCertificateModule    = -25313,
 146     errSecNoPolicyModule         = -25314,
 147     errSecInteractionRequired    = -25315,
 148     errSecDataNotAvailable       = -25316,
 149     errSecDataNotModifiable      = -25317,
 150     errSecCreateChainFailed      = -25318
 151 };
 152
 153 /*!
 154 @enum KeychainEvents
 155 Events relating to the state of the default Keychain.
 156 */
 157 typedef UInt16 SecKeychainEvent;
 158 enum {
 159     kSecLockEvent                = 1,                            /* a keychain was locked */
 160     kSecUnlockEvent              = 2,                            /* a keychain was unlocked */
 161     kSecAddEvent                 = 3,                            /* an item was added to a keychain */
 162     kSecDeleteEvent              = 4,                            /* an item was deleted from a keychain */
 163     kSecUpdateEvent              = 5,                            /* an item was updated */
 164     kSecPasswordChangedEvent     = 6,                            /* the keychain password was changed */
 165     kSecSystemEvent              = 8,                            /* the keychain client can process events */
 166     kSecDefaultChangedEvent      = 9,                            /* the default keychain was changed */
 167     kSecDataAccessEvent          = 10,                           /* a process has accessed a keychain item's data */
 168     kSecKeychainListChangedEvent = 11                            /* the list of keychains has changed */
 169 };
 170
 171
 172 typedef UInt16 SecKeychainEventMask;
 173 enum {
 174     kSecLockEventMask            = 1 << kSecLockEvent,
 175     kSecUnlockEventMask          = 1 << kSecUnlockEvent,
 176     kSecAddEventMask             = 1 << kSecAddEvent,
 177     kSecDeleteEventMask          = 1 << kSecDeleteEvent,
 178     kSecUpdateEventMask          = 1 << kSecUpdateEvent,
 179     kSecPasswordChangedEventMask = 1 << kSecPasswordChangedEvent,
 180     kSecSystemEventEventMask     = 1 << kSecSystemEvent,
 181     kSecDefaultChangedEventMask  = 1 << kSecDefaultChangedEvent,
 182     kSecDataAccessEventMask      = 1 << kSecDataAccessEvent,
 183     kSecEveryEventMask           = 0xFFFF                        /* all of the above*/
 184 };
 185
 186 typedef UInt8                    SecAFPServerSignature[16];
 187 typedef UInt8                    SecPublicKeyHash[20];
 188
 189 /*!
 190 @enum KeychainStatus
 191 The current status of the Keychain.
 192 */
 193 enum {
 194     kSecUnlockStateStatus        = 1,
 195     kSecRdPermStatus             = 2,
 196     kSecWrPermStatus             = 4
 197 };
 198
 199 typedef FourCharCode             SecItemClass;
 200 /*!
 201 @enum KeychainItemClasses
 202 Keychain item classes
 203 */
 204
 205 enum {
 206     kSecInternetPasswordItemClass = 'inet',                   /* Internet password */
 207     kSecGenericPasswordItemClass = 'genp',                    /* Generic password */
 208     kSecAppleSharePasswordItemClass = 'ashp'                  /* AppleShare password */
 209 };
 210
 211
 212 /*!
 213 @enum FourCharacterCodes
 214 */
 215 enum {
 216                                                                  /* Common attributes */
 217     kSecCreationDateItemAttr     = 'cdat',                       /* Date the item was created (UInt32) */
 218     kSecModDateItemAttr          = 'mdat',                       /* Last time the item was updated (UInt32) */
 219     kSecDescriptionItemAttr      = 'desc',                       /* User-visible description string (string) */
 220     kSecCommentItemAttr          = 'icmt',                       /* User's comment about the item (string) */
 221     kSecCreatorItemAttr          = 'crtr',                       /* Item's creator (OSType) */
 222     kSecTypeItemAttr             = 'type',                       /* Item's type (OSType) */
 223     kSecScriptCodeItemAttr       = 'scrp',                       /* Script code for all strings (ScriptCode) */
 224     kSecLabelItemAttr            = 'labl',                       /* Item label (string) */
 225     kSecInvisibleItemAttr        = 'invi',                       /* Invisible (boolean) */
 226     kSecNegativeItemAttr         = 'nega',                       /* Negative (boolean) */
 227     kSecCustomIconItemAttr       = 'cusi',                       /* Custom icon (boolean) */
 228                                                                  /* Unique Generic password attributes */
 229     kSecAccountItemAttr          = 'acct',                       /* User account (string) - also applies to Appleshare and Generic */
 230     kSecServiceItemAttr          = 'svce',                       /* Service (string) */
 231     kSecGenericItemAttr          = 'gena',                       /* User-defined attribute (untyped bytes) */
 232                                                                  /* Unique Internet password attributes */
 233     kSecSecurityDomainItemAttr   = 'sdmn',                       /* urity domain (string) */
 234     kSecServerItemAttr           = 'srvr',                       /* Server's domain name or IP address (string) */
 235     kSecAuthTypeItemAttr         = 'atyp',                       /* Authentication Type (AuthType) */
 236     kSecPortItemAttr             = 'port',                       /* Port (UInt32) */
 237     kSecPathItemAttr             = 'path',                       /* Path (string) */
 238                                                                  /* Unique Appleshare password attributes */
 239     kSecVolumeItemAttr           = 'vlme',                       /* Volume (string) */
 240     kSecAddressItemAttr          = 'addr',                       /* Server address (IP or domain name) or zone name (string) */
 241     kSecSignatureItemAttr        = 'ssig',                       /* Server signature block (AFPServerSignature) */
 242                                                                  /* Unique AppleShare and Internet attributes */
 243     kSecProtocolItemAttr         = 'ptcl',                       /* Protocol (ProtocolType) */
 244
 245 };
 246
 247 typedef FourCharCode SecItemAttr;
 248
 249
 250 /*!
 251 @enum SecurityAuthTypeCodes
 252 */
 253 enum {
 254     kSecAuthTypeNTLM             = 'ntlm',
 255     kSecAuthTypeMSN              = 'msna',
 256     kSecAuthTypeDPA              = 'dpaa',
 257     kSecAuthTypeRPA              = 'rpaa',
 258     kSecAuthTypeHTTPDigest       = 'httd',
 259     kSecAuthTypeDefault          = 'dflt'
 260 };
 261 typedef FourCharCode             SecAuthType;
 262
 263 /*!
 264 @enum SecurityProtocolTypeCodes
 265 */
 266 enum {
 267     kSecProtocolTypeFTP          = 'ftp ',
 268     kSecProtocolTypeFTPAccount   = 'ftpa',
 269     kSecProtocolTypeHTTP         = 'http',
 270     kSecProtocolTypeIRC          = 'irc ',
 271     kSecProtocolTypeNNTP         = 'nntp',
 272     kSecProtocolTypePOP3         = 'pop3',
 273     kSecProtocolTypeSMTP         = 'smtp',
 274     kSecProtocolTypeSOCKS        = 'sox ',
 275     kSecProtocolTypeIMAP         = 'imap',
 276     kSecProtocolTypeLDAP         = 'ldap',
 277     kSecProtocolTypeAppleTalk    = 'atlk',
 278     kSecProtocolTypeAFP          = 'afp ',
 279     kSecProtocolTypeTelnet       = 'teln'
 280 };
 281 typedef FourCharCode             SecProtocolType;
 282
 283 /*!
 284 @typedef KCChangeSettingsInfo
 285 Keychain Settings
 286 */
 287 struct SecKeychainSettings
 288 {
 289         UInt32                                  version;
 290         Boolean                         lockOnSleep;
 291         Boolean                         useLockInterval;
 292         UInt32                          lockInterval;
 293 };
 294 typedef struct SecKeychainSettings              SecKeychainSettings;
 295
 296 #define SEC_KEYCHAIN_SETTINGS_VERS1 1
 297
 298 struct SecKeychainCallbackInfo
 299 {
 300     UInt32                                                              version;
 301     SecKeychainItemRef                                  item;
 302     long                                                                processID[2];
 303     long                                                                event[4];
 304     SecKeychainRef                                              keychain;
 305 };
 306 typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo;
 307
 308
 309 /*!
 310     @function SecKeychainGetVersion
 311     Returns the version of the Keychain Manager (an unsigned 32-bit integer) in version.
 312
 313     @param returnVers Pointer to a UNInt32 to receive the version number.
 314     @result noErr 0 No error.
 315             errSecNotAvailable -25291 Keychain Manager was not loaded.
 316 */
 317 OSStatus SecKeychainGetVersion(UInt32 *returnVers);
 318
 319 /*!
 320     @function SecKeychainOpen
 321     Returns a referenece to the keychain specified by keychainFile.
 322     The memory that keychain occupies must be released by calling SecKeychainRelease when finished
 323     with it.
 324
 325     @param pathName A posix path to the keychain file.
 326     @param keychainRef Returned keychain reference.
 327     @result noErr 0 No error.
 328             paramErr -50 The keychain parameter is invalid (NULL).
 329 */
 330 OSStatus SecKeychainOpen(const char *pathName, SecKeychainRef *keychainRef);
 331
 332 /*!
 333         @function SecKeychainCreateNew
 334     Returns a referenece to the keychain specified by keychainFile.
 335     The memory that keychain occupies must be released by calling SecKeychainRelease when finished
 336     with it.
 337
 338     @param pathName A posix path to the keychain file.
 339     @param promptUser Display a password dialog to the user.
 340     @param keychainRef Returned keychain reference.
 341     @param passwordLength Max length of the password buffer.
 342     @param password A pointer to buffer with the password.  Must be in canonical UTF8 encoding.
 343     @result noErr 0 No error.
 344             paramErr -50 The keychain parameter is invalid (NULL).
 345 */
 346 OSStatus SecKeychainCreateNew(const char *pathName, SecKeychainRef *keychainRef, UInt32 passwordLength, const void *password, Boolean promptUser);
 347
 348 /*!
 349         @function SecKeychainDelete
 350     Deletes a the keychain specified by keychainRef.
 351
 352     @param keychainRef keychain to delete reference.
 353     @result noErr 0 No error.
 354             paramErr -50 The keychain parameter is invalid (NULL).
 355 */
 356 OSStatus SecKeychainDelete(SecKeychainRef keychainRef);
 357
 358 /*!
 359         @function SecKeychainSetSettings
 360         Changes the settings of keychain including the lockOnSleep, useLockInterval and lockInterval.
 361
 362     @param keychainRef keychain reference of the keychain to set.
 363         @param newSettings A SecKeychainSettings structure pointer.
 364     @result noErr 0 No error.
 365 */
 366 OSStatus SecKeychainSetSettings(SecKeychainRef keychainRef, const SecKeychainSettings *newSettings);
 367
 368 /*!
 369         @function SecKeychainCopySettings
 370         Copy the settings of keychain including the lockOnSleep, useLockInterval and lockInterval.  Because this structure is versioned
 371         the caller is required to preallocate it and fill in the version of the structure.
 372
 373     @param keychainRef keychain reference of the keychain settings to copy.
 374     @param outSettings  A SecKeychainSettings structure pointer.
 375         @result noErr 0 No error.
 376 */
 377 OSStatus SecKeychainCopySettings(SecKeychainRef keychainRef, SecKeychainSettings *outSettings);
 378
 379 /*!
 380         @function SecKeychainUnlock
 381         Unlocks the specified keychain.
 382
 383     @param keychainRef A reference to the keychain to be unlocked.
 384         @param passwordLength The length of the password buffer.
 385         @param password A buffer with the password for the keychain.
 386         @param usePassword By setting this flag the password parameter is either used or ignored.
 387     @result noErr 0 No error.
 388 */
 389 OSStatus SecKeychainUnlock(SecKeychainRef keychainRef, UInt32 passwordLength, void *password, Boolean usePassword);
 390
 391 /*!
 392         @function SecKeychainLock
 393         Locks the specified keychain.
 394
 395     @param keychainRef A reference to the keychain to be Locked.
 396     @result noErr 0 No error.
 397 */
 398 OSStatus SecKeychainLock(SecKeychainRef keychainRef);
 399
 400 /*!
 401         @function SecKeychainLockAll
 402         Locks all keychains.
 403
 404     @result noErr 0 No error.
 405 */
 406 OSStatus SecKeychainLockAll();
 407
 408 /*!
 409         @function SecKeychainCopyDefault
 410         This routine returns a SecKeychainRef which specifies the default keychain. Your application
 411         might call this routine to obtain the name and location of the default keychain.
 412
 413         @param SecKeychainRef A pointer to a reference of the default keychain.
 414         @result noErr 0 No error.
 415                         errSecNoDefaultKeychain -25307 There is no currently default keychain.
 416 */
 417 OSStatus SecKeychainCopyDefault(SecKeychainRef *keychainRef);
 418
 419 /*!
 420         @function SecKeychainSetDefault
 421         This routine sets the default keychain to the keychain specified by keychain.
 422
 423         @param SecKeychainRef A pointer to a reference of the default keychain.
 424     @result noErr 0 No error.
 425         paramErr -50 The input specification parameter was NULL.
 426         errSecNoSuchKeychain -25294 The specified keychain could not be found.
 427         errSecInvalidKeychain -25295 The specified keychain is invalid
 428 */
 429 OSStatus SecKeychainSetDefault(SecKeychainRef keychainRef);
 430
 431 /*!
 432         @function SecKeychainGetStatus
 433
 434         Returns status information for the specified keychain in the supplied parameter. If keychain is NULL,
 435         the status of the default keychain is returned.
 436
 437         The value returned in keychainStatus is a 32-bit field, the meaning of which must be determined
 438         by comparison with a list of predefined constants.
 439
 440         Currently defined bitmask values are:
 441                 kSecUnlockStateStatus   1 The specified keychain is unlocked if bit 0 is set.
 442                 kSecRdPermStatus                2 The specified keychain is unlocked with read permission if bit 1 is set.
 443                 kSecWrPermStatus                4 The specified keychain is unlocked with write permission if bit 2 is set.
 444
 445         @param keychainRef Pointer to a keychain reference (NULL specifies the default keychain).
 446         @param keychainRefStatus Returned status of the specified keychain.
 447
 448     @result noErr 0 No error.
 449                         errSecNoSuchKeychain -25294 The specified keychain could not be found.
 450                         errSecInvalidKeychain -25295 The specified keychain is invalid.
 451 */
 452 OSStatus SecKeychainGetStatus(SecKeychainRef keychainRef, SecKeychainStatus* keychainStatus);
 453
 454 /*!
 455         @function SecKeychainRelease
 456         Releases  keychain item references
 457
 458         @param keychainRef A keychain  reference to release.
 459     @result noErr 0 No error.
 460 */
 461 OSStatus SecKeychainRelease(SecKeychainRef itemRef);
 462
 463 /*!
 464         @function SecKeychainGetPath
 465         Get the path location of the specified keychain.
 466     @param keychainRef A reference to a keychain.
 467     @param ioPathLength On input specifies the size or the buffer pointed to by path and on output the length of the buffer
 468                         (without the zero termination which is added)
 469         @param pathName A posix path to the receive keychain filename.
 470     @result noErr 0 No error.
 471 */
 472 OSStatus SecKeychainGetPath(SecKeychainRef keychainRef, UInt32 *ioPathLength, char *pathName);
 473
 474 /*!
 475         @function SecKeychainListGetCount
 476         This function returns the number of available keychains. This number includes all keychains within
 477         the "Keychains" folder, as well as any other keychains known to the Keychain Manager.
 478     @result the number of keychains.
 479 */
 480 UInt16 SecKeychainListGetCount(void);
 481
 482 /*!
 483         @function SecKeychainListCopyKeychainAtIndex
 484         This routine to copies a keychain item from the default keychain to another.
 485         @param index The index of the item to copy.
 486         @param keychainRef A keychain reference of the destination keychain.
 487         @result noErr 0 No error.
 488                         errSecInvalidKeychain -25295 The specified destination keychain was invalid.
 489                         errSecReadOnly -25292 The destination keychain is read only.
 490                         errSecNoSuchClass -25306 item has an invalid keychain item class.
 491 */
 492 OSStatus SecKeychainListCopyKeychainAtIndex(UInt16 index, SecKeychainRef *keychainRef);
 493
 494 /*!
 495         @function SecKeychainItemCreateFromContent
 496         Creates a new keychain item from the supplied parameters. A reference to the newly-created
 497         item is returned in item. A copy of the data buffer pointed to by data is stored in the item.
 498         When the item reference is no longer required, call SecKeychainRelease to deallocate memory occupied
 499         by the item.
 500
 501         @param itemRefClass A constant identifying the class of item to be created.
 502         @param attrList The list of attributes of the item to be created.
 503         @param length Length of the data to be stored in this item.
 504         @param data Pointer to a buffer containing the data to be stored in this item.
 505     @param keychain to add the item to.
 506         @param itemRef A reference to the newly created keychain item (optional).
 507     @result noErr 0 No error.
 508                         paramErr -50 Not enough valid parameters were supplied.
 509                         memFullErr -108 Not enough memory in current heap zone to create the object.
 510 */
 511 OSStatus SecKeychainItemCreateFromContent(SecItemClass itemClass, SecKeychainAttributeList *attrList, UInt32 length, const void *data, SecKeychainRef keychainRef, SecKeychainItemRef *itemRef);
 512
 513 /*!
 514         @function SecKeychainItemModifyContent
 515         This routine to update an existing keychain item after changing its attributes or data. The item is
 516         written to the keychain's permanent data store. If item has not previously been added to a keychain,
 517         SecKeychainItemModifyContent does nothing and returns noErr.
 518
 519         @param itemRef A reference of the keychain item to be modified.
 520         @param attrList The list of attributes to be set in this item.
 521         @param length Length of the data to be stored in this item.
 522         @param data Pointer to a buffer containing the data to be stored in this item.
 523     @result noErr 0 No error.
 524                         errSecNoDefaultKeychain -25307 No default keychain could be found.
 525                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 526 */
 527 OSStatus SecKeychainItemModifyContent(SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data);
 528
 529 /*!
 530         @function SecKeychainItemCopyContent
 531         Use this function to retrieve the data and/or attributes stored in the given keychain item.
 532
 533         You must call SecKeychainItemFreeContent when you no longer need the attributes and data.
 534
 535         @param itemRef A reference of the keychain item to be modified.
 536         @param itemClass The items class.  Pass NULL if not required.
 537         @param attrList The list of attributes to get in this item on input, on output the attributes are filled in.
 538         @param length on output the actual length of the data.
 539         @param outData Pointer to a buffer containing the data in this item.  Pass NULL if not required.
 540
 541     @result noErr 0 No error.
 542                         paramErr -50 Not enough valid parameters were supplied.
 543                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 544                         errSecBufferTooSmall -25301 The data was too large for the supplied buffer.
 545                         errSecDataNotAvailable -25316 The data is not available for this item.
 546 */
 547 OSStatus SecKeychainItemCopyContent(SecKeychainItemRef itemRef, SecItemClass *itemClass, SecKeychainAttributeList *attrList, UInt32 *length, void **outData);
 548
 549 /*!
 550         @function SecKeychainItemFreeContent
 551 */
 552 OSStatus SecKeychainItemFreeContent(SecKeychainAttributeList *attrList, void *data);
 553
 554 /*!
 555         @function SecKeychainAttributeInfoForItemID
 556         This will allow clients to obtain the tags for all possible attrs for that item class. User should call SecKeychainFreeAttributeInfo to
 557         release the structure when done with it.
 558
 559         Warning, this call returns more attributes than are support by the old style Keychain API and passing them inro older calls will
 560         yield an invalid attribute error.  The recommended call to retrieve the attribtute values is SecKeychainItemCopyAttributesAndData.
 561
 562     @param keychainRef A reference to the keychain.
 563         @param itemID the relation ID of the item tags
 564         @param info a pointer to a SecKeychainAttributeInfo structure
 565
 566     @result noErr 0 No error.
 567                         paramErr -50 Not enough valid parameters were supplied.
 568 */
 569 OSStatus SecKeychainAttributeInfoForItemID(SecKeychainRef keychainRef,  UInt32 itemID, SecKeychainAttributeInfo **info);
 570
 571 /*!
 572         @function SecKeychainFreeAttributeInfo
 573         This function free the memory aquired during the SecKeychainAttributeInfoForItemID call.
 574
 575         @param Info a pointer to a SecKeychainAttributeInfo structure
 576
 577     @result noErr 0 No error.
 578                         paramErr -50 Not enough valid parameters were supplied.
 579 */
 580 OSStatus SecKeychainFreeAttributeInfo(SecKeychainAttributeInfo *info);
 581
 582 /*!
 583         @function SecKeychainItemModifyContent
 584         This routine to update an existing keychain item after changing its attributes or data. The item is
 585         written to the keychain's permanent data store. If item has not previously been added to a keychain,
 586         SecKeychainItemModifyContent does nothing and returns noErr.
 587
 588         @param itemRef A reference of the keychain item to be modified.
 589         @param attrList The list of attributes to be set in this item.
 590         @param length Length of the data to be stored in this item.
 591         @param data Pointer to a buffer containing the data to be stored in this item.
 592     @result noErr 0 No error.
 593                         errSecNoDefaultKeychain -25307 No default keychain could be found.
 594                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 595 */
 596 OSStatus SecKeychainItemModifyAttributesAndData(SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data);
 597
 598
 599 /*!
 600         @function SecKeychainItemCopyAttributesAndData
 601         Use this function to retrieve the data and/or attributes stored in the given keychain item.
 602
 603         You must call SecKeychainItemFreeAttributesAndData when you no longer need the attributes and data.
 604
 605         @param itemRef A reference of the keychain item to be modified.
 606         @param info List of tags of attributes to retrieve.
 607         @param itemClass The items class.  Pass NULL if not required.
 608         @param attrList The list of attributes to get in this item on input, on output the attributes are filled in.
 609         @param length on output the actual length of the data.
 610         @param outData Pointer to a buffer containing the data in this item.  Pass NULL if not required.
 611
 612     @result noErr 0 No error.
 613                         paramErr -50 Not enough valid parameters were supplied.
 614                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 615                         errSecBufferTooSmall -25301 The data was too large for the supplied buffer.
 616                         errSecDataNotAvailable -25316 The data is not available for this item.
 617 */
 618 OSStatus SecKeychainItemCopyAttributesAndData(SecKeychainItemRef itemRef, SecKeychainAttributeInfo *info, SecItemClass *itemClass, SecKeychainAttributeList **attrList, UInt32 *length, void **outData);
 619
 620 /*!
 621         @function SecKeychainItemFreeAttributesAndData
 622         Use this function to release the data and/or attributes returned by the SecKeychainItemCopyAttributesAndData function.
 623
 624         @param info List of tags of attributes to retrieve.
 625
 626     @result noErr 0 No error.
 627 */
 628 OSStatus SecKeychainItemFreeAttributesAndData(SecKeychainAttributeList *attrList, void *data);
 629
 630 /*!
 631         @function SecKeychainItemDelete
 632         Use this routine to delete a keychain item from the default keychain's permanent data store. If itemRef
 633         has not previously been added to the keychain, SecKeychainItemDelete does nothing and returns noErr.
 634         IMPORTANT: SecKeychainItemDelete does not dispose the memory occupied by the item reference itself;
 635         use SecKeychainItemRelease when you are completely finished with an item.
 636
 637         @param itemRef A keychain item reference of the item to be deleted.
 638     @result noErr 0 No error.
 639                         errSecNoDefaultKeychain -25307 No default keychain could be found.
 640                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 641 */
 642 OSStatus SecKeychainItemDelete(SecKeychainItemRef itemRef);
 643
 644 /*!
 645         @function SecKeychainItemCopyKeychain
 646         Use this routine to copy an existing keychain reference from a keychain item.
 647
 648         @param itemRef A keychain item reference of the item to be updated.
 649         @param keychainRef A pointer to a keychain reference returned.  Release this by calling
 650            SecKeychainRelease().
 651     @result noErr 0 No error.
 652                         errSecInvalidItemRef -25304 The specified keychain item reference was invalid.
 653 */
 654 OSStatus SecKeychainItemCopyKeychain(SecKeychainItemRef itemRef, SecKeychainRef* keychainRef);
 655
 656
 657 /*!
 658         @function SecKeychainItemCreateCopy
 659         Use this routine to copy a keychain item. The copy will be returned in itemCopy.
 660
 661         @param itemRef A keychain item reference to copy.
 662         @param itemCopy The new copied item.
 663     @result noErr 0 No error.
 664                         errSecInvalidKeychain -25295 The specified destKeychain was invalid.
 665                         errSecReadOnly -25292 The destKeychain is read only.
 666                         errSecNoSuchClass -25306 item has an invalid keychain item class.
 667 */
 668 OSStatus SecKeychainItemCreateCopy(SecKeychainItemRef itemRef, SecKeychainItemRef *itemCopy, SecKeychainRef destKeychainRef);
 669
 670 /*!
 671         @function SecKeychainItemRelease
 672         Releases  keychain item references
 673
 674         @param itemRef A keychain item reference to release.
 675     @result noErr 0 No error.
 676 */
 677 OSStatus SecKeychainItemRelease(SecKeychainItemRef itemRef);
 678
 679 /*!
 680         @function SecKeychainSearchCreateFromAttributes
 681         Creates a search reference matching a list of zero or more specified attributes in the specified keychain
 682         and returns a reference to the item. Pass NULL for keychain if you wish to search all unlocked
 683         keychains. The caller is responsible for calling SecKeychainSearchRelease to release this reference
 684         when finished with it. A reference to the current search criteria is also returned, for subsequent calls to
 685         SecKeychainCopySearchNextItem. This reference must be released by the caller when completely finished with a
 686         search by calling SecKeychainSearchRelease.
 687
 688         @param keychainRef The keychain to search (NULL means search all unlocked keychains)
 689         @param attrList A list of zero or more SecKeychainAttribute records to be matched
 690                                         (NULL matches any keychain item).
 691         @param searchRef A reference to the current search is returned here.
 692
 693     @result noErr 0 No error.
 694                         errSecNoDefaultKeychain -25307 No default keychain could be found.
 695                         errSecItemNotFound -25300 No matching keychain item was found.
 696                         errSecNoSuchAttr -25303 Specified an attribute which is undefined for this item class.
 697 */
 698 OSStatus SecKeychainSearchCreateFromAttributes(SecKeychainRef keychainRef, SecItemClass itemClass, const SecKeychainAttributeList *attrList, SecKeychainSearchRef *searchRef);
 699
 700 /*!
 701         @function SecKeychainCopySearchNextItem
 702         Finds the next keychain item matching the given search criteria, as previously specified by a call to
 703         SecKeychainSearchCreateFromAttributes, and returns a reference to the item. The caller is responsible for releasing
 704         this reference when finished with it.
 705
 706         @param searchRef A reference to the current search criteria.
 707         @param itemRef A reference to the next matching keychain item, if any, is returned here.
 708     @result noErr 0 No error.
 709                         errSecNoDefaultKeychain -25307 No default keychain could be found.
 710                         errSecInvalidSearchRef -25305 The specified search reference was invalid.
 711                         errSecItemNotFound -25300 No more matching keychain items were found.
 712 */
 713 OSStatus SecKeychainCopySearchNextItem(SecKeychainSearchRef searchRef, SecKeychainItemRef *itemRef);
 714
 715 /*!
 716         @function SecKeychainSearchRelease
 717         Releases a keychain search reference.
 718
 719         @param searchRef A reference to the search reference.
 720         @result noErr 0 No error.
 721 */
 722 OSStatus SecKeychainSearchRelease(SecKeychainSearchRef searchRef);
 723
 724
 725 /*!
 726         @function SecKeychainListRemoveKeychain
 727         Removed the specified keychain from the list of availible keychains.
 728
 729         @param keychainRef A reference to the keychain to be removed.
 730     @result noErr 0 No error.
 731 */
 732 OSStatus SecKeychainListRemoveKeychain(SecKeychainRef *keychainRef);
 733
 734 // Keychain Callback mgr stuff
 735 typedef OSStatus (*SecKeychainCallbackProcPtr)(SecKeychainEvent keychainEvent, SecKeychainCallbackInfo* info, void *context);
 736
 737
 738 /*!
 739         @function SecKeychainAddCallback
 740         Add a callback.
 741
 742         @param callbackFunction The callback function pointer to add
 743         @param eventMask
 744         @param userContext
 745     @result noErr 0 No error.
 746 */
 747 OSStatus SecKeychainAddCallback(SecKeychainCallbackProcPtr callbackFunction, SecKeychainEventMask eventMask, void* userContext);
 748
 749
 750 /*!
 751         @function SecKeychainRemoveCallback
 752         Remove a callback.
 753
 754         @param callbackFunction The callback function pointer to remove
 755         @result noErr 0 No error.
 756 */
 757 OSStatus SecKeychainRemoveCallback(SecKeychainCallbackProcPtr callbackFunction);
 758
 759
 760 /*!
 761         @function SecKeychainAddInternetPassword
 762         Add an internet password to the specified keychain.
 763
 764         @param keychainRef
 765         @param serverNameLength
 766         @param serverName
 767         @param securityDomainLength
 768         @param securityDomain
 769         @param accountNameLength
 770         @param accountName
 771         @param pathLength
 772         @param path
 773         @param port
 774         @param protocol
 775         @param authType
 776         @param passwordLength
 777         @param passwordData
 778         @param itemRef
 779
 780         @result noErr 0 No error.
 781 */
 782 OSStatus SecKeychainAddInternetPassword(SecKeychainRef keychainRef, UInt32 serverNameLength, char *serverName,
 783                                                                                 UInt32 securityDomainLength, char *securityDomain, UInt32 accountNameLength, char *accountName,
 784                                                                                 UInt32 pathLength, char *path, UInt16 port, OSType protocol, OSType authType,
 785                                                                                 UInt32 passwordLength, const void *passwordData, SecKeychainItemRef *itemRef);
 786
 787
 788 /*!
 789         @function SecKeychainFindInternetPassword
 790         Find an internet password
 791
 792         @param keychainRef
 793         @param serverNameLength
 794         @param serverName
 795         @param securityDomainLength
 796         @param securityDomain
 797         @param accountNameLength
 798         @param accountName
 799         @param pathLength
 800         @param path
 801         @param port
 802         @param protocol
 803         @param authType
 804         @param passwordLength
 805         @param passwordData
 806         @param itemRef
 807
 808         @result noErr 0 No error.
 809 */
 810 OSStatus SecKeychainFindInternetPassword(SecKeychainRef keychainRef, UInt32 serverNameLength, char *serverName,
 811                                                                                 UInt32 securityDomainLength, char *securityDomain, UInt32 accountNameLength, char *accountName,
 812                                                                                 UInt32 pathLength, char *path, UInt16 port, OSType protocol, OSType authType,
 813                                                                                 UInt32 *passwordLength, void **passwordData, SecKeychainItemRef *itemRef);
 814
 815
 816 /*!
 817         @function SecKeychainAddGenericPassword
 818         Add an generic password to the specified keychain.
 819
 820         @param  keychainRef
 821         @param serviceNameLength
 822         @param serviceName
 823         @param accountNameLength
 824         @param accountName
 825         @param passwordData
 826         @param passwordLength
 827         @param itemRef
 828
 829         @result noErr 0 No error.
 830 */
 831 OSStatus SecKeychainAddGenericPassword(SecKeychainRef keychainRef, UInt32 serviceNameLength, char *serviceName,
 832                                                                            UInt32 accountNameLength, char *accountName,
 833                                                                            UInt32 passwordLength, const void *passwordData, SecKeychainItemRef *itemRef);
 834
 835
 836 /*!
 837         @function SecKeychainFindGenericPassword
 838         Find a generic password
 839
 840         @param keychainRef
 841         @param serverNameLength
 842         @param serverName
 843         @param accountNameLength
 844         @param accountName
 845         @param passwordLength
 846         @param passwordData
 847         @param itemRef
 848
 849         @result noErr 0 No error.
 850 */
 851 OSStatus SecKeychainFindGenericPassword(SecKeychainRef keychainRef,  UInt32 serviceNameLength, char *serviceName,
 852                                                                                 UInt32 accountNameLength, char *accountName,
 853                                                                                 UInt32 *passwordLength, void **passwordData, SecKeychainItemRef *itemRef);
 854
 855
 856
 857 /*!
 858         @function SecKeychainSetUserInteractionAllowed
 859         Turn on/off any optional user interface
 860
 861         @param state true = allow user interface, false = disallow user interface
 862
 863         @result noErr 0 No error.
 864 */
 865 OSStatus SecKeychainSetUserInteractionAllowed(Boolean state);
 866
 867 /*!
 868         @function SecKeychainGetUserInteractionAllowed
 869         Get the current setting for SecKeychainSetUserInteractionAllowed
 870
 871         @param *state true = allow user interface, false = disallow user interface
 872
 873         @result noErr 0 No error.
 874 */
 875 OSStatus SecKeychainGetUserInteractionAllowed(Boolean *state);
 876
 877 #if defined(__cplusplus)
 878 }
 879 #endif
 880
 881 #endif /* ! __SECKEYCHAINAPI__ */
 882
 883