keychain/ot/OTControl.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 __OBJC2__
  25
  26 #ifndef OTCONTROL_H
  27 #define OTCONTROL_H
  28
  29 #import <Foundation/Foundation.h>
  30 #import <TargetConditionals.h>
  31 #if !TARGET_OS_BRIDGE // SecurityFoundation not mastered on BridgeOS
  32 #import <SecurityFoundation/SFKey.h>
  33 #else
  34 @class SFECKeyPair;
  35 #endif
  36
  37 #import <Security/OTConstants.h>
  38 #import <Security/OTClique.h>
  39
  40 #if !TARGET_OS_BRIDGE // SecurityFoundation not mastered on BridgeOS
  41 #import <SecurityFoundation/SFKey.h>
  42 #else
  43 @class SFECKeyPair;
  44 #endif
  45
  46 NS_ASSUME_NONNULL_BEGIN
  47
  48 @class OTJoiningConfiguration;
  49
  50
  51 @interface OTControl : NSObject
  52
  53 @property (assign) BOOL synchronous;
  54
  55 + (OTControl* _Nullable)controlObject:(NSError* _Nullable __autoreleasing* _Nullable)error;
  56 + (OTControl* _Nullable)controlObject:(bool)sync error:(NSError* _Nullable *)error;
  57
  58 - (instancetype)initWithConnection:(NSXPCConnection*)connection sync:(bool)sync;
  59
  60 - (void)restore:(NSString *)contextID dsid:(NSString *)dsid secret:(NSData*)secret escrowRecordID:(NSString*)escrowRecordID
  61           reply:(void (^)(NSData* signingKeyData, NSData* encryptionKeyData, NSError* _Nullable error))reply
  62     API_DEPRECATED("Use OTClique API", macos(10.14, 10.15.1), ios(4, 17.2));
  63 - (void)encryptionKey:(void (^)(NSData* result, NSError* _Nullable error))reply
  64     API_DEPRECATED("No longer needed", macos(10.14, 10.15.1), ios(4, 17.2));
  65 - (void)signingKey:(void (^)(NSData* result, NSError* _Nullable error))reply
  66     API_DEPRECATED("No longer needed", macos(10.14, 10.15.1), ios(4, 17.2));
  67 - (void)listOfRecords:(void (^)(NSArray* list, NSError* _Nullable error))reply
  68     API_DEPRECATED("No longer needed", macos(10.14, 10.15.1), ios(4, 17.2));
  69 - (void)reset:(void (^)(BOOL result, NSError* _Nullable error))reply
  70     API_DEPRECATED("No longer needed", macos(10.14, 10.15.1), ios(4, 17.2));
  71
  72 - (void)signIn:(NSString*)dsid container:(NSString* _Nullable)container context:(NSString*)contextID reply:(void (^)(NSError * _Nullable error))reply;
  73 - (void)signOut:(NSString* _Nullable)container context:(NSString*)contextID reply:(void (^)(NSError * _Nullable error))reply;
  74 - (void)notifyIDMSTrustLevelChangeForContainer:(NSString* _Nullable)container context:(NSString*)contextID reply:(void (^)(NSError * _Nullable error))reply;
  75
  76 - (void)handleIdentityChangeForSigningKey:(SFECKeyPair* _Nonnull)peerSigningKey
  77                          ForEncryptionKey:(SFECKeyPair* _Nonnull)encryptionKey
  78                                 ForPeerID:(NSString*)peerID
  79                                     reply:(void (^)(BOOL result,
  80                                                     NSError* _Nullable error))reply
  81     API_DEPRECATED("No longer needed", macos(10.14, 10.15.1), ios(4, 17.2));
  82
  83 - (void)rpcEpochWithConfiguration:(OTJoiningConfiguration*)config
  84                             reply:(void (^)(uint64_t epoch,
  85                                             NSError * _Nullable error))reply;
  86
  87 - (void)rpcPrepareIdentityAsApplicantWithConfiguration:(OTJoiningConfiguration*)config
  88                                                  reply:(void (^)(NSString * _Nullable peerID,
  89                                                                  NSData * _Nullable permanentInfo,
  90                                                                  NSData * _Nullable permanentInfoSig,
  91                                                                  NSData * _Nullable stableInfo,
  92                                                                  NSData * _Nullable stableInfoSig,
  93                                                                  NSError * _Nullable error))reply;
  94 - (void)rpcVoucherWithConfiguration:(OTJoiningConfiguration*)config
  95                              peerID:(NSString*)peerID
  96                       permanentInfo:(NSData *)permanentInfo
  97                    permanentInfoSig:(NSData *)permanentInfoSig
  98                          stableInfo:(NSData *)stableInfo
  99                       stableInfoSig:(NSData *)stableInfoSig
 100                               reply:(void (^)(NSData* voucher, NSData* voucherSig, NSError * _Nullable error))reply;
 101
 102 - (void)rpcJoinWithConfiguration:(OTJoiningConfiguration*)config
 103                        vouchData:(NSData*)vouchData
 104                         vouchSig:(NSData*)vouchSig
 105                            reply:(void (^)(NSError * _Nullable error))reply;
 106
 107
 108
 109 // Call this to 'preflight' a bottled peer entry. This will create sufficient entropy, derive and save all relevant keys,
 110 // then return the entropy to the caller. If something goes wrong during this process, do not store the returned entropy.
 111 - (void)preflightBottledPeer:(NSString*)contextID
 112                         dsid:(NSString*)dsid
 113                        reply:(void (^)(NSData* _Nullable entropy,
 114                                        NSString* _Nullable bottleID,
 115                                        NSData* _Nullable signingPublicKey,
 116                                        NSError* _Nullable error))reply
 117     API_DEPRECATED("Use OTClique API", macos(10.14, 10.15), ios(4, 17));
 118
 119 // Call this to 'launch' a preflighted bottled peer entry. This indicates that you've successfully stored the entropy,
 120 // and we should save the bottled peer entry off-device for later retrieval.
 121 - (void)launchBottledPeer:(NSString*)contextID
 122                  bottleID:(NSString*)bottleID
 123                     reply:(void (^ _Nullable)(NSError* _Nullable error))reply
 124     API_DEPRECATED("No longer needed", macos(10.14, 10.15), ios(4, 17));
 125
 126 // Call this to scrub the launch of a preflighted bottled peer entry. This indicates you've terminally failed to store the
 127 // preflighted entropy, and this bottled peer will never be used again and can be deleted.
 128 - (void)scrubBottledPeer:(NSString*)contextID
 129                 bottleID:(NSString*)bottleID
 130                    reply:(void (^ _Nullable)(NSError* _Nullable error))reply
 131     API_DEPRECATED("No longer needed", macos(10.14, 10.15), ios(4, 17));
 132
 133 - (void)status:(NSString* _Nullable)container
 134        context:(NSString*)context
 135          reply:(void (^)(NSDictionary* _Nullable result, NSError* _Nullable error))reply;
 136
 137 - (void)fetchEgoPeerID:(NSString* _Nullable)container
 138                context:(NSString*)context
 139                  reply:(void (^)(NSString* _Nullable peerID, NSError* _Nullable error))reply;
 140
 141 - (void)fetchCliqueStatus:(NSString* _Nullable)container
 142                   context:(NSString*)context
 143             configuration:(OTOperationConfiguration *)configuration
 144                     reply:(void (^)(CliqueStatus cliqueStatus, NSError* _Nullable error))reply;
 145
 146 - (void)fetchTrustStatus:(NSString* _Nullable)container
 147                  context:(NSString*)context
 148            configuration:(OTOperationConfiguration *)configuration
 149                    reply:(void (^)(CliqueStatus status,
 150                                    NSString* _Nullable peerID,
 151                                    NSNumber * _Nullable numberOfOctagonPeers,
 152                                    BOOL isExcluded,
 153                                    NSError * _Nullable error))reply;
 154
 155 // Likely won't be used once Octagon is turned on for good
 156 - (void)startOctagonStateMachine:(NSString* _Nullable)container
 157                          context:(NSString*)context
 158                            reply:(void (^)(NSError* _Nullable error))reply;
 159
 160 - (void)resetAndEstablish:(NSString* _Nullable)container
 161                   context:(NSString*)context
 162                   altDSID:(NSString*)altDSID
 163               resetReason:(CuttlefishResetReason)resetReason
 164                     reply:(void (^)(NSError* _Nullable error))reply;
 165
 166 - (void)establish:(NSString* _Nullable)container
 167           context:(NSString*)context
 168           altDSID:(NSString*)altDSID
 169             reply:(void (^)(NSError* _Nullable error))reply;
 170
 171 - (void)leaveClique:(NSString* _Nullable)container
 172             context:(NSString*)context
 173               reply:(void (^)(NSError* _Nullable error))reply;
 174
 175 - (void)removeFriendsInClique:(NSString* _Nullable)container
 176                       context:(NSString*)context
 177                       peerIDs:(NSArray<NSString*>*)peerIDs
 178                         reply:(void (^)(NSError* _Nullable error))reply;
 179
 180 - (void)peerDeviceNamesByPeerID:(NSString* _Nullable)container
 181                         context:(NSString*)context
 182                           reply:(void (^)(NSDictionary<NSString*, NSString*>* _Nullable peers, NSError* _Nullable error))reply;
 183
 184 - (void)fetchAllViableBottles:(NSString* _Nullable)container
 185                       context:(NSString*)context
 186                         reply:(void (^)(NSArray<NSString*>* _Nullable sortedBottleIDs, NSArray<NSString*> * _Nullable sortedPartialBottleIDs, NSError* _Nullable error))reply;
 187
 188 -(void)restore:(NSString* _Nullable)containerName
 189      contextID:(NSString *)contextID
 190     bottleSalt:(NSString *)bottleSalt
 191        entropy:(NSData *)entropy
 192       bottleID:(NSString *)bottleID
 193          reply:(void (^)(NSError * _Nullable))reply;
 194
 195 - (void)fetchEscrowContents:(NSString* _Nullable)containerName
 196                   contextID:(NSString *)contextID
 197                       reply:(void (^)(NSData* _Nullable entropy,
 198                                       NSString* _Nullable bottleID,
 199                                       NSData* _Nullable signingPublicKey,
 200                                       NSError* _Nullable error))reply;
 201
 202 - (void) createRecoveryKey:(NSString* _Nullable)containerName
 203                  contextID:(NSString *)contextID
 204                recoveryKey:(NSString *)recoveryKey
 205                      reply:(void (^)( NSError * _Nullable))reply;
 206
 207 - (void) joinWithRecoveryKey:(NSString* _Nullable)containerName
 208                    contextID:(NSString *)contextID
 209                  recoveryKey:(NSString*)recoveryKey
 210                        reply:(void (^)(NSError * _Nullable))reply;
 211
 212 - (void)healthCheck:(NSString* _Nullable)container
 213             context:(NSString *)context
 214 skipRateLimitingCheck:(BOOL)skipRateLimitingCheck
 215               reply:(void (^)(NSError *_Nullable error))reply;
 216
 217 - (void)attemptSosUpgrade:(NSString* _Nullable)container
 218                   context:(NSString*)context
 219                     reply:(void (^)(NSError* _Nullable error))reply;
 220
 221 - (void)waitForOctagonUpgrade:(NSString* _Nullable)container
 222                       context:(NSString*)context
 223                         reply:(void (^)(NSError* _Nullable error))reply;
 224
 225 - (void)postCDPFollowupResult:(BOOL)success
 226                          type:(OTCliqueCDPContextType)type
 227                         error:(NSError * _Nullable)error
 228                 containerName:(NSString* _Nullable)containerName
 229                   contextName:(NSString *)contextName
 230                         reply:(void (^)(NSError* _Nullable error))reply;
 231
 232 - (void)tapToRadar:(NSString *)action
 233        description:(NSString *)description
 234              radar:(NSString *)radar
 235              reply:(void (^)(NSError* _Nullable error))reply;
 236
 237 - (void)setCDPEnabled:(NSString* _Nullable)containerName
 238             contextID:(NSString*)contextID
 239                 reply:(void (^)(NSError* _Nullable error))reply;
 240
 241 - (void)getCDPStatus:(NSString* _Nullable)containerName
 242            contextID:(NSString*)contextID
 243                reply:(void (^)(OTCDPStatus status, NSError* _Nullable error))reply;
 244
 245 - (void)refetchCKKSPolicy:(NSString* _Nullable)containerName
 246                 contextID:(NSString*)contextID
 247                     reply:(void (^)(NSError* _Nullable error))reply;
 248
 249 @end
 250
 251 NS_ASSUME_NONNULL_END
 252
 253 #endif // OTCONTROL_H
 254 #endif  // __OBJC__