Contact Tracing
Framework Documentation
(API)
Preliminary - Subject to Modification and Extension
April 2020
Information subject to copyright. All rights reserved.
link to page 5 link to page 5 link to page 5 link to page 7 link to page 7 link to page 7 link to page 7 link to page 7 link to page 7 link to page 7 link to page 7 link to page 8 link to page 8 link to page 8 link to page 8 link to page 8 link to page 8 link to page 8 link to page 9 link to page 9 link to page 9
Contents
Overview
5
Affected User
5
...................................................................................................................................................
Exposed User
5
...................................................................................................................................................
CTStateGetRequest
7
Overview
7
..........................................................................................................................................................
typedef void ( ^CTErrorHandler )( NSError * _Nul able inError );
7
......................................................................
@property CTErrorHandler completionHandler;
7
..............................................................................................
@property dispatch_queue_t dispatchQueue;
7
.................................................................................................
@property CTManagerState state;
7
..................................................................................................................
- (void)perform;
7
................................................................................................................................................
- (void)invalidate;
7
.............................................................................................................................................
CTStateSetRequest
8
Overview
8
..........................................................................................................................................................
@property CTErrorHandler completionHandler;
8
..............................................................................................
@property dispatch_queue_t dispatchQueue;
8
.................................................................................................
@property CTManagerState state;
8
..................................................................................................................
- (void)perform;
8
................................................................................................................................................
- (void)invalidate;
8
.............................................................................................................................................
CTExposureDetectionSession
9
Overview
9
..........................................................................................................................................................
@property dispatch_queue_t dispatchQueue;
9
.................................................................................................
Contact Tracing
Framework Documentation
2
Information subject to copyright. All rights reserved.
link to page 9 link to page 9 link to page 9 link to page 9 link to page 9 link to page 9 link to page 10 link to page 10 link to page 11 link to page 11 link to page 11 link to page 12 link to page 12 link to page 12 link to page 12 link to page 12 link to page 12 link to page 12 link to page 12 link to page 13 link to page 13 link to page 13 link to page 14 link to page 14 link to page 14 link to page 14
@property NSInteger maxKeyCount;
9
...............................................................................................................
- (void) activateWithCompletion:(CTErrorHandler) inCompletion;
9
..................................................................
- (void)invalidate;
9
.............................................................................................................................................
- (void) addPositiveDiagnosisKeys:(NSArray <CTDailyTracingKey *> *) inKeys completion:(CTErrorHandler)
inCompletion;
9
...................................................................................................................................................
typedef void ( ^CTExposureDetectionFinishHandler )( CTExposureDetectionSummary * _Nul able
inSummary, NSError * _Nul able inError );
9
........................................................................................................
- (void) finishedPositiveDiagnosisKeysWithCompletion:(CTExposureDetectionFinishHandler)
inFinishHandler;
9
...............................................................................................................................................
typedef void ( ^CTExposureDetectionContactHandler )( NSArray <CTContactInfo *> * _Nul able inContacts,
NSError * _Nul able inError );
1
.......................................................................................................................... 0
- (void)getContactInfoWithHandler:(CTExposureDetectionContactHandler) inHandler;
1
.............................. 0
CTExposureDetectionSummary
11
Overview
1
......................................................................................................................................................... 1
@property NSInteger matchedKeyCount;
1
...................................................................................................... 1
CTSelfTracingInfoRequest
12
Overview
1
......................................................................................................................................................... 2
Discussion
1
...................................................................................................................................................... 2
typedef void ( ^CTSelfTracingInfoGetCompletion )( CTSelfTracingInfo * _Nul able inInfo, NSError * _Nul able
inError );
1
.......................................................................................................................................................... 2
@property CTSelfTracingInfoGetCompletion completionHandler;
1
................................................................ 2
@property dispatch_queue_t dispatchQueue;
1
............................................................................................... 2
- (void)perform;
1
.............................................................................................................................................. 2
- (void)invalidate;
1
............................................................................................................................................ 2
CTSelfTracingInfo
13
Overview
1
......................................................................................................................................................... 3
@property NSArray <CTDailyTracingKey *> * dailyTracingKeys;
1
.................................................................. 3
CTContactInfo
14
Overview
1
........................................................................................................................................................ 4
@property NSTimeInterval duration;
1
.............................................................................................................. 4
@property CFAbsoluteTime timestamp;
1
......................................................................................................... 4
Contact Tracing
Framework Documentation
3
Information subject to copyright. All rights reserved.
link to page 15 link to page 15 link to page 15
CTDailyTracingKey
15
Overview
1
......................................................................................................................................................... 5
@property NSData *keyData;
1
......................................................................................................................... 5
Contact Tracing
Framework Documentation
4
Information subject to copyright. All rights reserved.
Overview
The ContactTracing Framework is designed to help developers implement a privacy-
preserving contact tracing solution. It covers two user roles:
1.
Affected User. A user who reports themself as positively diagnosed as having the
virus.
2.
Exposed User. A user who has notified themself as potential y exposed to an
Affected User.
Affected User
When a user is positively affected, their Daily Tracing Keys should be shared with other
uses to alert them to potential exposure. These Daily Tracing Keys are retrieved using
CTSelfTracingInfoRequest.
Exposed User
Given a set of positively affected Daily Tracing Keys, the framework al ows you to
determine whether those Daily Tracing Keys were observed local y by the user,
indicating potential exposure. If so, additional information such as date and duration
may also be retrieved. Possible observations can be retrieved using
CTExposureDetectionFinishHandler, and additional information using
CTExposureDetectionContactHandler.
The following il ustration outlines the flow of the ContactTracing Framework for iOS.
Contact Tracing
Framework Documentation
5
Information subject to copyright. All rights reserved.
App_Local
CT Framework/Bluetooth Local
Crypto_Local
Crypto_Remote
CT Framework/Bluetooth Remote
App_Remote
Cloud
Advertising
[1] CTStateSetRequest(True)
Generates Tracing_Key if it doesn't exist
Saves to Disk
Derive Daily_Key from Tracing_Key
[2] Derive Rolling Proximity Identifier(Daily_Key, ..)
[3] Rolling Proximity Identifer
[4] Advertisement (Contact Detection Service UUID, Rolling Proximity Identifer)
Save Rolling Proximity Identifer
~15 mins elaspes
[5] Derive Rolling Proximity Identifier(Daily_Key, ..)
[6] new Rolling Proximity Identifer
[7] Advertisement (Contact Detection Service UUID, new Rolling Proximity Identifer)
Save Rolling Proximity Identifer
~24 hour elaspes
Derive Daily_Key from Tracing_Key
[8] Derive Rolling Proximity Identifier(Daily_Key, ..)
[9] new Rolling Proximity Identifer
[10] Advertisement (Contact Detection Service UUID, new Rolling Proximity Identifer)
Save Rolling Proximity Identifer
Scanning
[11] CTStateSetRequest (True)
Scan for Contact Detection Service UUID
[12] Advertisement (Contact Detection Service UUID, Rolling Proximity Identifer)
Save Rolling Proximity Identifer
[13] Advertisement (Contact Detection Service UUID, Rolling Proximity Identifer)
Save Rolling Proximity Identifer
Periodic Diagnosis_Key Fetch
[14] Diagnosis_Keys
[15] CTExposureDetectionSession (List of Diagnosis_Keys)
Resolve Diagnosis_Keys against all Rolling Proximity Identifers
[16] resolve (RPI, Diagnosis_Key)
[17] Match/No-Match
Algorithm to assess risk based on exposure duration, ..
[18] CTExposureDetectionSummary (# of matches)
[19] CTExposureDetectionSession (get contacts info)
CFUserNotification "App would like to access time and duration of your %d contacts. Approve?"
[20] CTExposureDetectionontactInfoCompletion (timestamp, duration)
Proximity to diagnosed confirmed
Diagnosis
Positive Diagnosis: Retrieve Keys
[21] CTSelfTracingInfoGetRequest (past 14 days)
CFUserNotification, ask user for permission
[22] CTSelfTracingInfoCompletion
App_Local
CT Framework/Bluetooth Local
Crypto_Local
Crypto_Remote
CT Framework/Bluetooth Remote
App_Remote
Cloud
Figure 1. The Contact Tracing Flow
Contact Tracing
Framework Documentation
6
Information subject to copyright. All rights reserved.
CTStateGetRequest
Overview
Requests whether contact tracing is on or off on the device.
typedef void ( ^CTErrorHandler )( NSError * _Nullable inError );
The type definition for the completion handler.
@property CTErrorHandler completionHandler;
This property holds the completion handler that framework invokes when the request completes. The
property is cleared upon completion to break any potential retain cycles.
@property dispatch_queue_t dispatchQueue;
This property holds the the dispatch queue used to invoke handlers on. If this property isn’t set, the
framework uses the main queue.
@property CTManagerState state;
This property contains the snapshot of the state when the request was performed. It’s valid only after the
framework invokes the completion handler.
- (void)perform;
Asynchronously performs the request to get the state, and invokes the completion handler when it's done.
- (void)invalidate;
Invalidates a previously initiated request. If there is an outstanding completion handler, the framework wil
invoke it with an error.
Don’t reuse the request after this is cal ed. If you require another request, create a new one.
Contact Tracing
Framework Documentation
7
Information subject to copyright. All rights reserved.
CTStateSetRequest
Overview
Changes the state of contact tracing on the device.
@property CTErrorHandler completionHandler;
This property holds the completion handler that framework invokes when the request completes. The
property is cleared upon completion to break any potential retain cycles.
@property dispatch_queue_t dispatchQueue;
This property holds the the dispatch queue used to invoke handlers on. If this property isn’t set, the
framework uses the main queue.
@property CTManagerState state;
This property contains the state to set Contact Tracing to. Cal the perform method to apply the state
once set.
- (void)perform;
Asynchronously performs the request to get the state, and invokes the completion handler when it's done.
- (void)invalidate;
Invalidates a previously initiated request. If there is an outstanding completion handler, the framework wil
invoke it with an error.
Don’t reuse the request after this is cal ed. If you require another request, create a new one.
Contact Tracing
Framework Documentation
8
Information subject to copyright. All rights reserved.
CTExposureDetectionSession
Overview
Performs exposure detection bad on previously collected proximity data and keys.
@property dispatch_queue_t dispatchQueue;
This property holds the the dispatch queue used to invoke handlers on. If this property isn’t set, the
framework uses the main queue.
@property NSInteger maxKeyCount;
This property contains the maximum number of keys to provide to this API at once. This property’s value
updates after each operation complete and before the completion handler is invoked. Use this property to
throttle key downloads to avoid excessive buffering of keys in memory.
- (void) activateWithCompletion:(CTErrorHandler) inCompletion;
Activates the session and requests authorization for the app with the user. Properties and methods cannot
be used until this completes successful y.
- (void)invalidate;
Invalidates the session. Any outstanding completion handlers wil be invoked with an error. The session
cannot be used after this is cal ed. A new session must be created if another detection is needed.
- (void) addPositiveDiagnosisKeys:(NSArray <CTDailyTracingKey
*> *) inKeys completion:(CTErrorHandler) inCompletion;
Asynchronously adds the specified keys to the session to al ow them to be checked for exposure. Each cal
to this method must include more keys than specified by the current value of <maxKeyCount>.
typedef void ( ^CTExposureDetectionFinishHandler )
( CTExposureDetectionSummary * _Nullable inSummary, NSError *
_Nullable inError );
The type definition for the completion handler.
- (void) finishedPositiveDiagnosisKeysWithCompletion:
(CTExposureDetectionFinishHandler) inFinishHandler;
Indicates al of the available keys have been provided. Any remaining detection wil be performed and the
completion handler wil be invoked with the results.
Contact Tracing
Framework Documentation
9
Information subject to copyright. All rights reserved.
typedef void ( ^CTExposureDetectionContactHandler )( NSArray
<CTContactInfo *> * _Nullable inContacts, NSError * _Nullable
inError );
The type definition for the completion handler.
- (void)getContactInfoWithHandler:
(CTExposureDetectionContactHandler) inHandler;
Obtains information on each incident. This can only be cal ed once the detector finishes. The handler may
be invoked multiple times. An empty array indicates the final invocation of the hander.
Contact Tracing
Framework Documentation
10
Information subject to copyright. All rights reserved.
CTExposureDetectionSummary
Overview
Provides a summary on exposures.
@property NSInteger matchedKeyCount;
This property holds the number of keys that matched for an exposure detection.
Contact Tracing
Framework Documentation
11
Information subject to copyright. All rights reserved.
CTSelfTracingInfoRequest
Overview
Requests the daily tracing keys used by this device to share with a server.
Discussion
This request is intended to be cal ed when a user has a positive diagnosis. Once the keys are shared with a
server, other users can use the keys to check if their device has been in contact with any positive diagnosis
users. Each request wil require the user to authorize access.
Keys wil be reported for the previous 14 days of contact tracing. The app wil also be launched every day
after the daily tracing key changes to al ow it to request again to get the key for each previous day for the
next 14 days.
typedef void ( ^CTSelfTracingInfoGetCompletion )
( CTSelfTracingInfo * _Nullable inInfo, NSError * _Nullable inError );
The type definition for the completion handler.
@property CTSelfTracingInfoGetCompletion completionHandler;
This property invokes this completion handler when the request completes and clears the property to break
any potential retain cycles.
@property dispatch_queue_t dispatchQueue;
This property holds the the dispatch queue used to invoke handlers on. If this property isn’t set, the
framework uses the main queue.
- (void)perform;
Asynchronously performs the request to get the state, and invokes the completion handler when it's done.
- (void)invalidate;
Invalidates a previously initiated request. If there is an outstanding completion handler, the framework wil
invoke it with an error.
Don’t reuse the request after this is cal ed. If you require another request, create a new one.
Contact Tracing
Framework Documentation
12
Information subject to copyright. All rights reserved.
CTSelfTracingInfo
Overview
Contains the Daily Tracing Keys.
@property NSArray <CTDailyTracingKey *> *
dailyTracingKeys;
Daily tracing keys available at the time of the request.
Contact Tracing
Framework Documentation
13
Information subject to copyright. All rights reserved.
CTContactInfo
Overview
Contains information about a single contact incident.
@property NSTimeInterval duration;
How long the contact was in proximity. Minimum duration is 5 minutes and increments by 5 minutes: 5, 10,
15, etc.
@property CFAbsoluteTime timestamp;
This property contains the time when the contact occurred. This may have reduced precision, such as
within one day of the actual time.
Contact Tracing
Framework Documentation
14
Information subject to copyright. All rights reserved.
CTDailyTracingKey
Overview
The Daily Tracing Key object.
@property NSData *keyData;
This property contains the Daily Tracing Key information.
Contact Tracing
Framework Documentation
15
Information subject to copyright. All rights reserved.
Document Outline