This is an HTML version of an attachment to the Freedom of Information request 'Communication with Google/Apple on contact tracing'.


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 

Affected User 

...................................................................................................................................................
Exposed User 

...................................................................................................................................................
CTStateGetRequest 

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 

Overview 
8
..........................................................................................................................................................  
@property CTErrorHandler completionHandler; 
8
..............................................................................................  
@property dispatch_queue_t dispatchQueue; 
8
.................................................................................................  
@property CTManagerState state; 
8
..................................................................................................................  
- (void)perform; 
8
................................................................................................................................................  
- (void)invalidate; 
8
.............................................................................................................................................  
CTExposureDetectionSession 

Overview 
9
..........................................................................................................................................................  
@property dispatch_queue_t dispatchQueue; 
9
.................................................................................................  
Contact Tracing
Framework Documentation

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

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

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

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

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

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

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

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