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  bool SecItemBackupWithRegisteredViewBackup(CFStringRef viewName, CFErrorRef *error);
 58  
 59  /*!
 60   @function SecItemBackupWithChanges
 61   @abstract Tell securityd which keybag (via a persistent ref) to use to backup
 62   items for each of the built in dataSources to.
 63   @param backupName Name of this backup set.
 64   @param error Returned if there is a failure.
 65   @result bool standard CFError contract.
 66   @discussion CloudServices is expected to call this SPI to stream out changes already spooled into a backup file by securityd.  */
 67  bool SecItemBackupWithChanges(CFStringRef backupName, CFErrorRef *error, void (^event)(SecBackupEventType et, CFTypeRef key, CFTypeRef item));
 68  
 69  /*!
 70   @function SecItemBackupSetConfirmedManifest
 71   @abstract Tell securityd what we have in the backup for a particular backupName
 72   @param backupName Name of this backup set.
 73   @param keybagDigest The SHA1 hash of the last received keybag.
 74   @param manifest Manifest of the backup.
 75   @result bool standard CFError contract.
 76   @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.  */
 77  bool SecItemBackupSetConfirmedManifest(CFStringRef backupName, CFDataRef keybagDigest, CFDataRef manifest, CFErrorRef *error);
 78  
 79  /*!
 80   @function SecItemBackupRestore
 81   @abstract Restore data from a cloudsvc backup.
 82   @param backupName Name of this backup set (corresponds to the view).
 83   @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().
 84   @param secret Credential to unlock keybag
 85   @param keybag keybag for this backup
 86   @param backup backup to be restored
 87   @discussion CloudServices iterates over all the backups, calling this for each backup with peer infos matching the chosen device. */
 88  void SecItemBackupRestore(CFStringRef backupName, CFStringRef peerID, CFDataRef keybag, CFDataRef secret, CFTypeRef backup, void (^completion)(CFErrorRef error));
 89  
 90  // Utility function to compute a confirmed manifest from a v0 backup dictionary.
 91  CFDataRef SecItemBackupCreateManifest(CFDictionaryRef backup, CFErrorRef *error);
 92  
 93  /*!
 94   @function SecBackupKeybagAdd
 95   @abstract Add a new asymmetric keybag to the backup table.
 96   @param passcode User entropy to protect the keybag.
 97   @param identifier Unique identifier for the keybag.
 98   @param pathinfo The directory or file containing the keychain.
 99   @param error Returned if there is a failure.
100   @result bool standard CFError contract.
101   @discussion The keybag is created and stored in the backup keybag table */
102  bool SecBackupKeybagAdd(CFDataRef passcode, CFDataRef *identifier, CFURLRef *pathinfo, CFErrorRef *error);
103  
104  /*!
105   @function SecBackupKeybagDelete
106   @abstract Remove an asymmetric keybag from the backup table.
107   @param query Specify which keybag(s) to delete
108   @param error Returned if there is a failure.
109   @result bool standard CFError contract.
110   @discussion The keychain must be unlocked */
111  bool SecBackupKeybagDelete(CFDictionaryRef query, CFErrorRef *error);
112  
113  __END_DECLS
114  
115  #endif /* _SECURITY_ITEMBACKUP_H_ */