keychain/ot/OTClique.h

   1 /*
   2  * Copyright (c) 2018 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
  25 #ifndef OTClique_h
  26 #define OTClique_h
  27
  28 #if __OBJC2__
  29
  30 #import <Foundation/Foundation.h>
  31 #import <Security/SecureObjectSync/SOSCloudCircleInternal.h>
  32 #import <Security/SecureObjectSync/SOSPeerInfo.h>
  33 #import <Security/SecureObjectSync/SOSTypes.h>
  34 #import <Security/OTConstants.h>
  35 #import <Security/SecRecoveryKey.h>
  36
  37 typedef NS_ENUM(NSInteger, CliqueStatus) {
  38     CliqueStatusIn         = 0, /*There is a clique and I am in it*/
  39     CliqueStatusNotIn      = 1, /*There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us*/
  40     CliqueStatusPending    = 2, /*For compatibility, keeping the pending state */
  41     CliqueStatusAbsent     = 3, /*There is no clique - you can establish one */
  42     CliqueStatusNoCloudKitAccount = 4, /* no cloudkit account present */
  43     CliqueStatusError      = -1 /*unable to determine circle status, inspect CFError to find out why */
  44 };
  45
  46 typedef NS_ENUM(NSInteger, OTCDPStatus) {
  47     OTCDPStatusUnknown = 0,
  48     OTCDPStatusDisabled = 1,
  49     OTCDPStatusEnabled = 2,
  50 };
  51
  52 NS_ASSUME_NONNULL_BEGIN
  53
  54 NSString* OTCliqueStatusToString(CliqueStatus status);
  55 CliqueStatus OTCliqueStatusFromString(NSString* str);
  56 NSString* OTCDPStatusToString(OTCDPStatus status);
  57
  58 @class KCPairingChannelContext;
  59 @class KCPairingChannel;
  60 @class OTPairingChannel;
  61 @class OTPairingChannelContext;
  62 @class OTControl;
  63 @class CKKSControl;
  64
  65 extern NSString* kSecEntitlementPrivateOctagonEscrow;
  66
  67 @interface OTConfigurationContext : NSObject
  68 @property (nonatomic, copy) NSString* context;
  69 @property (nonatomic, copy) NSString* containerName;
  70 @property (nonatomic, copy, nullable) NSString* dsid;
  71 @property (nonatomic, copy, nullable) NSString* altDSID;
  72 @property (nonatomic, copy, nullable) NSString* authenticationAppleID;
  73 @property (nonatomic, copy, nullable) NSString* passwordEquivalentToken;
  74 @property (nonatomic) BOOL overrideEscrowCache;
  75
  76 // Use this to inject your own OTControl object. It must be configured as synchronous.
  77 @property (nullable, strong) OTControl* otControl;
  78
  79 // Use this to inject your own CKKSControl object. It must be configured as synchronous.
  80 @property (nullable, strong) CKKSControl* ckksControl;
  81
  82 // Use this to inject your own SecureBackup object. It must conform to the OctagonEscrowRecoverer protocol.
  83 @property (nullable, strong) id sbd;
  84
  85 // Create a new synchronous OTControl if one doesn't already exist in context.
  86 - (OTControl* _Nullable)makeOTControl:(NSError**)error;
  87 @end
  88
  89 // OTBottleIDs: an Obj-C Tuple
  90
  91 @interface OTBottleIDs : NSObject
  92 @property (strong) NSArray<NSString*>* preferredBottleIDs;
  93 @property (strong) NSArray<NSString*>* partialRecoveryBottleIDs;
  94 @end
  95
  96 @interface OTOperationConfiguration : NSObject <NSSecureCoding>
  97 @property (nonatomic, assign) uint64_t timeoutWaitForCKAccount;
  98 @property (nonatomic, assign) NSQualityOfService qualityOfService;
  99 @property (nonatomic, assign) BOOL discretionaryNetwork;
 100 @property (nonatomic, assign) BOOL useCachedAccountStatus;
 101 @end
 102
 103 typedef NSString* OTCliqueCDPContextType NS_STRING_ENUM;
 104 extern OTCliqueCDPContextType OTCliqueCDPContextTypeNone;
 105 extern OTCliqueCDPContextType OTCliqueCDPContextTypeSignIn;
 106 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRepair;
 107 extern OTCliqueCDPContextType OTCliqueCDPContextTypeFinishPasscodeChange;
 108 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRecoveryKeyGenerate;
 109 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRecoveryKeyNew;
 110 extern OTCliqueCDPContextType OTCliqueCDPContextTypeUpdatePasscode;
 111
 112
 113 // OTClique
 114
 115 @interface OTClique : NSObject
 116
 117 + (BOOL)platformSupportsSOS;
 118
 119 @property (nonatomic, readonly, nullable) NSString* cliqueMemberIdentifier;
 120
 121 - (instancetype) init NS_UNAVAILABLE;
 122
 123 // MARK: Clique SPI
 124
 125 /* *
 126  * @abstract, initializes a clique object given a context.  A clique object enables octagon trust operations for a given context and dsid.
 127  * @param ctx, a collection of arguments describing the world
 128  * @return an instance of octagon trust
 129  */
 130 - (instancetype)initWithContextData:(OTConfigurationContext *)ctx;
 131
 132 /* *
 133  * @abstract   Establish a new clique, reset protected data
 134  *   Reset the clique
 135  *   Delete backups
 136  *   Delete all CKKS data
 137  *
 138  * @param   ctx, context containing parameters to setup OTClique
 139  * @return  clique, returns a new clique instance
 140  * @param  error, error gets filled if something goes horribly wrong
 141  */
 142 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data error:(NSError * __autoreleasing *)error __deprecated_msg("use newFriendsWithContextData:resetReason:error: instead");
 143
 144 /* *
 145 * @abstract   Establish a new clique, reset protected data
 146 *   Reset the clique
 147 *   Delete backups
 148 *   Delete all CKKS data
 149 *
 150 * @param   ctx, context containing parameters to setup OTClique
 151 * @param    resetReason, a reason that drives cdp to perform a reset
 152 * @return  clique, returns a new clique instance
 153 * @param  error, error gets filled if something goes horribly wrong
 154 */
 155 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data resetReason:(CuttlefishResetReason)resetReason error:(NSError * __autoreleasing *)error;
 156
 157 /*
 158  * @abstract Perform a SecureBackup escrow/keychain recovery and attempt to use the information therein to join this account.
 159  *       You do not need to call joinAfterRestore after calling this method.
 160  * @param data The OTClique configuration data
 161  * @param sbdRecoveryArguments the grab bag of things you'd normally pass to SecureBackup's recoverWithInfo.
 162  * @param error Reports any error along the process, including 'incorrect secret' and 'couldn't rejoin account'.
 163  * @return a fresh new OTClique, if the account rejoin was successful. Otherwise, nil.
 164  */
 165 + (OTClique* _Nullable)performEscrowRecoveryWithContextData:(OTConfigurationContext*)data
 166                                             escrowArguments:(NSDictionary*)sbdRecoveryArguments
 167                                                       error:(NSError**)error;
 168
 169 /* *
 170  * @abstract   Create pairing channel with
 171  *
 172  * @param ctx, context containing parameters to setup the pairing channel as the initiator
 173  * @return  KCPairingChannel, An instance of a KCPairingCHannel
 174  */
 175 - (KCPairingChannel *)setupPairingChannelAsInitiator:(KCPairingChannelContext *)ctx;
 176
 177 - (KCPairingChannel * _Nullable)setupPairingChannelAsInitator:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsInitiator:error: deprecated, use setupPairingChannelAsInitiator:");
 178
 179 /* *
 180  * @abstract   Configure this peer as the acceptor during piggybacking
 181  *
 182  * @param ctx, context containing parameters to setup the pairing channel as the acceptor
 183  * @return  KCPairingChannel, An instance of a KCPairingChannel
 184  */
 185 - (KCPairingChannel *)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx;
 186
 187 - (KCPairingChannel * _Nullable)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsAcceptor:error: deprecated, use setupPairingChannelAsAcceptor:");
 188
 189 /* *
 190  * @abstract Get the cached status of clique - returns one of:
 191  *       There is no clique - you can establish one
 192  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 193  *       There is a clique and I am in it
 194  * @param error, error gets filled if something goes horribly wrong
 195  * @return  cached cliqueStatus, value will represent one of the above
 196  */
 197 - (CliqueStatus)cachedCliqueStatus:(BOOL)useCached error:(NSError * __autoreleasing *)error
 198     __deprecated_msg("use fetchCliqueStatus:");
 199
 200 /* *
 201  * @abstract Get status of clique - returns one of:
 202  *       There is no clique - you can establish one
 203  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 204  *       There is a clique and I am in it
 205  * @param error, error gets filled if something goes horribly wrong
 206  * @return  cliqueStatus, value will represent one of the above
 207  */
 208 - (CliqueStatus)fetchCliqueStatus:(NSError * __autoreleasing * _Nonnull)error;
 209
 210 /* *
 211  * @abstract Get status of clique - returns one of:
 212  *       There is no clique - you can establish one
 213  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 214  *       There is a clique and I am in it
 215  * @param configuration, behavior of operations performed follow up this operation
 216  * @param error, error gets filled if something goes horribly wrong
 217  * @return  cliqueStatus, value will represent one of the above
 218  */
 219 - (CliqueStatus)fetchCliqueStatus:(OTOperationConfiguration *)configuration error:(NSError * __autoreleasing * _Nonnull)error;
 220
 221 /* *
 222  * @abstract Exclude given a member identifier
 223  * @param   friendIdentifiers, friends to remove
 224  * @param   error, error gets filled if something goes horribly wrong
 225  * @return  BOOL, YES if successful. No if call failed.
 226  */
 227 - (BOOL)removeFriendsInClique:(NSArray<NSString*>*)friendIdentifiers error:(NSError * __autoreleasing *)error;
 228
 229  /* *
 230   * @abstract Depart (exclude self)
 231   *            Un-enroll from escrow
 232   * @param   error, error gets filled if something goes horribly wrong
 233   * @return BOOL, YES if successful. No if call failed.
 234   */
 235 - (BOOL)leaveClique:(NSError * __autoreleasing *)error;
 236
 237 /* *
 238  * @abstract Get list of peerIDs and device names
 239  * @param   error, error gets filled if something goes horribly wrong
 240  * @return friends, list of peer ids and their mapping to device names of all devices currently in the clique,
 241  *                  ex: NSDictionary[peerID, device Name];
 242  */
 243 - (NSDictionary<NSString*,NSString*>* _Nullable)peerDeviceNamesByPeerID:(NSError * __autoreleasing *)error;
 244
 245 /*
 246  * CDP bit handling
 247  */
 248
 249 + (BOOL)setCDPEnabled:(OTConfigurationContext*)arguments
 250                 error:(NSError* __autoreleasing*)error;
 251
 252 + (OTCDPStatus)getCDPStatus:(OTConfigurationContext*)arguments
 253                       error:(NSError* __autoreleasing *)error;
 254
 255 /*
 256  * User view handling
 257  */
 258
 259 /* *
 260  * @abstract Set the current status of user-controllable views. This is unavailable on TV and Watch, and will error.
 261  * @param error, This will return an error if anything goes wrong
 262  * @return success
 263  */
 264 - (BOOL)setUserControllableViewsSyncStatus:(BOOL)enabled
 265                                      error:(NSError* __autoreleasing *)error;
 266
 267 /* *
 268  * @abstract Fetch the current status of user-controllable views
 269  * @param   error, This will return an error if anything goes wrong
 270  * @return status, The status of syncing. Note that in the success case, this can be NO while error remains empty.
 271  */
 272 - (BOOL)fetchUserControllableViewsSyncingEnabled:(NSError* __autoreleasing *)error __attribute__((swift_error(nonnull_error)));
 273
 274 /* SOS glue */
 275
 276 - (BOOL)joinAfterRestore:(NSError * __autoreleasing *)error;
 277
 278 - (BOOL)safariPasswordSyncingEnabled:(NSError *__autoreleasing*)error
 279 API_DEPRECATED_WITH_REPLACEMENT("fetchUserControllableViewsSyncingEnabled",macos(10.15, 10.16), ios(13.0, 14.0), watchos(6.0, 7.0), tvos(13.0,14.0));
 280
 281 - (BOOL)isLastFriend:(NSError *__autoreleasing*)error;
 282
 283 - (BOOL)waitForInitialSync:(NSError *__autoreleasing*)error;
 284
 285 - (NSArray* _Nullable)copyViewUnawarePeerInfo:(NSError *__autoreleasing*)error;
 286
 287 - (BOOL)viewSet:(NSSet*)enabledViews disabledViews:(NSSet*)disabledViews
 288 API_DEPRECATED_WITH_REPLACEMENT("setUserControllableViewsSyncStatus",macos(10.15, 10.16), ios(13.0, 14.0), watchos(6.0, 7.0), tvos(13.0,14.0));
 289
 290
 291 - (BOOL)setUserCredentialsAndDSID:(NSString*)userLabel
 292                               password:(NSData*)userPassword
 293                                  error:(NSError *__autoreleasing*)error;
 294
 295 - (BOOL)tryUserCredentialsAndDSID:(NSString*)userLabel
 296                                         password:(NSData*)userPassword
 297                                         error:(NSError *__autoreleasing*)error;
 298
 299 - (NSArray* _Nullable)copyPeerPeerInfo:(NSError *__autoreleasing*)error;
 300
 301 - (BOOL)peersHaveViewsEnabled:(NSArray<NSString*>*)viewNames error:(NSError *__autoreleasing*)error;
 302
 303 - (BOOL)requestToJoinCircle:(NSError *__autoreleasing*)error;
 304
 305 - (BOOL)accountUserKeyAvailable;
 306
 307 /* test only */
 308 - (void)setPairingDefault:(BOOL)defaults;
 309 - (void)removePairingDefault;
 310 /* Internal/sbd only */
 311
 312
 313 /*
 314  * @abstract Ask for the list of best bottle IDs to restore for this account
 315  *    Ideally, we will replace this with a findOptimalEscrowRecordIDsWithContextData, but we're gated on
 316  *      Cuttlefish being able to read EscrowProxy (to get real escrow record IDs):
 317  *      <rdar://problem/44618259> [CUTTLEFISH] Cuttlefish needs to call Escrow Proxy to validate unmigrated accounts
 318  * @param data The OTClique configuration data
 319  * @param error Reports any error along the process
 320  * @return A pair of lists of escrow record IDs
 321  */
 322 + (OTBottleIDs* _Nullable)findOptimalBottleIDsWithContextData:(OTConfigurationContext*)data
 323                                                         error:(NSError**)error;
 324
 325 // This call is a noop.
 326 + (instancetype _Nullable)recoverWithContextData:(OTConfigurationContext*)data
 327                                         bottleID:(NSString*)bottleID
 328                                  escrowedEntropy:(NSData*)entropy
 329                                            error:(NSError**)error __deprecated_msg("recoverWithContextData:bottleID:escrowedEntropy:error: deprecated, use performEscrowRecoveryWithContextData:escrowArguments:error");
 330
 331 // used by sbd to fill in the escrow record
 332 // You must have the entitlement "com.apple.private.octagon.escrow-content" to use this
 333 // Also known as kSecEntitlementPrivateOctagonEscrow
 334 - (void)fetchEscrowContents:(void (^)(NSData* _Nullable entropy,
 335                                       NSString* _Nullable bottleID,
 336                                       NSData* _Nullable signingPublicKey,
 337                                       NSError* _Nullable error))reply;
 338
 339 // used by sbd to enroll a recovery key in octagon
 340 + (void)setNewRecoveryKeyWithData:(OTConfigurationContext *)ctx
 341                       recoveryKey:(NSString*)recoveryKey
 342                             reply:(void(^)(SecRecoveryKey * _Nullable rk,
 343                                            NSError* _Nullable error))reply;
 344
 345 // used by sbd to recover octagon data by providing a
 346 + (void)recoverOctagonUsingData:(OTConfigurationContext *)ctx
 347                     recoveryKey:(NSString*)recoveryKey
 348                           reply:(void(^)(NSError* _Nullable error))reply;
 349
 350
 351 // CoreCDP will call this function when they failed to complete a successful CDP state machine run.
 352 // Errors provided may be propagated from layers beneath CoreCDP, or contain the CoreCDP cause of failure.
 353 - (void)performedFailureCDPStateMachineRun:(OTCliqueCDPContextType)type
 354                                      error:(NSError * _Nullable)error
 355                                      reply:(void(^)(NSError* _Nullable error))reply;
 356
 357 // CoreCDP will call this function when they complete a successful CDP state machine run.
 358 - (void)performedSuccessfulCDPStateMachineRun:(OTCliqueCDPContextType)type
 359                                         reply:(void(^)(NSError* _Nullable error))reply;
 360
 361 // CoreCDP will call this function when they are upgrading an account from SA to HSA2
 362 - (BOOL)waitForOctagonUpgrade:(NSError** _Nullable)error;
 363
 364
 365 /*
 366 * @abstract CoreCDP to call this function when they need to reset protected data.
 367 *   This routine resets all circles, creates a new octagon and sos circle, then puts this device into each circle.
 368 *   This routine does not create a new escrow record
 369 *   This routine will need ensure OTConfigurationContext contains appleID and passwordEquivalentToken to delete all CDP records
 370 * @param data The OTClique configuration data
 371 * @param error Reports any error along the process
 372 * @return a new clique
 373 */
 374 + (OTClique* _Nullable)resetProtectedData:(OTConfigurationContext*)data error:(NSError**)error;
 375 @end
 376
 377 NS_ASSUME_NONNULL_END
 378
 379 #endif /* OBJC2 */
 380 #endif /* OctagonTrust_h */