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                  preapprovedKeys:(NSArray<NSData*>* _Nullable)preapprovedKeys
 106                            reply:(void (^)(NSError * _Nullable error))reply;
 107
 108
 109
 110 // Call this to 'preflight' a bottled peer entry. This will create sufficient entropy, derive and save all relevant keys,
 111 // then return the entropy to the caller. If something goes wrong during this process, do not store the returned entropy.
 112 - (void)preflightBottledPeer:(NSString*)contextID
 113                         dsid:(NSString*)dsid
 114                        reply:(void (^)(NSData* _Nullable entropy,
 115                                        NSString* _Nullable bottleID,
 116                                        NSData* _Nullable signingPublicKey,
 117                                        NSError* _Nullable error))reply
 118     API_DEPRECATED("Use OTClique API", macos(10.14, 10.15), ios(4, 17));
 119
 120 // Call this to 'launch' a preflighted bottled peer entry. This indicates that you've successfully stored the entropy,
 121 // and we should save the bottled peer entry off-device for later retrieval.
 122 - (void)launchBottledPeer:(NSString*)contextID
 123                  bottleID:(NSString*)bottleID
 124                     reply:(void (^ _Nullable)(NSError* _Nullable error))reply
 125     API_DEPRECATED("No longer needed", macos(10.14, 10.15), ios(4, 17));
 126
 127 // Call this to scrub the launch of a preflighted bottled peer entry. This indicates you've terminally failed to store the
 128 // preflighted entropy, and this bottled peer will never be used again and can be deleted.
 129 - (void)scrubBottledPeer:(NSString*)contextID
 130                 bottleID:(NSString*)bottleID
 131                    reply:(void (^ _Nullable)(NSError* _Nullable error))reply
 132     API_DEPRECATED("No longer needed", macos(10.14, 10.15), ios(4, 17));
 133
 134 - (void)status:(NSString* _Nullable)container
 135        context:(NSString*)context
 136          reply:(void (^)(NSDictionary* _Nullable result, NSError* _Nullable error))reply;
 137
 138 - (void)fetchEgoPeerID:(NSString* _Nullable)container
 139                context:(NSString*)context
 140                  reply:(void (^)(NSString* _Nullable peerID, NSError* _Nullable error))reply;
 141
 142 - (void)fetchCliqueStatus:(NSString* _Nullable)container
 143                   context:(NSString*)context
 144             configuration:(OTOperationConfiguration *)configuration
 145                     reply:(void (^)(CliqueStatus cliqueStatus, NSError* _Nullable error))reply;
 146
 147 - (void)fetchTrustStatus:(NSString* _Nullable)container
 148                  context:(NSString*)context
 149            configuration:(OTOperationConfiguration *)configuration
 150                    reply:(void (^)(CliqueStatus status,
 151                                    NSString* _Nullable peerID,
 152                                    NSNumber * _Nullable numberOfOctagonPeers,
 153                                    BOOL isExcluded,
 154                                    NSError * _Nullable error))reply;
 155
 156 // Likely won't be used once Octagon is turned on for good
 157 - (void)startOctagonStateMachine:(NSString* _Nullable)container
 158                          context:(NSString*)context
 159                            reply:(void (^)(NSError* _Nullable error))reply;
 160
 161 - (void)resetAndEstablish:(NSString* _Nullable)container
 162                   context:(NSString*)context
 163                   altDSID:(NSString*)altDSID
 164               resetReason:(CuttlefishResetReason)resetReason
 165                     reply:(void (^)(NSError* _Nullable error))reply;
 166
 167 - (void)establish:(NSString* _Nullable)container
 168           context:(NSString*)context
 169           altDSID:(NSString*)altDSID
 170             reply:(void (^)(NSError* _Nullable error))reply;
 171
 172 - (void)leaveClique:(NSString* _Nullable)container
 173             context:(NSString*)context
 174               reply:(void (^)(NSError* _Nullable error))reply;
 175
 176 - (void)removeFriendsInClique:(NSString* _Nullable)container
 177                       context:(NSString*)context
 178                       peerIDs:(NSArray<NSString*>*)peerIDs
 179                         reply:(void (^)(NSError* _Nullable error))reply;
 180
 181 - (void)peerDeviceNamesByPeerID:(NSString* _Nullable)container
 182                         context:(NSString*)context
 183                           reply:(void (^)(NSDictionary<NSString*, NSString*>* _Nullable peers, NSError* _Nullable error))reply;
 184
 185 - (void)fetchAllViableBottles:(NSString* _Nullable)container
 186                       context:(NSString*)context
 187                         reply:(void (^)(NSArray<NSString*>* _Nullable sortedBottleIDs, NSArray<NSString*> * _Nullable sortedPartialBottleIDs, NSError* _Nullable error))reply;
 188
 189 -(void)restore:(NSString* _Nullable)containerName
 190      contextID:(NSString *)contextID
 191     bottleSalt:(NSString *)bottleSalt
 192        entropy:(NSData *)entropy
 193       bottleID:(NSString *)bottleID
 194          reply:(void (^)(NSError * _Nullable))reply;
 195
 196 - (void)fetchEscrowContents:(NSString* _Nullable)containerName
 197                   contextID:(NSString *)contextID
 198                       reply:(void (^)(NSData* _Nullable entropy,
 199                                       NSString* _Nullable bottleID,
 200                                       NSData* _Nullable signingPublicKey,
 201                                       NSError* _Nullable error))reply;
 202
 203 - (void) createRecoveryKey:(NSString* _Nullable)containerName
 204                  contextID:(NSString *)contextID
 205                recoveryKey:(NSString *)recoveryKey
 206                      reply:(void (^)( NSError * _Nullable))reply;
 207
 208 - (void) joinWithRecoveryKey:(NSString* _Nullable)containerName
 209                    contextID:(NSString *)contextID
 210                  recoveryKey:(NSString*)recoveryKey
 211                        reply:(void (^)(NSError * _Nullable))reply;
 212
 213 - (void)healthCheck:(NSString* _Nullable)container
 214             context:(NSString *)context
 215 skipRateLimitingCheck:(BOOL)skipRateLimitingCheck
 216               reply:(void (^)(NSError *_Nullable error))reply;
 217
 218 - (void)attemptSosUpgrade:(NSString* _Nullable)container
 219                   context:(NSString*)context
 220                     reply:(void (^)(NSError* _Nullable error))reply;
 221
 222 - (void)waitForOctagonUpgrade:(NSString* _Nullable)container
 223                       context:(NSString*)context
 224                         reply:(void (^)(NSError* _Nullable error))reply;
 225
 226 - (void)postCDPFollowupResult:(BOOL)success
 227                          type:(OTCliqueCDPContextType)type
 228                         error:(NSError * _Nullable)error
 229                 containerName:(NSString* _Nullable)containerName
 230                   contextName:(NSString *)contextName
 231                         reply:(void (^)(NSError* _Nullable error))reply;
 232
 233 - (void)tapToRadar:(NSString *)action
 234        description:(NSString *)description
 235              radar:(NSString *)radar
 236              reply:(void (^)(NSError* _Nullable error))reply;
 237
 238 @end
 239
 240 NS_ASSUME_NONNULL_END
 241
 242 #endif // OTCONTROL_H
 243 #endif  // __OBJC__