OSX/sec/SOSCircle/SecureObjectSync/SOSForerunnerSession.h

   1 /*
   2  * Copyright (c) 2013-2014 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  @header SOSForerunnerSession.h
  26  Describes interfaces for both requesting and approving forerunner sessions. A
  27  A forerunner session encapsulates the following control flow between two
  28  devices, Requestor and Acceptor, when Requestor attempts to join a syncing
  29  circle already inhabited by Acceptor.
  30
  31  0. Requestor creates a requesting session containing PAKE key pair
  32  1. Requestor creates a packet to request membership in the syncing circle;
  33         Packet includes session public key
  34  2. Requestor sends RequestPacket to Acceptor using an interface of its
  35         choosing
  36  3. Acceptor receives RequestPacket.
  37  4. Acceptor creates an approving session containing PAKE key pair with
  38     RequestPacket
  39  5. Acceptor generates Secret, a six-digit code that never leaves Acceptor
  40  6. Acceptor generates ChallengePacket, derived from the public key in
  41     RequestPacket and Secret
  42  7. Acceptor sends ChallengePacket to Requestor using an interface of its
  43     choosing
  44  8. Requestor receives ChallengePacket
  45  9. Requestor asks User to enter Secret
  46 10. Requestor creates ResponsePacket, derived from Secret and the public key
  47     contained in ChallengePacket
  48 11. Requestor sends ResponsePacket to Acceptor using an interface of its
  49     choosing
  50 12. Acceptor receives ResponsePacket
  51 13. Acceptor validates ResponsePacket
  52 14. Acceptor generates HSA2Code
  53 14b. Acceptor encrypts and attests to the HSA2Code to its session key
  54 15. Acceptor sends encrypted HSA2Code to Requestor using an interface of its
  55     choosing
  56 16. Requestor receives encrypted HSA2Code
  57 16b. Requestor decrypts and verifies HSA2Code
  58 17. Requestor sends HSA2Code to Apple
  59 18. Apple adds Requestor to trusted device list
  60 19. Requestor generates Identity
  61 20. Requestor applies to syncing circle with Identity
  62  */
  63
  64 #ifndef _SEC_SOSFORERUNNERSESSION_H_
  65 #define _SEC_SOSFORERUNNERSESSION_H_
  66
  67 #include <sys/cdefs.h>
  68 #include <os/base.h>
  69 #include <os/object.h>
  70 #include <CoreFoundation/CoreFoundation.h>
  71 #include <CoreFoundation/CFError.h>
  72
  73 __BEGIN_DECLS
  74
  75 /*!
  76  @const SECFR_API_VERSION
  77  An API version that may be used during the preprocessing phase to determine
  78  which version of the API is being built against. This may be used to guard
  79  against breaking due to changes in the API that are not sync'ed against your
  80  project. For example, if version 20150424 adds a new method,
  81  SOSFRSNewMethod(), you may guard your use of that method with
  82
  83  #if SECFR_API_VERSION >= 20150424
  84  SOSFRSNewMethod();
  85  #endif // SECFR_API_VERSION >= 20150424
  86  */
  87 #define SECFR_API_VERSION 20150424
  88
  89 /*!
  90  @type SOSForerunnerRequestorSessionRef
  91  An opaque type representing the requesting side of a session being used to
  92  enter the requestor into a syncing circle. The object has no thread affinity,
  93  but it is not safe to invoke methods on the same object from multiple threads
  94  concurrently.
  95  */
  96 typedef struct __OpaqueSOSForerunnerRequestorSession
  97                 *SOSForerunnerRequestorSessionRef;
  98
  99 /*!
 100  @function SOSForerunnerRequestorSessionGetTypeID
 101
 102  @abstract
 103  Returns the type identifier for the requestor session class.
 104
 105  @result
 106  A type identifier.
 107  */
 108 OS_EXPORT OS_WARN_RESULT
 109 CFTypeID
 110 SOSForerunnerRequestorSessionGetTypeID(void);
 111
 112 /*!
 113  @function SOSForerunnerRequestorSessionCreate
 114
 115  @abstract
 116  Creates a new requesting session object to negotiate entry into a syncing
 117  circle.
 118
 119  @param allocator
 120  The vestigal CoreFoundation allocator. Pass NULL or
 121  {@link kCFAllocatorDefault}.
 122
 123  @param username
 124  The AppleID for the account whose syncing circle is to be joined.
 125
 126  @param dsid
 127  The DirectoryServices identifier for the AppleID given in {@param username}.
 128
 129  @result
 130  A new session object. This object must be released with {@link CFRelease} when
 131  it is no longer needed.
 132  */
 133 OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT
 134 SOSForerunnerRequestorSessionRef
 135 SOSForerunnerRequestorSessionCreate(CFAllocatorRef allocator,
 136                 CFStringRef username, uint64_t dsid);
 137
 138 /*!
 139  @function SOSFRSCopyRequestPacket
 140
 141  @abstract
 142  Returns a request packet suitable for requesting to join a syncing circle.
 143
 144  @param session
 145  The session from which to copy the request packet.
 146
 147  @param error
 148  Upon unsuccessful return, an error object describing the failure condition. May
 149  be NULL.
 150
 151  @result
 152  A new data object representing the request packet.
 153  */
 154 OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
 155 CFDataRef
 156 SOSFRSCopyRequestPacket(SOSForerunnerRequestorSessionRef session,
 157                 CFErrorRef *error);
 158
 159 /*!
 160  @function SOSFRSCopyResponsePacket
 161
 162  @abstract
 163  Returns a response packet suitable for responding to a challenge to join a
 164  syncing circle.
 165
 166  @param session
 167  The session from which to copy the response packet.
 168
 169  @param challenge
 170  The challenge packet received from the approving device.
 171
 172  @param secret
 173  The six-digit secret generated by the approving device and entered by the user
 174  on the requesting device.
 175
 176  @param peerInfo
 177  A dictionary containing information about the peer, such as GPS location,
 178  device type, etc. Pass NULL for now. This contents of this dictionary will be
 179  defined at a future date.
 180
 181  @param error
 182  Upon unsuccessful return, an error object describing the failure condition. May
 183  be NULL.
 184
 185  @result
 186  A new data object representing the response packet.
 187  */
 188 OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
 189 OS_NONNULL3
 190 CFDataRef
 191 SOSFRSCopyResponsePacket(SOSForerunnerRequestorSessionRef session,
 192                 CFDataRef challenge, CFStringRef secret, CFDictionaryRef peerInfo,
 193                 CFErrorRef *error);
 194
 195 /*!
 196  @function SOSFRSCopyHSA2CodeFromPacket
 197
 198  @abstract
 199  Returns the HSA2 join code from the encrypted packet sent by the approving
 200  device.
 201
 202  @param session
 203  The session from which to copy the HSA2 join code.
 204
 205  @param hsa2packet
 206  The encrypted packet containing the HSA2 join code sent by the approving
 207  device.
 208
 209  @result
 210  A new data object representing the HSA2 join code.
 211  */
 212 OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
 213 CFDataRef
 214 SOSFRSCopyHSA2CodeFromPacket(SOSForerunnerRequestorSessionRef session,
 215                 CFDataRef hsa2packet, CFErrorRef *error);
 216
 217 /*!
 218  @function SOSFRSCopyDecryptedData
 219
 220  @abstract
 221  Decrypts data received through the secured communication channel negotiated by
 222  the session.
 223
 224  @param session
 225  The session that the encrypted data is associated with.
 226
 227  @param encrypted
 228  The encrypted data received from the approving device.
 229
 230  @result
 231  A new data object representing the decrypted data received from the approving
 232  device.
 233  */
 234 OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
 235 CFDataRef
 236 SOSFRSCopyDecryptedData(SOSForerunnerRequestorSessionRef session,
 237                 CFDataRef encrypted);
 238
 239 /*!
 240  @type SOSForerunnerAcceptorSessionRef
 241  An opaque type representing the accepting side of a session being used to
 242  enter a new requesting device into the syncing circle of which the acceptor is
 243  a member. The object has no thread affinity, but it is not safe to invoke
 244  methods on the same object from multiple threads concurrently.
 245  */
 246 typedef struct __OpaqueSOSForerunnerAcceptorSession
 247                 *SOSForerunnerAcceptorSessionRef;
 248
 249 /*!
 250  @function SOSForerunnerAcceptorSessionGetTypeID
 251
 252  @abstract
 253  Returns the type identifier for the acceptor session class.
 254
 255  @result
 256  A type identifier.
 257  */
 258 OS_EXPORT OS_WARN_RESULT
 259 CFTypeID
 260 SOSForerunnerAcceptorSessionGetTypeID(void);
 261
 262 /*!
 263  @function SOSForerunnerAcceptorSessionCreate
 264
 265  @abstract
 266  Creates a new accepting session object to negotiate entry of a requesting
 267  device into a syncing circle.
 268
 269  @param allocator
 270  The vestigal CoreFoundation allocator. Pass NULL or
 271  {@link kCFAllocatorDefault}.
 272
 273  @param username
 274  The AppleID for the account whose syncing circle is to be joined.
 275
 276  @param dsid
 277  The DirectoryServices identifier for the AppleID given in {@param username}.
 278
 279  @param circleSecret
 280  The six-digit secret generated to join the syncing circle.
 281
 282  @result
 283  A new session object. This object must be released with {@link CFRelease} when
 284  it is no longer needed.
 285  */
 286 OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL2
 287 OS_NONNULL4
 288 SOSForerunnerAcceptorSessionRef
 289 SOSForerunnerAcceptorSessionCreate(CFAllocatorRef allocator,
 290                 CFStringRef username, uint64_t dsid, CFStringRef circleSecret);
 291
 292 /*!
 293  @function SOSFASCopyChallengePacket
 294
 295  @abstract
 296  Returns a challenge packet that a requesting device must satisfy to join the
 297  syncing circle of which the accepting device is a member.
 298
 299  @param session
 300  The session from which to copy the challenge packet.
 301
 302  @param requestorPacket
 303  The initial requestor packet received from the device requesting to join the
 304  circle.
 305
 306  @param error
 307  Upon unsuccessful return, an error object describing the failure condition. May
 308  be NULL.
 309
 310  @result
 311  A new data object representing the challenge packet.
 312  */
 313 OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
 314 CFDataRef
 315 SOSFASCopyChallengePacket(SOSForerunnerAcceptorSessionRef session,
 316                 CFDataRef requestorPacket, CFErrorRef *error);
 317
 318 /*!
 319  @function SOSFASCopyHSA2Packet
 320
 321  @abstract
 322  Processes the packet sent in response to the challenge packet by the requesting
 323  device and, if the challenge is satisfied, arms auto-acceptance into the HSA2
 324  trusted device list and returns a packet containing the HSA2 join code to be
 325  sent to the requestor.
 326
 327  @param session
 328  The session associated with the challenge that the response was sent to
 329  satisfy.
 330
 331  @param responsePacket
 332  The packet sent by the requestor in response to the challenge.
 333
 334  @param hsa2Code
 335  The code for the requestor to use to join the HSA2 trusted device list.
 336
 337  @param error
 338  Upon unsuccessful return, an error object describing the failure condition.
 339  Unlike the other interfaces in this API suite, this parameter cannot be NULL,
 340  as different error codes indicate different caller responsibilities.
 341
 342  If the underlying error is EAGAIN, the caller may attempt to re-negotiate with
 343  the requesting device. If too many attempts are made to re-negotiate, EBADMSG
 344  will be returned. At this point, the caller may not attempt to create another
 345  HSA2 packet; the connection should be terminated and the session torn down.
 346
 347  @result
 348  An encrypted packet containing the HSA2 join code. NULL in the event of
 349  failure.
 350  */
 351 OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
 352 OS_NONNULL2 OS_NONNULL3 OS_NONNULL4
 353 CFDataRef
 354 SOSFASCopyHSA2Packet(SOSForerunnerAcceptorSessionRef session,
 355                 CFDataRef responsePacket, CFDataRef hsa2Code, CFErrorRef *error);
 356
 357 /*!
 358  @function SOSFASCopyEncryptedData
 359
 360  @abstract
 361  Encrypts data for transport over the negotiated session.
 362
 363  @param session
 364  The session object for which to encrypt the given data.
 365
 366  @param data
 367  The data to encrypt.
 368
 369  @result
 370  The encrypted representation of {@param data}.
 371  */
 372 OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
 373 OS_NONNULL2
 374 CFDataRef
 375 SOSFASCopyEncryptedData(SOSForerunnerAcceptorSessionRef session,
 376                 CFDataRef data);
 377
 378 __END_DECLS
 379
 380 #endif /* _SEC_SOSFORERUNNERSESSION_H_ */