1/* 2 * Copyright (c) 2000-2004 Apple Computer, Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/*! 25@header SecPassword 26 SecPassword implements logic to use the system facilities for acquiring a password, 27 optionally stored and retrieved from the user's keychain. 28 */ 29 30#include <Security/SecBase.h> 31#include <Security/SecKeychainItem.h> 32#include <Security/cssmapple.h> 33 34#ifndef _SECURITY_SECPASSWORD_H_ 35#define _SECURITY_SECPASSWORD_H_ 36 37#if defined(__cplusplus) 38extern "C" { 39#endif 40 41/*! 42 @abstract Flags to specify SecPasswordAction behavior, as the application steps through the options 43 Get, just get it. 44 Get|Set, get it and set it if it wasn't in the keychain; client doesn't verify it before it's stored 45 Get|Fail, get it and flag that the previously given or stored password is busted. 46 Get|Set|Fail, same as above but also store it. 47 New instead of Get toggles between asking for a new passphrase and an existing one. 48*/ 49enum { 50 kSecPasswordGet = 1<<0, // Get password from keychain or user 51 kSecPasswordSet = 1<<1, // Set password (passed in if kSecPasswordGet not set, otherwise from user) 52 kSecPasswordFail = 1<<2, // Wrong password (ignore item in keychain and flag error) 53 kSecPasswordNew = 1<<3 // Explicitly get a new passphrase 54}; 55 56/*! 57 @function SecGenericPasswordCreate 58 @abstract Create an SecPassword object be used with SecPasswordAction to query and/or set a password used in the client. 59 The keychain list is searched for a generic password with the supplied attributes. If 60 the item is not found, SecPasswordAction will create a new password in the default keychain. 61 Otherwise, the existing item is updated. 62 searchAttrList and itemAttrList are optional - pass NULL for both of them if you only wish to query the user for a password. 63 Use CFRelease on the returned SecPasswordRef when it is no longer needed. 64 @param searchAttrList (in/opt) The list of search attributes for the item. 65 @param itemAttrList (in/opt) A list of attributes which will be used for item creation. 66 @param itemRef (out) On return, a pointer to a password reference. Release this by calling the CFRelease function. 67 */ 68OSStatus SecGenericPasswordCreate(SecKeychainAttributeList *searchAttrList, SecKeychainAttributeList *itemAttrList, SecPasswordRef *itemRef); 69 70/*! 71 @function SecPasswordAction 72 @abstract Get the password for a SecPassword, either from the user or the keychain and return it. 73 Use SecKeychainItemFreeContent to free the data. 74 75 @param itemRef An itemRef previously obtained from SecGenericPasswordCreate. 76 @param message Message to display to the user as a CFString or nil for a default message. 77 (future extension accepts CFDictionary for other hints, icon, secaccess) 78 @param flags (in) The mode of operation. See the flags documentation above. 79 @param length (out) The length of the buffer pointed to by data. 80 @param data A pointer to a buffer containing the data to store. 81 82 */ 83OSStatus SecPasswordAction(SecPasswordRef itemRef, CFTypeRef message, UInt32 flags, UInt32 *length, const void **data); 84 85/*! 86 @function SecPasswordSetInitialAccess 87 @abstract Set the initial access ref. Only used when a password is first added to the keychain. 88 */ 89OSStatus SecPasswordSetInitialAccess(SecPasswordRef itemRef, SecAccessRef accessRef); 90 91#if defined(__cplusplus) 92} 93#endif 94 95#endif /* !_SECURITY_SECPASSWORD_H_ */ 96