libsecurity_keychain/lib/SecKeychainItemExtendedAttributes.h

   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)
  38 extern "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  */
  75 OSStatus 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  */
  90 OSStatus 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  */
 116 OSStatus 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