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 NS_ASSUME_NONNULL_BEGIN
  48
  49 NSString* OTCliqueStatusToString(CliqueStatus status);
  50 CliqueStatus OTCliqueStatusFromString(NSString* str);
  51
  52 @class KCPairingChannelContext;
  53 @class KCPairingChannel;
  54 @class OTPairingChannel;
  55 @class OTPairingChannelContext;
  56 @class OTControl;
  57
  58 extern NSString* kSecEntitlementPrivateOctagonEscrow;
  59
  60 @interface OTConfigurationContext : NSObject
  61 @property (nonatomic, copy, nullable) NSString* context;
  62 @property (nonatomic, copy) NSString* dsid;
  63 @property (nonatomic, copy) NSString* altDSID;
  64 @property (nonatomic, strong, nullable) SFSignInAnalytics* analytics;
  65
  66 // Use this to inject your own OTControl object. It must be configured as synchronous.
  67 @property (nullable, strong) OTControl* otControl;
  68 // Use this to inject your own SecureBackup object. It must conform to the OctagonEscrowRecoverer protocol.
  69 @property (nullable, strong) id sbd;
  70
  71 // Create a new synchronous OTControl if one doesn't already exist in context.
  72 - (OTControl* _Nullable)makeOTControl:(NSError**)error;
  73 @end
  74
  75 // OTBottleIDs: an Obj-C Tuple
  76
  77 @interface OTBottleIDs : NSObject
  78 @property (strong) NSArray<NSString*>* preferredBottleIDs;
  79 @property (strong) NSArray<NSString*>* partialRecoveryBottleIDs;
  80 @end
  81
  82 @interface OTOperationConfiguration : NSObject <NSSecureCoding>
  83 @property (nonatomic, assign) uint64_t timeoutWaitForCKAccount;
  84 @property (nonatomic, assign) NSQualityOfService qualityOfService;
  85 @property (nonatomic, assign) BOOL discretionaryNetwork;
  86 @property (nonatomic, assign) BOOL useCachedAccountStatus;
  87 @end
  88
  89 typedef NSString* OTCliqueCDPContextType NS_STRING_ENUM;
  90 extern OTCliqueCDPContextType OTCliqueCDPContextTypeNone;
  91 extern OTCliqueCDPContextType OTCliqueCDPContextTypeSignIn;
  92 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRepair;
  93 extern OTCliqueCDPContextType OTCliqueCDPContextTypeFinishPasscodeChange;
  94 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRecoveryKeyGenerate;
  95 extern OTCliqueCDPContextType OTCliqueCDPContextTypeRecoveryKeyNew;
  96 extern OTCliqueCDPContextType OTCliqueCDPContextTypeUpdatePasscode;
  97
  98
  99 // OTClique
 100
 101 @interface OTClique : NSObject
 102
 103 + (BOOL)platformSupportsSOS;
 104
 105 @property (nonatomic, readonly, nullable) NSString* cliqueMemberIdentifier;
 106
 107 - (instancetype) init NS_UNAVAILABLE;
 108
 109 // MARK: Clique SPI
 110
 111 /* *
 112  * @abstract, initializes a clique object given a context.  A clique object enables octagon trust operations for a given context and dsid.
 113  * @param ctx, a unique string that is used as a way to retrieve current trust state
 114  * @return an instance of octagon trust
 115  */
 116 - (instancetype _Nullable)initWithContextData:(OTConfigurationContext *)ctx error:(NSError * __autoreleasing * _Nonnull)error;
 117
 118 /* *
 119  * @abstract   Establish a new clique, reset protected data
 120  *   Reset the clique
 121  *   Delete backups
 122  *   Delete all CKKS data
 123  *
 124  * @param   ctx, context containing parameters to setup OTClique
 125  * @return  clique, returns a new clique instance
 126  * @param  error, error gets filled if something goes horribly wrong
 127  */
 128 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data error:(NSError * __autoreleasing *)error __deprecated_msg("use newFriendsWithContextData:resetReason:error: instead");
 129
 130 /* *
 131 * @abstract   Establish a new clique, reset protected data
 132 *   Reset the clique
 133 *   Delete backups
 134 *   Delete all CKKS data
 135 *
 136 * @param   ctx, context containing parameters to setup OTClique
 137 * @param    resetReason, a reason that drives cdp to perform a reset
 138 * @return  clique, returns a new clique instance
 139 * @param  error, error gets filled if something goes horribly wrong
 140 */
 141 + (instancetype _Nullable)newFriendsWithContextData:(OTConfigurationContext*)data resetReason:(CuttlefishResetReason)resetReason error:(NSError * __autoreleasing *)error;
 142
 143 /*
 144  * @abstract Perform a SecureBackup escrow/keychain recovery and attempt to use the information therein to join this account.
 145  *       You do not need to call joinAfterRestore after calling this method.
 146  * @param data The OTClique configuration data
 147  * @param sbdRecoveryArguments the grab bag of things you'd normally pass to SecureBackup's recoverWithInfo.
 148  * @param error Reports any error along the process, including 'incorrect secret' and 'couldn't rejoin account'.
 149  * @return a fresh new OTClique, if the account rejoin was successful. Otherwise, nil.
 150  */
 151 + (OTClique* _Nullable)performEscrowRecoveryWithContextData:(OTConfigurationContext*)data
 152                                             escrowArguments:(NSDictionary*)sbdRecoveryArguments
 153                                                       error:(NSError**)error;
 154
 155 /* *
 156  * @abstract   Create pairing channel with
 157  *
 158  * @param ctx, context containing parameters to setup OTClique
 159  * @param pairingChannelContext, context containing parameters to setup the pairing channel as the initiator
 160  * @return  clique, An instance of an OTClique
 161  * @return  error, error gets filled if something goes horribly wrong
 162  */
 163 - (KCPairingChannel *)setupPairingChannelAsInitiator:(KCPairingChannelContext *)ctx;
 164
 165 - (KCPairingChannel * _Nullable)setupPairingChannelAsInitator:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsInitiator:error: deprecated, use setupPairingChannelAsInitiator:");
 166
 167 /* *
 168  * @abstract   Configure this peer as the acceptor during piggybacking
 169  *
 170  * @param ctx, context containing parameters to setup OTClique
 171  * @param pairingChannelContext, context containing parameters to setup the pairing channel as the acceptor
 172  * @param error, error gets filled if something goes horribly wrong
 173  * @return  KCPairingChannel, An instance of an OTClique
 174  */
 175 - (KCPairingChannel *)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx;
 176
 177 - (KCPairingChannel * _Nullable)setupPairingChannelAsAcceptor:(KCPairingChannelContext *)ctx error:(NSError * __autoreleasing *)error __deprecated_msg("setupPairingChannelAsAcceptor:error: deprecated, use setupPairingChannelAsAcceptor:");
 178
 179 /* *
 180  * @abstract Get the cached status of clique - returns one of:
 181  *       There is no clique - you can establish one
 182  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 183  *       There is a clique and I am in it
 184  * @param error, error gets filled if something goes horribly wrong
 185  * @return  cached cliqueStatus, value will represent one of the above
 186  */
 187 - (CliqueStatus)cachedCliqueStatus:(BOOL)useCached error:(NSError * __autoreleasing *)error
 188     __deprecated_msg("use fetchCliqueStatus:");
 189
 190 /* *
 191  * @abstract Get status of clique - returns one of:
 192  *       There is no clique - you can establish one
 193  *       There is a clique and I am not in it - you should get a voucher to join or tell another peer to trust us
 194  *       There is a clique and I am in it
 195  * @param error, error gets filled if something goes horribly wrong
 196  * @return  cliqueStatus, value will represent one of the above
 197  */
 198 - (CliqueStatus)fetchCliqueStatus:(NSError * __autoreleasing * _Nonnull)error;
 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 configuration, behavior of operations performed follow up this operation
 206  * @param error, error gets filled if something goes horribly wrong
 207  * @return  cliqueStatus, value will represent one of the above
 208  */
 209 - (CliqueStatus)fetchCliqueStatus:(OTOperationConfiguration *)configuration error:(NSError * __autoreleasing * _Nonnull)error;
 210
 211 /* *
 212  * @abstract Exclude given a member identifier
 213  * @param   friendIdentifiers, friends to remove
 214  * @param   error, error gets filled if something goes horribly wrong
 215  * @return  BOOL, YES if successful. No if call failed.
 216  */
 217 - (BOOL)removeFriendsInClique:(NSArray<NSString*>*)friendIdentifiers error:(NSError * __autoreleasing *)error;
 218
 219  /* *
 220   * @abstract Depart (exclude self)
 221   *            Un-enroll from escrow
 222   * @param   error, error gets filled if something goes horribly wrong
 223   * @return BOOL, YES if successful. No if call failed.
 224   */
 225 - (BOOL)leaveClique:(NSError * __autoreleasing *)error;
 226
 227 /* *
 228  * @abstract Get list of peerIDs and device names
 229  * @param   error, error gets filled if something goes horribly wrong
 230  * @return friends, list of peer ids and their mapping to device names of all devices currently in the clique,
 231  *                  ex: NSDictionary[peerID, device Name];
 232  */
 233 - (NSDictionary<NSString*,NSString*>* _Nullable)peerDeviceNamesByPeerID:(NSError * __autoreleasing *)error;
 234
 235
 236
 237 /* SOS glue */
 238
 239 - (BOOL)joinAfterRestore:(NSError * __autoreleasing *)error;
 240
 241 - (BOOL)safariPasswordSyncingEnabled:(NSError *__autoreleasing*)error;
 242
 243 - (BOOL)isLastFriend:(NSError *__autoreleasing*)error;
 244
 245 - (BOOL)waitForInitialSync:(NSError *__autoreleasing*)error;
 246
 247 - (NSArray* _Nullable)copyViewUnawarePeerInfo:(NSError *__autoreleasing*)error;
 248
 249 - (BOOL)viewSet:(NSSet*)enabledViews disabledViews:(NSSet*)disabledViews;
 250
 251 - (BOOL)setUserCredentialsAndDSID:(NSString*)userLabel
 252                               password:(NSData*)userPassword
 253                                  error:(NSError *__autoreleasing*)error;
 254
 255 - (BOOL)tryUserCredentialsAndDSID:(NSString*)userLabel
 256                                         password:(NSData*)userPassword
 257                                         error:(NSError *__autoreleasing*)error;
 258
 259 - (NSArray* _Nullable)copyPeerPeerInfo:(NSError *__autoreleasing*)error;
 260
 261 - (BOOL)peersHaveViewsEnabled:(NSArray<NSString*>*)viewNames error:(NSError *__autoreleasing*)error;
 262
 263 - (BOOL)requestToJoinCircle:(NSError *__autoreleasing*)error;
 264
 265 - (BOOL)accountUserKeyAvailable;
 266
 267 /* test only */
 268 - (void)setPairingDefault:(BOOL)defaults;
 269 - (void)removePairingDefault;
 270 /* Internal/sbd only */
 271
 272
 273 /*
 274  * @abstract Ask for the list of best bottle IDs to restore for this account
 275  *    Ideally, we will replace this with a findOptimalEscrowRecordIDsWithContextData, but we're gated on
 276  *      Cuttlefish being able to read EscrowProxy (to get real escrow record IDs):
 277  *      <rdar://problem/44618259> [CUTTLEFISH] Cuttlefish needs to call Escrow Proxy to validate unmigrated accounts
 278  * @param data The OTClique configuration data
 279  * @param error Reports any error along the process
 280  * @return A pair of lists of escrow record IDs
 281  */
 282 + (OTBottleIDs* _Nullable)findOptimalBottleIDsWithContextData:(OTConfigurationContext*)data
 283                                                         error:(NSError**)error;
 284
 285 // This call is a noop.
 286 + (instancetype _Nullable)recoverWithContextData:(OTConfigurationContext*)data
 287                                         bottleID:(NSString*)bottleID
 288                                  escrowedEntropy:(NSData*)entropy
 289                                            error:(NSError**)error __deprecated_msg("recoverWithContextData:bottleID:escrowedEntropy:error: deprecated, use performEscrowRecoveryWithContextData:escrowArguments:error");
 290
 291 // used by sbd to fill in the escrow record
 292 // You must have the entitlement "com.apple.private.octagon.escrow-content" to use this
 293 // Also known as kSecEntitlementPrivateOctagonEscrow
 294 - (void)fetchEscrowContents:(void (^)(NSData* _Nullable entropy,
 295                                       NSString* _Nullable bottleID,
 296                                       NSData* _Nullable signingPublicKey,
 297                                       NSError* _Nullable error))reply;
 298
 299 // used by sbd to enroll a recovery key in octagon
 300 + (void)setNewRecoveryKeyWithData:(OTConfigurationContext *)ctx
 301                       recoveryKey:(NSString*)recoveryKey
 302                             reply:(void(^)(SecRecoveryKey * _Nullable rk,
 303                                            NSError* _Nullable error))reply;
 304
 305 // used by sbd to recover octagon data by providing a
 306 + (void)recoverOctagonUsingData:(OTConfigurationContext *)ctx
 307                     recoveryKey:(NSString*)recoveryKey
 308                           reply:(void(^)(NSError* _Nullable error))reply;
 309
 310
 311 // CoreCDP will call this function when they failed to complete a successful CDP state machine run.
 312 // Errors provided may be propagated from layers beneath CoreCDP, or contain the CoreCDP cause of failure.
 313 - (void)performedFailureCDPStateMachineRun:(OTCliqueCDPContextType)type
 314                                      error:(NSError * _Nullable)error
 315                                      reply:(void(^)(NSError* _Nullable error))reply;
 316
 317 // CoreCDP will call this function when they complete a successful CDP state machine run.
 318 - (void)performedSuccessfulCDPStateMachineRun:(OTCliqueCDPContextType)type
 319                                         reply:(void(^)(NSError* _Nullable error))reply;
 320
 321 // CoreCDP will call this function when they are upgrading an account from SA to HSA2
 322 - (BOOL)waitForOctagonUpgrade:(NSError** _Nullable)error;
 323
 324 @end
 325
 326 NS_ASSUME_NONNULL_END
 327
 328 #endif /* OBJC2 */
 329 #endif /* OctagonTrust_h */