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