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 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_ */