1/* 2 * Copyright (c) 2006 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 * SecKeychainItemExtendedAttributes.h 26 * Created 9/6/06 by dmitch 27 */ 28 29#ifndef _SEC_KEYCHAIN_ITEM_EXTENDED_ATTRIBUTES_H_ 30#define _SEC_KEYCHAIN_ITEM_EXTENDED_ATTRIBUTES_H_ 31 32#include <Security/SecBase.h> 33#include <Security/cssmapple.h> 34#include <CoreFoundation/CFArray.h> 35#include <CoreFoundation/CFData.h> 36 37#if defined(__cplusplus) 38extern "C" { 39#endif 40 41/* 42 * Extended attributes extend the fixed set of keychain item attribute in a generally 43 * extensible way. A given SecKeychainItemRef can have assigned to it any number 44 * of extended attributes, each consisting of an attribute name (as a CFStringRef) 45 * and an attribute value (as a CFDataRef). 46 * 47 * Each extended attribute is a distinct record residing in the same keychain as 48 * the item to which it refers. In a given keychain, the set of the following properties 49 * of an extended attribute record must be unique: 50 * 51 * -- the type of item to which the extended attribute is bound (kSecPublicKeyItemClass, 52 * kSecPrivateKeyItemClass, etc.) 53 * -- an identifier which uniquely identifies the item to which the extended attribute 54 * is bound. Currently this is the PrimaryKey blob. 55 * -- the extended attribute's Attribute Name, specified in this interface as a 56 * CFString. 57 * 58 * Thus, e.g., a given item can have at most one extended attribute with 59 * Attribute Name of CFSTR("SomeAttributeName"). 60 */ 61 62/* 63 * SecKeychainItemSetExtendedAttribute() - set an extended attribute by name and value. 64 * 65 * If the extended attribute specified by 'attrName' does not exist, one will be 66 * created with the value specified in 'attrValue'. 67 * 68 * If the extended attribute specified by 'attrName already exists, its value will be 69 * replaced by the value specified in 'attrValue'. 70 * 71 * If the incoming 'attrValue' is NULL, the extended attribute specified by 'attrName' 72 * will be deleted if it exists. If the incoming 'attrValue' is NULL and no such 73 * attribute exists, the function will return errSecNoSuchAttr. 74 */ 75OSStatus SecKeychainItemSetExtendedAttribute( 76 SecKeychainItemRef itemRef, 77 CFStringRef attrName, /* identifies the attribute */ 78 CFDataRef attrValue); /* value to set; NULL means delete the 79 * attribute */ 80 81/* 82 * SecKeychainItemCopyExtendedAttribute() - Obtain the value of an an extended attribute. 83 * 84 * If the extended attribute specified by 'attrName' exists, its value will be returned 85 * via the *attrValue argument. The caller must CFRelease() this returned value. 86 * 87 * If the extended attribute specified by 'attrName' does not exist, the function 88 * will return errSecNoSuchAttr. 89 */ 90OSStatus SecKeychainItemCopyExtendedAttribute( 91 SecKeychainItemRef itemRef, 92 CFStringRef attrName, 93 CFDataRef *attrValue); /* RETURNED */ 94 95/* 96 * SecKeychainItemCopyAllExtendedAttributes() - obtain all of an item's extended attributes. 97 * 98 * This is used to determine all of the extended attributes associated with a given 99 * SecKeychainItemRef. The Atrribute Names of all of the extended attributes are 100 * returned in the *attrNames argument; on successful return this contains a 101 * CFArray whose elements are CFStringRefs, each of which is an Attribute Name. 102 * The caller must CFRelease() this array. 103 * 104 * Optionally, the Attribute Values of all of the extended attributes is returned 105 * in the *attrValues argument; on successful return this contains a CFArray whose 106 * elements are CFDataRefs, each of which is an Attribute Value. The positions of 107 * the elements in this array correspond with the elements in *attrNames; i.e., 108 * the n'th element in *attrName is the Attribute Name corresponding to the 109 * Attribute Value found in the n'th element of *attrValues. 110 * 111 * Pass in NULL for attrValues if you don't need the Attribute Values. Caller 112 * must CFRelease the array returned via this argument. 113 * 114 * If the item has no extended attributes, this function returns errSecNoSuchAttr. 115 */ 116OSStatus SecKeychainItemCopyAllExtendedAttributes( 117 SecKeychainItemRef itemRef, 118 CFArrayRef *attrNames, /* RETURNED, each element is a CFStringRef */ 119 CFArrayRef *attrValues); /* optional, RETURNED, each element is a 120 * CFDataRef */ 121#if defined(__cplusplus) 122} 123#endif 124 125#endif /* _SEC_KEYCHAIN_ITEM_EXTENDED_ATTRIBUTES_H_ */ 126 127