KeychainCircle/KCJoiningSession.h

   1 //
   2 //  KCJoiningSession.h
   3 //  KeychainCircle
   4 //
   5 //
   6
   7 #import <KeychainCircle/KCSRPContext.h>
   8 #import <KeychainCircle/KCAESGCMDuplexSession.h>
   9 #include <Security/SecureObjectSync/SOSPeerInfo.h>
  10 #include <Security/SecureObjectSync/SOSCloudCircle.h>
  11
  12
  13 bool KCJoiningOctagonPiggybackingEnabled(void);
  14 bool KCSetJoiningOctagonPiggybackingEnabled(bool value);
  15
  16 NS_ASSUME_NONNULL_BEGIN
  17
  18 @protocol KCJoiningRequestCircleDelegate <NSObject>
  19 /*!
  20  Get this devices peer info (As Application)
  21
  22  @result
  23  SOSPeerInfoRef object or NULL if we had an error.
  24  */
  25 - (SOSPeerInfoRef) copyPeerInfoError: (NSError**) error;
  26
  27 /*!
  28  Handle recipt of confirmed circleJoinData over the channel
  29
  30  @parameter circleJoinData
  31  Data the acceptor made to allow us to join the circle.
  32
  33  @parameter version
  34  Piggybacking protocol version, let's secd know to expect more data
  35
  36  */
  37 - (bool) processCircleJoinData: (NSData*) circleJoinData version:(PiggyBackProtocolVersion) version error: (NSError**)error;
  38
  39 @end
  40
  41 @protocol KCJoiningRequestSecretDelegate <NSObject>
  42 /*!
  43  Get the shared secret for this session.
  44  Not called during creation or initialMessage: to allow the initial message to be sent before
  45  we know the secret.
  46  Called during message processing.
  47
  48  @result
  49  String containing shared secret for session
  50  */
  51 - (NSString*) secret;
  52
  53 /*!
  54  Handle verification failure
  55  @result
  56  NULL if we should give up. Secret to use on retry, if not.
  57  */
  58 - (NSString*) verificationFailed: (bool) codeChanged;
  59
  60 /*!
  61  Handle recipt of confirmed accountCode over the channel
  62
  63  @parameter accountCode
  64  Data the acceptor made to allow us to join the circle.
  65  */
  66 - (bool) processAccountCode: (NSString*) accountCode error: (NSError**)error;
  67
  68 @end
  69
  70 @interface KCJoiningRequestSecretSession : NSObject
  71 @property (nullable, readonly) KCAESGCMDuplexSession* session;
  72
  73 - (bool) isDone;
  74
  75 - (nullable NSData*) initialMessage: (NSError**) error;
  76 - (nullable NSData*) processMessage: (NSData*) incomingMessage error: (NSError**) error;
  77
  78 + (nullable instancetype)sessionWithSecretDelegate: (NSObject<KCJoiningRequestSecretDelegate>*) secretDelegate
  79                                               dsid: (uint64_t)dsid
  80                                              error: (NSError**) error;
  81
  82 - (nullable instancetype)initWithSecretDelegate: (NSObject<KCJoiningRequestSecretDelegate>*) secretDelegate
  83                                            dsid: (uint64_t)dsid
  84                                           error: (NSError**)error;
  85
  86 - (nullable instancetype)initWithSecretDelegate: (NSObject<KCJoiningRequestSecretDelegate>*) secretDelegate
  87                                            dsid: (uint64_t)dsid
  88                                             rng: (struct ccrng_state *)rng
  89                                           error: (NSError**)error NS_DESIGNATED_INITIALIZER;
  90
  91 - (instancetype)init NS_UNAVAILABLE;
  92
  93 @end
  94
  95 @class OTControl;
  96 @interface KCJoiningRequestCircleSession : NSObject
  97
  98 - (bool) isDone;
  99
 100 - (nullable NSData*) initialMessage: (NSError**) error;
 101 - (nullable NSData*) processMessage: (NSData*) incomingMessage error: (NSError**) error;
 102
 103 + (instancetype) sessionWithCircleDelegate: (NSObject<KCJoiningRequestCircleDelegate>*) circleDelegate
 104                                    session: (KCAESGCMDuplexSession*) session
 105                                      error: (NSError**) error;
 106
 107 - (instancetype) initWithCircleDelegate: (NSObject<KCJoiningRequestCircleDelegate>*) circleDelegate
 108                                 session: (KCAESGCMDuplexSession*) session
 109                                   error: (NSError**) error;
 110
 111
 112 - (instancetype)initWithCircleDelegate:(NSObject<KCJoiningRequestCircleDelegate>*) circleDelegate
 113                                session:(KCAESGCMDuplexSession*) session
 114                              otcontrol:(OTControl*)otcontrol
 115                                  error:(NSError**) error NS_DESIGNATED_INITIALIZER;
 116
 117 - (instancetype)init NS_UNAVAILABLE;
 118 @end
 119
 120
 121 @protocol KCJoiningAcceptCircleDelegate <NSObject>
 122 /*!
 123  Handle the request's peer info and get the blob they can use to get in circle
 124  @param peer
 125  SOSPeerInfo sent from requestor to apply to the circle
 126  @param error
 127  Error resulting in looking at peer and trying to produce circle join data
 128  @result
 129  Data containing blob the requestor can use to get in circle
 130  */
 131 - (NSData*) circleJoinDataFor: (SOSPeerInfoRef) peer
 132                         error: (NSError**) error;
 133
 134 /*!
 135  Retrieves initial sync data from the following initial sync views: backupV0, iCloud identity, and ckks tlk
 136  @param error
 137  Error returns an error if encoding the initial sync data was successful or not
 138  @result
 139  Data blob contains tlks, icloud identities, and backupv0
 140  */
 141 -(NSData*) circleGetInitialSyncViews:(SOSInitialSyncFlags)flags error:(NSError**) error;
 142 @end
 143
 144 typedef enum {
 145     kKCRetryError = 0,
 146     kKCRetryWithSameChallenge,
 147     kKCRetryWithNewChallenge
 148 } KCRetryOrNot;
 149
 150 @protocol KCJoiningAcceptSecretDelegate <NSObject>
 151 /*!
 152     Get the shared secret for this session
 153     @result
 154         String containing shared secret for session
 155 */
 156 - (NSString*) secret;
 157 /*!
 158     Get the code the other device can use to access the account
 159     @result
 160         String containing code to access the account
 161 */
 162 - (NSString*) accountCode;
 163
 164 /*!
 165  Handle verification failure
 166  @result
 167  NULL if we should permit retry with the same secret. New secret if we've changed it.
 168  */
 169 - (KCRetryOrNot) verificationFailed: (NSError**) error;
 170
 171 @end
 172
 173
 174 @interface KCJoiningAcceptSession : NSObject
 175 /*!
 176     create an appropriate joining session given the initial message.
 177
 178     @parameter message
 179         initial message received from the requestor
 180     @parameter delegate
 181         delegate which will provide data and processing (see KCJoiningAcceptSecretDelegate protocol
 182     @parameter error
 183         failures to find a session for the initial message
 184     @result
 185         KCJoiningAcceptSession that can handle the data from the peer
 186
 187  */
 188 + (nullable instancetype) sessionWithInitialMessage: (NSData*) message
 189                                      secretDelegate: (NSObject<KCJoiningAcceptSecretDelegate>*) delegate
 190                                      circleDelegate: (NSObject<KCJoiningAcceptCircleDelegate>*) delegate
 191                                                dsid: (uint64_t) dsid
 192                                               error: (NSError**) error;
 193
 194
 195 - (nullable instancetype)initWithSecretDelegate: (NSObject<KCJoiningAcceptSecretDelegate>*) delegate
 196                                  circleDelegate: (NSObject<KCJoiningAcceptCircleDelegate>*) delegate
 197                                            dsid: (uint64_t) dsid
 198                                             rng: (struct ccrng_state *)rng
 199                                           error: (NSError**) error NS_DESIGNATED_INITIALIZER;
 200
 201 /*!
 202  create an appropriate joining session given the initial message.
 203
 204  @parameter incomingMessage
 205     message received from the requestor
 206  @parameter error
 207     failures parse the message
 208  @result
 209     Data to send to the requestor, or NULL if we had an error.
 210     Calling this function when we are done results in an error return.
 211  */
 212 - (nullable NSData*) processMessage: (NSData*) incomingMessage error: (NSError**) error;
 213
 214 - (bool) isDone;
 215
 216 - (id)init NS_UNAVAILABLE;
 217
 218 @end
 219
 220 NS_ASSUME_NONNULL_END