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