keychain/ckks/CKKSKey.h

   1 /*
   2  * Copyright (c) 2017 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 #if OCTAGON
  25
  26 #import <Foundation/Foundation.h>
  27
  28 #import "keychain/ckks/CKKSItem.h"
  29 #import "keychain/ckks/CKKSKeychainBackedKey.h"
  30 #import "keychain/ckks/CKKSSIV.h"
  31
  32 #import "keychain/ckks/CKKSPeer.h"
  33 #import "keychain/ckks/proto/generated_source/CKKSSerializedKey.h"
  34
  35 NS_ASSUME_NONNULL_BEGIN
  36
  37 @class CKKSPeerProviderState;
  38
  39 @interface CKKSKey : CKKSCKRecordHolder
  40 @property CKKSKeychainBackedKey* keycore;
  41
  42 @property NSString* uuid;
  43 @property NSString* parentKeyUUID;
  44 @property (copy) CKKSKeyClass* keyclass;
  45
  46 @property (copy) CKKSWrappedAESSIVKey* wrappedkey;
  47 @property (nullable, readonly) CKKSAESSIVKey* aessivkey;
  48
  49 @property (copy) CKKSProcessedState* state;
  50 @property bool currentkey;
  51
  52 @property (readonly) NSString* zoneName;
  53
  54 // Fetches and attempts to unwrap this key for use
  55 + (instancetype _Nullable)loadKeyWithUUID:(NSString*)uuid zoneID:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
  56
  57 // Creates new random keys, in the parent's zone
  58 + (instancetype _Nullable)randomKeyWrappedByParent:(CKKSKey*)parentKey error:(NSError* __autoreleasing*)error;
  59 + (instancetype _Nullable)randomKeyWrappedByParent:(CKKSKey*)parentKey
  60                                           keyclass:(CKKSKeyClass*)keyclass
  61                                              error:(NSError* __autoreleasing*)error;
  62
  63 // Creates a new random key that wraps itself
  64 + (instancetype _Nullable)randomKeyWrappedBySelf:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
  65
  66 /* Helper functions for persisting key material in the keychain */
  67 - (BOOL)saveKeyMaterialToKeychain:(NSError* __autoreleasing*)error;
  68 - (BOOL)saveKeyMaterialToKeychain:(bool)stashTLK
  69                             error:(NSError* __autoreleasing*)error;  // call this to not stash a non-syncable TLK, if that's what you want
  70
  71 - (BOOL)loadKeyMaterialFromKeychain:(NSError* __autoreleasing*)error;
  72 - (BOOL)deleteKeyMaterialFromKeychain:(NSError* __autoreleasing*)error;
  73 + (NSString* _Nullable)isItemKeyForKeychainView:(SecDbItemRef)item;
  74
  75 + (instancetype _Nullable)keyFromKeychain:(NSString*)uuid
  76                             parentKeyUUID:(NSString*)parentKeyUUID
  77                                  keyclass:(CKKSKeyClass*)keyclass
  78                                     state:(CKKSProcessedState*)state
  79                                    zoneID:(CKRecordZoneID*)zoneID
  80                           encodedCKRecord:(NSData* _Nullable)encodedrecord
  81                                currentkey:(NSInteger)currentkey
  82                                     error:(NSError* __autoreleasing*)error;
  83
  84
  85 // Returns false if this key is not a valid TLK for any reason.
  86 - (BOOL)validTLK:(NSError**)error;
  87
  88 // First, attempts to load the key from the keychain. If it isn't present, this will
  89 // load the TLKShares for this key from the database, then attempts to use them to unwrap this key.
  90 // If no TLKShares are trusted, returns an error.
  91 - (BOOL)tlkMaterialPresentOrRecoverableViaTLKShare:(NSArray<CKKSPeerProviderState*>*)trustStates
  92                                              error:(NSError**)error;
  93
  94 + (instancetype _Nullable)fromDatabase:(NSString*)uuid zoneID:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
  95 + (instancetype _Nullable)fromDatabaseAnyState:(NSString*)uuid
  96                                         zoneID:(CKRecordZoneID*)zoneID
  97                                          error:(NSError* __autoreleasing*)error;
  98 + (instancetype _Nullable)tryFromDatabase:(NSString*)uuid zoneID:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
  99 + (instancetype _Nullable)tryFromDatabaseAnyState:(NSString*)uuid zoneID:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 100
 101 + (NSArray<CKKSKey*>* _Nullable)selfWrappedKeys:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 102
 103 + (instancetype _Nullable)currentKeyForClass:(CKKSKeyClass*)keyclass zoneID:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 104 + (NSArray<CKKSKey*>* _Nullable)currentKeysForClass:(CKKSKeyClass*)keyclass
 105                                     state:(CKKSProcessedState*)state
 106                                    zoneID:(CKRecordZoneID*)zoneID
 107                                     error:(NSError* __autoreleasing*)error;
 108
 109 + (NSArray<CKKSKey*>*)allKeys:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 110 + (NSArray<CKKSKey*>*)remoteKeys:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 111 + (NSArray<CKKSKey*>*)localKeys:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 112
 113 - (bool)saveToDatabaseAsOnlyCurrentKeyForClassAndState:(NSError* __autoreleasing*)error;
 114
 115 - (instancetype)init NS_UNAVAILABLE;
 116
 117 - (instancetype)initSelfWrappedWithAESKey:(CKKSAESSIVKey*)aeskey
 118                                      uuid:(NSString*)uuid
 119                                  keyclass:(CKKSKeyClass*)keyclass
 120                                     state:(CKKSProcessedState*)state
 121                                    zoneID:(CKRecordZoneID*)zoneID
 122                           encodedCKRecord:(NSData* _Nullable)encodedrecord
 123                                currentkey:(NSInteger)currentkey;
 124
 125 - (instancetype)initWrappedBy:(CKKSKey*)wrappingKey
 126                        AESKey:(CKKSAESSIVKey*)aeskey
 127                          uuid:(NSString*)uuid
 128                      keyclass:(CKKSKeyClass*)keyclass
 129                         state:(CKKSProcessedState*)state
 130                        zoneID:(CKRecordZoneID*)zoneID
 131               encodedCKRecord:(NSData* _Nullable)encodedrecord
 132                    currentkey:(NSInteger)currentkey;
 133
 134 - (instancetype)initWithWrappedAESKey:(CKKSWrappedAESSIVKey* _Nullable)wrappedaeskey
 135                                  uuid:(NSString*)uuid
 136                         parentKeyUUID:(NSString*)parentKeyUUID
 137                              keyclass:(CKKSKeyClass*)keyclass
 138                                 state:(CKKSProcessedState*)state
 139                                zoneID:(CKRecordZoneID*)zoneID
 140                       encodedCKRecord:(NSData* _Nullable)encodedrecord
 141                            currentkey:(NSInteger)currentkey;
 142
 143 - (instancetype)initWithKeyCore:(CKKSKeychainBackedKey*)core;
 144
 145 /* Returns true if we believe this key wraps itself. */
 146 - (bool)wrapsSelf;
 147
 148 - (CKKSKey* _Nullable)topKeyInAnyState:(NSError* __autoreleasing*)error;
 149
 150 // Attempts checks if the AES key is already loaded, or attempts to load it from the keychain. Returns false if it fails.
 151 - (CKKSAESSIVKey*)ensureKeyLoaded:(NSError* __autoreleasing*)error;
 152
 153 // Attempts to unwrap this key via unwrapping its wrapping keys via the key hierarchy.
 154 - (CKKSAESSIVKey*)unwrapViaKeyHierarchy:(NSError* __autoreleasing*)error;
 155
 156 // On a self-wrapped key, determine if this AES-SIV key is the self-wrapped key.
 157 // If it is, save the key as this CKKSKey's unwrapped key.
 158 - (bool)trySelfWrappedKeyCandidate:(CKKSAESSIVKey*)candidate error:(NSError* __autoreleasing*)error;
 159
 160 - (CKKSWrappedAESSIVKey*)wrapAESKey:(CKKSAESSIVKey*)keyToWrap error:(NSError* __autoreleasing*)error;
 161 - (CKKSAESSIVKey*)unwrapAESKey:(CKKSWrappedAESSIVKey*)keyToUnwrap error:(NSError* __autoreleasing*)error;
 162
 163 - (bool)wrapUnder:(CKKSKey*)wrappingKey error:(NSError* __autoreleasing*)error;
 164
 165 - (NSData* _Nullable)encryptData:(NSData*)plaintext
 166                authenticatedData:(NSDictionary<NSString*, NSData*>* _Nullable)ad
 167                            error:(NSError* __autoreleasing*)error;
 168 - (NSData* _Nullable)decryptData:(NSData*)ciphertext
 169                authenticatedData:(NSDictionary<NSString*, NSData*>* _Nullable)ad
 170                            error:(NSError* __autoreleasing*)error;
 171
 172 - (NSData* _Nullable)serializeAsProtobuf:(NSError* __autoreleasing*)error;
 173 + (CKKSKey* _Nullable)loadFromProtobuf:(NSData*)data error:(NSError* __autoreleasing*)error;
 174
 175 + (NSDictionary<NSString*, NSNumber*>*)countsByClass:(CKRecordZoneID*)zoneID error:(NSError* __autoreleasing*)error;
 176 @end
 177
 178 NS_ASSUME_NONNULL_END
 179
 180 #endif