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 typedef NS_ENUM(NSInteger, CliqueStatus) {
  29     CliqueStatusIn         = 0, /*There is a clique and I am in it*/
  30     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*/
  31     CliqueStatusPending    = 2, /*For compatibility, keeping the pending state */
  32     CliqueStatusAbsent     = 3, /*There is no clique - you can establish one */
  33     CliqueStatusNoCloudKitAccount = 4, /* no cloudkit account present */
  34     CliqueStatusError      = -1 /*unable to determine circle status, inspect CFError to find out why */
  35 };
  36
  37 #import <Security/SecRecoveryKey.h>
  38
  39 #if __OBJC2__
  40
  41 #import <Foundation/Foundation.h>
  42 #import <Security/SecureObjectSync/SOSCloudCircleInternal.h>
  43 #import <Security/SecureObjectSync/SOSPeerInfo.h>
  44 #import <Security/SecureObjectSync/SOSTypes.h>
  45 #import <Security/OTConstants.h>
  46
  47 typedef NS_ENUM(NSInteger, OTCDPStatus) {
  48     OTCDPStatusUnknown = 0,
  49     OTCDPStatusDisabled = 1,
  50     OTCDPStatusEnabled = 2,
  51 };
  52
  53 NS_ASSUME_NONNULL_BEGIN
  54
  55 NSString* OTCliqueStatusToString(CliqueStatus status);
  56 CliqueStatus OTCliqueStatusFromString(NSString* str);
  57 NSString* OTCDPStatusToString(OTCDPStatus status);
  58
  59 @class KCPairingChannelContext;
  60 @class KCPairingChannel;
  61 @class OTPairingChannel;
  62 @class OTPairingChannelContext;
  63 @class OTControl;
  64 @class CKKSControl;
  65
  66 extern NSString* kSecEntitlementPrivateOctagonEscrow;
  67
  68 @interface OTConfigurationContext : NSObject
  69 @property (nonatomic, copy) NSString* context;
  70 @property (nonatomic, copy, nullable) NSString* dsid;
  71 @property (nonatomic, copy, nullable) NSString* altDSID;
  72 @property (nonatomic, strong, nullable) SFSignInAnalytics* analytics;
  73 @property (nonatomic, copy, nullable) NSString* authenticationAppleID;
  74 @property (nonatomic, copy, nullable) NSString* passwordEquivalentToken;
  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  * Much like initWithContextData, but might fail. There are currently no failures possible.
 134  */
 135 - (instancetype _Nullable)initWithContextData:(OTConfigurationContext *)ctx error:(NSError**)error __deprecated_msg("Use initWithContextData instead");
 136
 137 /* *
 138  * @abstract   Establish a new clique, reset protected data
 139  *   Reset the clique
 140  *   Delete backups
 141  *   Delete all CKKS data
 142  *
 143  * @param   ctx, context containing parameters to setup OTClique
 144  * @return  clique, returns a new clique instance
 145  * @param  error, error gets filled if something goes horribly wrong
 146  */
 147 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data error:(NSError * __autoreleasing *)error __deprecated_msg("use newFriendsWithContextData:resetReason:error: instead");
 148
 149 /* *
 150 * @abstract   Establish a new clique, reset protected data
 151 *   Reset the clique
 152 *   Delete backups
 153 *   Delete all CKKS data
 154 *
 155 * @param   ctx, context containing parameters to setup OTClique
 156 * @param    resetReason, a reason that drives cdp to perform a reset
 157 * @return  clique, returns a new clique instance
 158 * @param  error, error gets filled if something goes horribly wrong
 159 */
 160 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data resetReason:(CuttlefishResetReason)resetReason error:(NSError * __autoreleasing *)error;
 161
 162 /*
 163  * @abstract Perform a SecureBackup escrow/keychain recovery and attempt to use the information therein to join this account.
 164  *       You do not need to call joinAfterRestore after calling this method.
 165  * @param data The OTClique configuration data
 166  * @param sbdRecoveryArguments the grab bag of things you'd normally pass to SecureBackup's recoverWithInfo.
 167  * @param error Reports any error along the process, including 'incorrect secret' and 'couldn't rejoin account'.
 168  * @return a fresh new OTClique, if the account rejoin was successful. Otherwise, nil.
 169  */
 170 + (OTClique* _Nullable)performEscrowRecoveryWithContextData:(OTConfigurationContext*)data
 171                                             escrowArguments:(NSDictionary*)sbdRecoveryArguments
 172                                                       error:(NSError**)error;
 173
 174 /* *
 175  * @abstract   Create pairing channel with
 176  *
 177  * @param ctx, context containing parameters to setup the pairing channel as the initiator
 178  * @return  KCPairingChannel, An instance of a KCPairingCHannel
 179  */
 180 - (KCPairingChannel *)setupPairingChannelAsInitiator:(KCPairingChannelContext *)ctx;
 181
 182 - (KCPairingChannel * _Nullable)setupPairingChannelAsInitator:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsInitiator:error: deprecated, use setupPairingChannelAsInitiator:");
 183
 184 /* *
 185  * @abstract   Configure this peer as the acceptor during piggybacking
 186  *
 187  * @param ctx, context containing parameters to setup the pairing channel as the acceptor
 188  * @return  KCPairingChannel, An instance of a KCPairingChannel
 189  */
 190 - (KCPairingChannel *)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx;
 191
 192 - (KCPairingChannel * _Nullable)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsAcceptor:error: deprecated, use setupPairingChannelAsAcceptor:");
 193
 194 /* *
 195  * @abstract Get the cached status of clique - returns one of:
 196  *       There is no clique - you can establish one
 197  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 198  *       There is a clique and I am in it
 199  * @param error, error gets filled if something goes horribly wrong
 200  * @return  cached cliqueStatus, value will represent one of the above
 201  */
 202 - (CliqueStatus)cachedCliqueStatus:(BOOL)useCached error:(NSError * __autoreleasing *)error
 203     __deprecated_msg("use fetchCliqueStatus:");
 204
 205 /* *
 206  * @abstract Get status of clique - returns one of:
 207  *       There is no clique - you can establish one
 208  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 209  *       There is a clique and I am in it
 210  * @param error, error gets filled if something goes horribly wrong
 211  * @return  cliqueStatus, value will represent one of the above
 212  */
 213 - (CliqueStatus)fetchCliqueStatus:(NSError * __autoreleasing * _Nonnull)error;
 214
 215 /* *
 216  * @abstract Get status of clique - returns one of:
 217  *       There is no clique - you can establish one
 218  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 219  *       There is a clique and I am in it
 220  * @param configuration, behavior of operations performed follow up this operation
 221  * @param error, error gets filled if something goes horribly wrong
 222  * @return  cliqueStatus, value will represent one of the above
 223  */
 224 - (CliqueStatus)fetchCliqueStatus:(OTOperationConfiguration *)configuration error:(NSError * __autoreleasing * _Nonnull)error;
 225
 226 /* *
 227  * @abstract Exclude given a member identifier
 228  * @param   friendIdentifiers, friends to remove
 229  * @param   error, error gets filled if something goes horribly wrong
 230  * @return  BOOL, YES if successful. No if call failed.
 231  */
 232 - (BOOL)removeFriendsInClique:(NSArray<NSString*>*)friendIdentifiers error:(NSError * __autoreleasing *)error;
 233
 234  /* *
 235   * @abstract Depart (exclude self)
 236   *            Un-enroll from escrow
 237   * @param   error, error gets filled if something goes horribly wrong
 238   * @return BOOL, YES if successful. No if call failed.
 239   */
 240 - (BOOL)leaveClique:(NSError * __autoreleasing *)error;
 241
 242 /* *
 243  * @abstract Get list of peerIDs and device names
 244  * @param   error, error gets filled if something goes horribly wrong
 245  * @return friends, list of peer ids and their mapping to device names of all devices currently in the clique,
 246  *                  ex: NSDictionary[peerID, device Name];
 247  */
 248 - (NSDictionary<NSString*,NSString*>* _Nullable)peerDeviceNamesByPeerID:(NSError * __autoreleasing *)error;
 249
 250
 251 /*
 252  * CDP bit handling
 253  */
 254
 255 + (BOOL)setCDPEnabled:(OTConfigurationContext*)arguments
 256                 error:(NSError* __autoreleasing*)error;
 257
 258 + (OTCDPStatus)getCDPStatus:(OTConfigurationContext*)arguments
 259                       error:(NSError* __autoreleasing *)error;
 260
 261 /* SOS glue */
 262
 263 - (BOOL)joinAfterRestore:(NSError * __autoreleasing *)error;
 264
 265 - (BOOL)safariPasswordSyncingEnabled:(NSError *__autoreleasing*)error;
 266
 267 - (BOOL)isLastFriend:(NSError *__autoreleasing*)error;
 268
 269 - (BOOL)waitForInitialSync:(NSError *__autoreleasing*)error;
 270
 271 - (NSArray* _Nullable)copyViewUnawarePeerInfo:(NSError *__autoreleasing*)error;
 272
 273 - (BOOL)viewSet:(NSSet*)enabledViews disabledViews:(NSSet*)disabledViews;
 274
 275 - (BOOL)setUserCredentialsAndDSID:(NSString*)userLabel
 276                               password:(NSData*)userPassword
 277                                  error:(NSError *__autoreleasing*)error;
 278
 279 - (BOOL)tryUserCredentialsAndDSID:(NSString*)userLabel
 280                                         password:(NSData*)userPassword
 281                                         error:(NSError *__autoreleasing*)error;
 282
 283 - (NSArray* _Nullable)copyPeerPeerInfo:(NSError *__autoreleasing*)error;
 284
 285 - (BOOL)peersHaveViewsEnabled:(NSArray<NSString*>*)viewNames error:(NSError *__autoreleasing*)error;
 286
 287 - (BOOL)requestToJoinCircle:(NSError *__autoreleasing*)error;
 288
 289 - (BOOL)accountUserKeyAvailable;
 290
 291 /* test only */
 292 - (void)setPairingDefault:(BOOL)defaults;
 293 - (void)removePairingDefault;
 294 /* Internal/sbd only */
 295
 296
 297 /*
 298  * @abstract Ask for the list of best bottle IDs to restore for this account
 299  *    Ideally, we will replace this with a findOptimalEscrowRecordIDsWithContextData, but we're gated on
 300  *      Cuttlefish being able to read EscrowProxy (to get real escrow record IDs):
 301  *      <rdar://problem/44618259> [CUTTLEFISH] Cuttlefish needs to call Escrow Proxy to validate unmigrated accounts
 302  * @param data The OTClique configuration data
 303  * @param error Reports any error along the process
 304  * @return A pair of lists of escrow record IDs
 305  */
 306 + (OTBottleIDs* _Nullable)findOptimalBottleIDsWithContextData:(OTConfigurationContext*)data
 307                                                         error:(NSError**)error;
 308
 309 // This call is a noop.
 310 + (instancetype _Nullable)recoverWithContextData:(OTConfigurationContext*)data
 311                                         bottleID:(NSString*)bottleID
 312                                  escrowedEntropy:(NSData*)entropy
 313                                            error:(NSError**)error __deprecated_msg("recoverWithContextData:bottleID:escrowedEntropy:error: deprecated, use performEscrowRecoveryWithContextData:escrowArguments:error");
 314
 315 // used by sbd to fill in the escrow record
 316 // You must have the entitlement "com.apple.private.octagon.escrow-content" to use this
 317 // Also known as kSecEntitlementPrivateOctagonEscrow
 318 - (void)fetchEscrowContents:(void (^)(NSData* _Nullable entropy,
 319                                       NSString* _Nullable bottleID,
 320                                       NSData* _Nullable signingPublicKey,
 321                                       NSError* _Nullable error))reply;
 322
 323 // used by sbd to enroll a recovery key in octagon
 324 + (void)setNewRecoveryKeyWithData:(OTConfigurationContext *)ctx
 325                       recoveryKey:(NSString*)recoveryKey
 326                             reply:(void(^)(SecRecoveryKey * _Nullable rk,
 327                                            NSError* _Nullable error))reply;
 328
 329 // used by sbd to recover octagon data by providing a
 330 + (void)recoverOctagonUsingData:(OTConfigurationContext *)ctx
 331                     recoveryKey:(NSString*)recoveryKey
 332                           reply:(void(^)(NSError* _Nullable error))reply;
 333
 334
 335 // CoreCDP will call this function when they failed to complete a successful CDP state machine run.
 336 // Errors provided may be propagated from layers beneath CoreCDP, or contain the CoreCDP cause of failure.
 337 - (void)performedFailureCDPStateMachineRun:(OTCliqueCDPContextType)type
 338                                      error:(NSError * _Nullable)error
 339                                      reply:(void(^)(NSError* _Nullable error))reply;
 340
 341 // CoreCDP will call this function when they complete a successful CDP state machine run.
 342 - (void)performedSuccessfulCDPStateMachineRun:(OTCliqueCDPContextType)type
 343                                         reply:(void(^)(NSError* _Nullable error))reply;
 344
 345 // CoreCDP will call this function when they are upgrading an account from SA to HSA2
 346 - (BOOL)waitForOctagonUpgrade:(NSError** _Nullable)error;
 347
 348
 349 /*
 350 * @abstract CoreCDP to call this function when they need to reset protected data.
 351 *   This routine resets all circles, creates a new octagon and sos circle, then puts this device into each circle.
 352 *   This routine does not create a new escrow record
 353 *   This routine will need ensure OTConfigurationContext contains appleID and passwordEquivalentToken to delete all CDP records
 354 * @param data The OTClique configuration data
 355 * @param error Reports any error along the process
 356 * @return a new clique
 357 */
 358 + (OTClique* _Nullable)resetProtectedData:(OTConfigurationContext*)data error:(NSError**)error;
 359 @end
 360
 361 NS_ASSUME_NONNULL_END
 362
 363 #endif /* OBJC2 */
 364 #endif /* OctagonTrust_h */