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