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 #include <CoreFoundation/CFURL.h>
  35
  36 __BEGIN_DECLS
  37
  38 // Keys in a backup item dictionary
  39 #define kSecItemBackupHashKey  CFSTR("hash")
  40 #define kSecItemBackupClassKey CFSTR("class")
  41 #define kSecItemBackupDataKey  CFSTR("data")
  42
  43
  44 /* View aware backup/restore SPIs. */
  45
  46 #define kSecItemBackupNotification "com.apple.security.itembackup"
  47
  48 typedef enum SecBackupEventType {
  49     kSecBackupEventReset = 0,           // key is keybag
  50     kSecBackupEventAdd,                 // key, item are added in backup (replaces existing item with key)
  51     kSecBackupEventRemove,              // key gets removed from backup
  52     kSecBackupEventComplete             // key and value are unused
  53 } SecBackupEventType;
  54
  55 bool SecItemBackupWithRegisteredBackups(CFErrorRef *error, void(^backup)(CFStringRef backupName));
  56
  57 /*!
  58  @function SecItemBackupWithChanges
  59  @abstract Tell securityd which keybag (via a persistent ref) to use to backup
  60  items for each of the built in dataSources to.
  61  @param backupName Name of this backup set.
  62  @param error Returned if there is a failure.
  63  @result bool standard CFError contract.
  64  @discussion CloudServices is expected to call this SPI to stream out changes already spooled into a backup file by securityd.  */
  65 bool SecItemBackupWithChanges(CFStringRef backupName, CFErrorRef *error, void (^event)(SecBackupEventType et, CFTypeRef key, CFTypeRef item));
  66
  67 /*!
  68  @function SecItemBackupSetConfirmedManifest
  69  @abstract Tell securityd what we have in the backup for a particular backupName
  70  @param backupName Name of this backup set.
  71  @param keybagDigest The SHA1 hash of the last received keybag.
  72  @param manifest Manifest of the backup.
  73  @result bool standard CFError contract.
  74  @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.  */
  75 bool SecItemBackupSetConfirmedManifest(CFStringRef backupName, CFDataRef keybagDigest, CFDataRef manifest, CFErrorRef *error);
  76
  77 /*!
  78  @function SecItemBackupRestore
  79  @abstract Restore data from a cloudsvc backup.
  80  @param backupName Name of this backup set (corresponds to the view).
  81  @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().
  82  @param secret Credential to unlock keybag
  83  @param keybag keybag for this backup
  84  @param backup backup to be restored
  85  @discussion CloudServices iterates over all the backups, calling this for each backup with peer infos matching the chosen device. */
  86 void SecItemBackupRestore(CFStringRef backupName, CFStringRef peerID, CFDataRef keybag, CFDataRef secret, CFTypeRef backup, void (^completion)(CFErrorRef error));
  87
  88 /*!
  89  @function SecItemBackupCopyMatching
  90  @abstract Query the contents of a backup dictionary.
  91  @param keybag The bag protecting the backup data.
  92  @param secret Credential to unlock keybag.
  93  @param backup Dictionary returned from SecItemBackupDataSource.
  94  @param query A dictionary containing an item class specification and
  95  optional attributes for controlling the search. See the "Keychain
  96  Search Attributes" section of SecItemCopyMatching for a description of
  97  currently defined search attributes.
  98  @result CFTypeRef reference to the found item(s). The
  99  exact type of the result is based on the search attributes supplied
 100  in the query.  Returns NULL and sets *error if there is a failure.
 101  @discussion This allows clients to "restore" a backup and fetch an item from
 102  it without restoring the backup to the keychain, and in particular without
 103  even having a writable keychain around, such as when running in the restore OS. */
 104 CFDictionaryRef SecItemBackupCopyMatching(CFDataRef keybag, CFDataRef secret, CFDictionaryRef backup, CFDictionaryRef query, CFErrorRef *error);
 105
 106 // Utility function to compute a confirmed manifest from a v0 backup dictionary.
 107 CFDataRef SecItemBackupCreateManifest(CFDictionaryRef backup, CFErrorRef *error);
 108
 109 /*!
 110  @function SecBackupKeybagAdd
 111  @abstract Add a new asymmetric keybag to the backup table.
 112  @param passcode User entropy to protect the keybag.
 113  @param identifier Unique identifier for the keybag.
 114  @param pathinfo The directory or file containing the keychain.
 115  @param error Returned if there is a failure.
 116  @result bool standard CFError contract.
 117  @discussion The keybag is created and stored in the backup keybag table */
 118 bool SecBackupKeybagAdd(CFDataRef passcode, CFDataRef *identifier, CFURLRef *pathinfo, CFErrorRef *error);
 119
 120 /*!
 121  @function SecBackupKeybagDelete
 122  @abstract Remove an asymmetric keybag from the backup table.
 123  @param query Specify which keybag(s) to delete
 124  @param error Returned if there is a failure.
 125  @result bool standard CFError contract.
 126  @discussion The keychain must be unlocked */
 127 bool SecBackupKeybagDelete(CFDictionaryRef query, CFErrorRef *error);
 128
 129 __END_DECLS
 130
 131 #endif /* _SECURITY_ITEMBACKUP_H_ */