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