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