OSX/sec/Security/SecItemBackup.h

   1 /*
   2  * Copyright (c) 2015 Apple 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 //  SecItemBackup.h
  26 //  SecItem backup restore SPIs
  27 //
  28
  29 #ifndef _SECURITY_ITEMBACKUP_H_
  30 #define _SECURITY_ITEMBACKUP_H_
  31
  32 #include <CoreFoundation/CFError.h>
  33 #include <CoreFoundation/CFString.h>
  34
  35 __BEGIN_DECLS
  36
  37 // Keys in a backup item dictionary
  38 #define kSecItemBackupHashKey  CFSTR("hash")
  39 #define kSecItemBackupClassKey CFSTR("class")
  40 #define kSecItemBackupDataKey  CFSTR("data")
  41
  42
  43 /* View aware backup/restore SPIs. */
  44
  45 #define kSecItemBackupNotification "com.apple.security.itembackup"
  46
  47 typedef enum SecBackupEventType {
  48     kSecBackupEventReset = 0,           // key is keybag
  49     kSecBackupEventAdd,                 // key, item are added in backup (replaces existing item with key)
  50     kSecBackupEventRemove,              // key gets removed from backup
  51     kSecBackupEventComplete             // key and value are unused
  52 } SecBackupEventType;
  53
  54 bool SecItemBackupWithRegisteredBackups(CFErrorRef *error, void(^backup)(CFStringRef backupName));
  55
  56 /*!
  57  @function SecItemBackupWithChanges
  58  @abstract Tell securityd which keybag (via a persistent ref) to use to backup
  59  items for each of the built in dataSources to.
  60  @param backupName Name of this backup set.
  61  @param error Returned if there is a failure.
  62  @result bool standard CFError contract.
  63  @discussion CloudServices is expected to call this SPI to stream out changes already spooled into a backup file by securityd.  */
  64 bool SecItemBackupWithChanges(CFStringRef backupName, CFErrorRef *error, void (^event)(SecBackupEventType et, CFTypeRef key, CFTypeRef item));
  65
  66 /*!
  67  @function SecItemBackupSetConfirmedManifest
  68  @abstract Tell securityd what we have in the backup for a particular backupName
  69  @param backupName Name of this backup set.
  70  @param keybagDigest The SHA1 hash of the last received keybag.
  71  @param manifest Manifest of the backup.
  72  @result bool standard CFError contract.
  73  @discussion cloudsvc is expected to call this SPI to whenever it thinks securityd might not be in sync with backupd of whenever it reads a backup from or writes a backup to kvs.  */
  74 bool SecItemBackupSetConfirmedManifest(CFStringRef backupName, CFDataRef keybagDigest, CFDataRef manifest, CFErrorRef *error);
  75
  76 /*!
  77  @function SecItemBackupRestore
  78  @abstract Restore data from a cloudsvc backup.
  79  @param backupName Name of this backup set (corresponds to the view).
  80  @param peerID hash of the public key of the peer info matching the chosen device. For single iCSC recovery, this is the public key hash returned from SOSRegisterSingleRecoverySecret().
  81  @param secret Credential to unlock keybag
  82  @param keybag keybag for this backup
  83  @param backup backup to be restored
  84  @discussion CloudServices iterates over all the backups, calling this for each backup with peer infos matching the chosen device. */
  85 void SecItemBackupRestore(CFStringRef backupName, CFStringRef peerID, CFDataRef keybag, CFDataRef secret, CFTypeRef backup, void (^completion)(CFErrorRef error));
  86
  87 /*!
  88  @function SecItemBackupCopyMatching
  89  @abstract Query the contents of a backup dictionary.
  90  @param keybag The bag protecting the backup data.
  91  @param secret Credential to unlock keybag.
  92  @param backup Dictionary returned from SecItemBackupDataSource.
  93  @param query A dictionary containing an item class specification and
  94  optional attributes for controlling the search. See the "Keychain
  95  Search Attributes" section of SecItemCopyMatching for a description of
  96  currently defined search attributes.
  97  @result CFTypeRef reference to the found item(s). The
  98  exact type of the result is based on the search attributes supplied
  99  in the query.  Returns NULL and sets *error if there is a failure.
 100  @discussion This allows clients to "restore" a backup and fetch an item from
 101  it without restoring the backup to the keychain, and in particular without
 102  even having a writable keychain around, such as when running in the restore OS. */
 103 CFDictionaryRef SecItemBackupCopyMatching(CFDataRef keybag, CFDataRef secret, CFDictionaryRef backup, CFDictionaryRef query, CFErrorRef *error);
 104
 105 // Utility function to compute a confirmed manifest from a v0 backup dictionary.
 106 CFDataRef SecItemBackupCreateManifest(CFDictionaryRef backup, CFErrorRef *error);
 107
 108 __END_DECLS
 109
 110 #endif /* _SECURITY_ITEMBACKUP_H_ */