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