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