+++ /dev/null
-/*
- * Copyright (c) 2013-2014 Apple Inc. All Rights Reserved.
- *
- * @APPLE_LICENSE_HEADER_START@
- *
- * This file contains Original Code and/or Modifications of Original Code
- * as defined in and that are subject to the Apple Public Source License
- * Version 2.0 (the 'License'). You may not use this file except in
- * compliance with the License. Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this
- * file.
- *
- * The Original Code and all software distributed under the License are
- * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
- * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
- * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
- * Please see the License for the specific language governing rights and
- * limitations under the License.
- *
- * @APPLE_LICENSE_HEADER_END@
- */
-
-/*!
- @header SOSForerunnerSession.h
- Describes interfaces for both requesting and approving forerunner sessions. A
- A forerunner session encapsulates the following control flow between two
- devices, Requestor and Acceptor, when Requestor attempts to join a syncing
- circle already inhabited by Acceptor.
-
- 0. Requestor creates a requesting session containing PAKE key pair
- 1. Requestor creates a packet to request membership in the syncing circle;
- Packet includes session public key
- 2. Requestor sends RequestPacket to Acceptor using an interface of its
- choosing
- 3. Acceptor receives RequestPacket.
- 4. Acceptor creates an approving session containing PAKE key pair with
- RequestPacket
- 5. Acceptor generates Secret, a six-digit code that never leaves Acceptor
- 6. Acceptor generates ChallengePacket, derived from the public key in
- RequestPacket and Secret
- 7. Acceptor sends ChallengePacket to Requestor using an interface of its
- choosing
- 8. Requestor receives ChallengePacket
- 9. Requestor asks User to enter Secret
-10. Requestor creates ResponsePacket, derived from Secret and the public key
- contained in ChallengePacket
-11. Requestor sends ResponsePacket to Acceptor using an interface of its
- choosing
-12. Acceptor receives ResponsePacket
-13. Acceptor validates ResponsePacket
-14. Acceptor generates HSA2Code
-14b. Acceptor encrypts and attests to the HSA2Code to its session key
-15. Acceptor sends encrypted HSA2Code to Requestor using an interface of its
- choosing
-16. Requestor receives encrypted HSA2Code
-16b. Requestor decrypts and verifies HSA2Code
-17. Requestor sends HSA2Code to Apple
-18. Apple adds Requestor to trusted device list
-19. Requestor generates Identity
-20. Requestor applies to syncing circle with Identity
- */
-
-#ifndef _SEC_SOSFORERUNNERSESSION_H_
-#define _SEC_SOSFORERUNNERSESSION_H_
-
-#include <sys/cdefs.h>
-#include <os/base.h>
-#include <os/object.h>
-#include <CoreFoundation/CoreFoundation.h>
-#include <CoreFoundation/CFError.h>
-
-__BEGIN_DECLS
-
-/*!
- @const SECFR_API_VERSION
- An API version that may be used during the preprocessing phase to determine
- which version of the API is being built against. This may be used to guard
- against breaking due to changes in the API that are not sync'ed against your
- project. For example, if version 20150424 adds a new method,
- SOSFRSNewMethod(), you may guard your use of that method with
-
- #if SECFR_API_VERSION >= 20150424
- SOSFRSNewMethod();
- #endif // SECFR_API_VERSION >= 20150424
- */
-#define SECFR_API_VERSION 20150424
-
-/*!
- @type SOSForerunnerRequestorSessionRef
- An opaque type representing the requesting side of a session being used to
- enter the requestor into a syncing circle. The object has no thread affinity,
- but it is not safe to invoke methods on the same object from multiple threads
- concurrently.
- */
-typedef struct __OpaqueSOSForerunnerRequestorSession
- *SOSForerunnerRequestorSessionRef;
-
-/*!
- @function SOSForerunnerRequestorSessionGetTypeID
-
- @abstract
- Returns the type identifier for the requestor session class.
-
- @result
- A type identifier.
- */
-OS_EXPORT OS_WARN_RESULT
-CFTypeID
-SOSForerunnerRequestorSessionGetTypeID(void);
-
-/*!
- @function SOSForerunnerRequestorSessionCreate
-
- @abstract
- Creates a new requesting session object to negotiate entry into a syncing
- circle.
-
- @param allocator
- The vestigal CoreFoundation allocator. Pass NULL or
- {@link kCFAllocatorDefault}.
-
- @param username
- The AppleID for the account whose syncing circle is to be joined.
-
- @param dsid
- The DirectoryServices identifier for the AppleID given in {@param username}.
-
- @result
- A new session object. This object must be released with {@link CFRelease} when
- it is no longer needed.
- */
-OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT
-SOSForerunnerRequestorSessionRef
-SOSForerunnerRequestorSessionCreate(CFAllocatorRef allocator,
- CFStringRef username, uint64_t dsid);
-
-/*!
- @function SOSFRSCopyRequestPacket
-
- @abstract
- Returns a request packet suitable for requesting to join a syncing circle.
-
- @param session
- The session from which to copy the request packet.
-
- @param error
- Upon unsuccessful return, an error object describing the failure condition. May
- be NULL.
-
- @result
- A new data object representing the request packet.
- */
-OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
-CFDataRef
-SOSFRSCopyRequestPacket(SOSForerunnerRequestorSessionRef session,
- CFErrorRef *error);
-
-/*!
- @function SOSFRSCopyResponsePacket
-
- @abstract
- Returns a response packet suitable for responding to a challenge to join a
- syncing circle.
-
- @param session
- The session from which to copy the response packet.
-
- @param challenge
- The challenge packet received from the approving device.
-
- @param secret
- The six-digit secret generated by the approving device and entered by the user
- on the requesting device.
-
- @param peerInfo
- A dictionary containing information about the peer, such as GPS location,
- device type, etc. Pass NULL for now. This contents of this dictionary will be
- defined at a future date.
-
- @param error
- Upon unsuccessful return, an error object describing the failure condition. May
- be NULL.
-
- @result
- A new data object representing the response packet.
- */
-OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
-OS_NONNULL3
-CFDataRef
-SOSFRSCopyResponsePacket(SOSForerunnerRequestorSessionRef session,
- CFDataRef challenge, CFStringRef secret, CFDictionaryRef peerInfo,
- CFErrorRef *error);
-
-/*!
- @function SOSFRSCopyHSA2CodeFromPacket
-
- @abstract
- Returns the HSA2 join code from the encrypted packet sent by the approving
- device.
-
- @param session
- The session from which to copy the HSA2 join code.
-
- @param hsa2packet
- The encrypted packet containing the HSA2 join code sent by the approving
- device.
-
- @result
- A new data object representing the HSA2 join code.
- */
-OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
-CFDataRef
-SOSFRSCopyHSA2CodeFromPacket(SOSForerunnerRequestorSessionRef session,
- CFDataRef hsa2packet, CFErrorRef *error);
-
-/*!
- @function SOSFRSCopyDecryptedData
-
- @abstract
- Decrypts data received through the secured communication channel negotiated by
- the session.
-
- @param session
- The session that the encrypted data is associated with.
-
- @param encrypted
- The encrypted data received from the approving device.
-
- @result
- A new data object representing the decrypted data received from the approving
- device.
- */
-OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
-CFDataRef
-SOSFRSCopyDecryptedData(SOSForerunnerRequestorSessionRef session,
- CFDataRef encrypted);
-
-/*!
- @type SOSForerunnerAcceptorSessionRef
- An opaque type representing the accepting side of a session being used to
- enter a new requesting device into the syncing circle of which the acceptor is
- a member. The object has no thread affinity, but it is not safe to invoke
- methods on the same object from multiple threads concurrently.
- */
-typedef struct __OpaqueSOSForerunnerAcceptorSession
- *SOSForerunnerAcceptorSessionRef;
-
-/*!
- @function SOSForerunnerAcceptorSessionGetTypeID
-
- @abstract
- Returns the type identifier for the acceptor session class.
-
- @result
- A type identifier.
- */
-OS_EXPORT OS_WARN_RESULT
-CFTypeID
-SOSForerunnerAcceptorSessionGetTypeID(void);
-
-/*!
- @function SOSForerunnerAcceptorSessionCreate
-
- @abstract
- Creates a new accepting session object to negotiate entry of a requesting
- device into a syncing circle.
-
- @param allocator
- The vestigal CoreFoundation allocator. Pass NULL or
- {@link kCFAllocatorDefault}.
-
- @param username
- The AppleID for the account whose syncing circle is to be joined.
-
- @param dsid
- The DirectoryServices identifier for the AppleID given in {@param username}.
-
- @param circleSecret
- The six-digit secret generated to join the syncing circle.
-
- @result
- A new session object. This object must be released with {@link CFRelease} when
- it is no longer needed.
- */
-OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL2
-OS_NONNULL4
-SOSForerunnerAcceptorSessionRef
-SOSForerunnerAcceptorSessionCreate(CFAllocatorRef allocator,
- CFStringRef username, uint64_t dsid, CFStringRef circleSecret);
-
-/*!
- @function SOSFASCopyChallengePacket
-
- @abstract
- Returns a challenge packet that a requesting device must satisfy to join the
- syncing circle of which the accepting device is a member.
-
- @param session
- The session from which to copy the challenge packet.
-
- @param requestorPacket
- The initial requestor packet received from the device requesting to join the
- circle.
-
- @param error
- Upon unsuccessful return, an error object describing the failure condition. May
- be NULL.
-
- @result
- A new data object representing the challenge packet.
- */
-OS_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1 OS_NONNULL2
-CFDataRef
-SOSFASCopyChallengePacket(SOSForerunnerAcceptorSessionRef session,
- CFDataRef requestorPacket, CFErrorRef *error);
-
-/*!
- @function SOSFASCopyHSA2Packet
-
- @abstract
- Processes the packet sent in response to the challenge packet by the requesting
- device and, if the challenge is satisfied, arms auto-acceptance into the HSA2
- trusted device list and returns a packet containing the HSA2 join code to be
- sent to the requestor.
-
- @param session
- The session associated with the challenge that the response was sent to
- satisfy.
-
- @param responsePacket
- The packet sent by the requestor in response to the challenge.
-
- @param hsa2Code
- The code for the requestor to use to join the HSA2 trusted device list.
-
- @param error
- Upon unsuccessful return, an error object describing the failure condition.
- Unlike the other interfaces in this API suite, this parameter cannot be NULL,
- as different error codes indicate different caller responsibilities.
-
- If the underlying error is EAGAIN, the caller may attempt to re-negotiate with
- the requesting device. If too many attempts are made to re-negotiate, EBADMSG
- will be returned. At this point, the caller may not attempt to create another
- HSA2 packet; the connection should be terminated and the session torn down.
-
- @result
- An encrypted packet containing the HSA2 join code. NULL in the event of
- failure.
- */
-OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
-OS_NONNULL2 OS_NONNULL3 OS_NONNULL4
-CFDataRef
-SOSFASCopyHSA2Packet(SOSForerunnerAcceptorSessionRef session,
- CFDataRef responsePacket, CFDataRef hsa2Code, CFErrorRef *error);
-
-/*!
- @function SOSFASCopyEncryptedData
-
- @abstract
- Encrypts data for transport over the negotiated session.
-
- @param session
- The session object for which to encrypt the given data.
-
- @param data
- The data to encrypt.
-
- @result
- The encrypted representation of {@param data}.
- */
-OS_EXPORT OS_MALLOC OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NONNULL1
-OS_NONNULL2
-CFDataRef
-SOSFASCopyEncryptedData(SOSForerunnerAcceptorSessionRef session,
- CFDataRef data);
-
-__END_DECLS
-
-#endif /* _SEC_SOSFORERUNNERSESSION_H_ */
projects / apple / security.git / blobdiff