2 * Copyright (c) 2016 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
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
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.
21 * @APPLE_LICENSE_HEADER_END@
27 #include <dispatch/dispatch.h>
28 #include <ipc/securityd_client.h>
29 #include <utilities/SecCFWrappers.h>
30 #include <utilities/SecDb.h>
34 #import <Foundation/Foundation.h>
35 NS_ASSUME_NONNULL_BEGIN
37 CF_ASSUME_NONNULL_BEGIN
42 typedef NS_ENUM(NSUInteger
, SecCKKSItemEncryptionVersion
) {
43 CKKSItemEncryptionVersionNone
= 0, // No encryption present
44 CKKSItemEncryptionVersion1
= 1, // Current version, AES-SIV 512, not all fields authenticated
45 CKKSItemEncryptionVersion2
= 2, // Seed3 version, AES-SIV 512, all fields (including unknown fields) authenticated
48 extern const SecCKKSItemEncryptionVersion currentCKKSItemEncryptionVersion
;
51 extern NSString
* const SecCKKSActionAdd
;
52 extern NSString
* const SecCKKSActionDelete
;
53 extern NSString
* const SecCKKSActionModify
;
56 @protocol SecCKKSItemState
<NSObject
>
58 typedef NSString
<SecCKKSItemState
> CKKSItemState
;
59 extern CKKSItemState
* const SecCKKSStateNew
;
60 extern CKKSItemState
* const SecCKKSStateUnauthenticated
;
61 extern CKKSItemState
* const SecCKKSStateInFlight
;
62 extern CKKSItemState
* const SecCKKSStateReencrypt
;
63 extern CKKSItemState
* const SecCKKSStateError
;
64 extern CKKSItemState
* const SecCKKSStateZoneMismatch
; // an item has appeared that's in the wrong zone
65 extern CKKSItemState
* const SecCKKSStateDeleted
; // meta-state: please delete this item!
67 /* Processed States */
68 @protocol SecCKKSProcessedState
<NSObject
>
70 typedef NSString
<SecCKKSProcessedState
> CKKSProcessedState
;
71 extern CKKSProcessedState
* const SecCKKSProcessedStateLocal
;
72 extern CKKSProcessedState
* const SecCKKSProcessedStateRemote
;
75 @protocol SecCKKSKeyClass
<NSObject
>
77 typedef NSString
<SecCKKSKeyClass
> CKKSKeyClass
;
78 extern CKKSKeyClass
* const SecCKKSKeyClassTLK
;
79 extern CKKSKeyClass
* const SecCKKSKeyClassA
;
80 extern CKKSKeyClass
* const SecCKKSKeyClassC
;
82 /* Useful CloudKit configuration */
83 extern NSString
* SecCKKSContainerName
;
84 extern bool SecCKKSContainerUsePCS
;
85 extern NSString
* const SecCKKSSubscriptionID
;
86 extern NSString
* const SecCKKSAPSNamedPort
;
89 extern NSString
* const SecCKRecordItemType
;
90 extern NSString
* const SecCKRecordHostOSVersionKey
;
91 extern NSString
* const SecCKRecordEncryptionVersionKey
;
92 extern NSString
* const SecCKRecordParentKeyRefKey
;
93 extern NSString
* const SecCKRecordDataKey
;
94 extern NSString
* const SecCKRecordWrappedKeyKey
;
95 extern NSString
* const SecCKRecordGenerationCountKey
;
96 extern NSString
* const SecCKRecordPCSServiceIdentifier
;
97 extern NSString
* const SecCKRecordPCSPublicKey
;
98 extern NSString
* const SecCKRecordPCSPublicIdentity
;
99 extern NSString
* const SecCKRecordServerWasCurrent
;
101 /* Intermediate Key CKRecord Keys */
102 extern NSString
* const SecCKRecordIntermediateKeyType
;
103 extern NSString
* const SecCKRecordKeyClassKey
;
104 //extern NSString* const SecCKRecordWrappedKeyKey;
105 //extern NSString* const SecCKRecordParentKeyRefKey;
107 /* TLK Share CKRecord Keys */
108 // These are a bit special; they can't use the record ID as information without parsing.
109 extern NSString
* const SecCKRecordTLKShareType
;
110 extern NSString
* const SecCKRecordSenderPeerID
;
111 extern NSString
* const SecCKRecordReceiverPeerID
;
112 extern NSString
* const SecCKRecordReceiverPublicEncryptionKey
;
113 extern NSString
* const SecCKRecordCurve
;
114 extern NSString
* const SecCKRecordEpoch
;
115 extern NSString
* const SecCKRecordPoisoned
;
116 extern NSString
* const SecCKRecordSignature
;
117 extern NSString
* const SecCKRecordVersion
;
118 //extern NSString* const SecCKRecordParentKeyRefKey; // reference to the key contained by this record
119 //extern NSString* const SecCKRecordWrappedKeyKey; // key material
121 /* Current Key CKRecord Keys */
122 extern NSString
* const SecCKRecordCurrentKeyType
;
123 // The key class will be the record name.
124 //extern NSString* const SecCKRecordParentKeyRefKey; <-- represent the current key for this key class
126 /* Current Item CKRecord Keys */
127 extern NSString
* const SecCKRecordCurrentItemType
;
128 extern NSString
* const SecCKRecordItemRefKey
;
131 /* Device State CKRecord Keys */
132 extern NSString
* const SecCKRecordDeviceStateType
;
133 extern NSString
* const SecCKRecordCirclePeerID
;
134 extern NSString
* const SecCKRecordOctagonPeerID
;
135 extern NSString
* const SecCKRecordOctagonStatus
;
136 extern NSString
* const SecCKRecordCircleStatus
;
137 extern NSString
* const SecCKRecordKeyState
;
138 extern NSString
* const SecCKRecordCurrentTLK
;
139 extern NSString
* const SecCKRecordCurrentClassA
;
140 extern NSString
* const SecCKRecordCurrentClassC
;
141 extern NSString
* const SecCKSRecordLastUnlockTime
;
142 extern NSString
* const SecCKSRecordOSVersionKey
; // Similar to SecCKRecordHostOSVersionKey, but better named
144 /* Manifest master CKRecord Keys */
145 extern NSString
* const SecCKRecordManifestType
;
146 extern NSString
* const SecCKRecordManifestDigestValueKey
;
147 extern NSString
* const SecCKRecordManifestGenerationCountKey
;
148 extern NSString
* const SecCKRecordManifestLeafRecordIDsKey
;
149 extern NSString
* const SecCKRecordManifestPeerManifestRecordIDsKey
;
150 extern NSString
* const SecCKRecordManifestCurrentItemsKey
;
151 extern NSString
* const SecCKRecordManifestSignaturesKey
;
152 extern NSString
* const SecCKRecordManifestSignerIDKey
;
153 extern NSString
* const SecCKRecordManifestSchemaKey
;
155 /* Manifest leaf CKRecord Keys */
156 extern NSString
* const SecCKRecordManifestLeafType
;
157 extern NSString
* const SecCKRecordManifestLeafDERKey
;
158 extern NSString
* const SecCKRecordManifestLeafDigestKey
;
160 /* Zone Key Hierarchy States */
161 @protocol SecCKKSZoneKeyState
<NSObject
>
163 typedef NSString
<SecCKKSZoneKeyState
> CKKSZoneKeyState
;
165 // CKKS is currently logged out
166 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateLoggedOut
;
168 // Class has just been created.
169 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateInitializing
;
170 // CKKSZone has just informed us that its setup is done (and completed successfully).
171 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateInitialized
;
172 // CKKSZone has informed us that zone setup did not work. Try again soon!
173 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateZoneCreationFailed
;
174 // Everything is ready and waiting for input.
175 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateReady
;
176 // We're presumably ready, but we'd like to do one or two more checks after we unlock.
177 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateReadyPendingUnlock
;
179 // We're currently refetching the zone
180 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateFetch
;
181 // A Fetch has just been completed which includes some new keys to process
182 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateFetchComplete
;
183 // We'd really like a full refetch.
184 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateNeedFullRefetch
;
185 // We've received a wrapped TLK, but we don't have its contents yet. Wait until they arrive.
186 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateWaitForTLK
;
187 // We've received a wrapped TLK, but we can't process it until the keybag unlocks. Wait until then.
188 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateWaitForUnlock
;
189 // Things are unhealthy, but we're not sure entirely why.
190 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateUnhealthy
;
191 // Something has gone horribly wrong with the current key pointers.
192 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateBadCurrentPointers
;
193 // Something has gone wrong creating new TLKs.
194 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateNewTLKsFailed
;
195 // Something isn't quite right with the TLK shares.
196 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateHealTLKShares
;
197 // Something has gone wrong fixing TLK shares.
198 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateHealTLKSharesFailed
;
199 // The key hierarchy state machine needs to wait for the fixup operation to complete
200 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateWaitForFixupOperation
;
201 // The key hierarchy state machine is responding to a key state reprocess request
202 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateProcess
;
204 // CKKS is resetting the remote zone, due to key hierarchy reasons. Will not proceed until the local reset occurs.
205 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateResettingZone
;
206 // CKKS is resetting the local data, likely to do a cloudkit reset or a rpc.
207 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateResettingLocalData
;
209 // Fatal error. Will not proceed unless fixed from outside class.
210 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateError
;
211 // This CKKS instance has been cancelled.
212 extern CKKSZoneKeyState
* const SecCKKSZoneKeyStateCancelled
;
214 // If you absolutely need to numberify one of the above constants, here's your maps.
215 NSDictionary
<CKKSZoneKeyState
*, NSNumber
*>* CKKSZoneKeyStateMap(void);
216 NSDictionary
<NSNumber
*, CKKSZoneKeyState
*>* CKKSZoneKeyStateInverseMap(void);
217 NSNumber
* CKKSZoneKeyToNumber(CKKSZoneKeyState
* state
);
218 CKKSZoneKeyState
* CKKSZoneKeyRecover(NSNumber
* stateNumber
);
220 // Use this to determine if CKKS believes the current state is "transient": that is, should resolve itself with further local processing
221 // or 'nontransient': further local processing won't progress. Either we're ready, or waiting for the user to unlock, or a remote device to do something.
222 bool CKKSKeyStateTransient(CKKSZoneKeyState
* state
);
224 /* Hide Item Length */
225 extern const NSUInteger SecCKKSItemPaddingBlockSize
;
228 extern NSString
* const SecCKKSAggdPropagationDelay
;
229 extern NSString
* const SecCKKSAggdPrimaryKeyConflict
;
230 extern NSString
* const SecCKKSAggdViewKeyCount
;
231 extern NSString
* const SecCKKSAggdItemReencryption
;
233 extern NSString
* const SecCKKSUserDefaultsSuite
;
235 extern NSString
* const CKKSErrorDomain
;
236 extern NSString
* const CKKSServerExtensionErrorDomain
;
238 /* Queue limits: these should likely be configurable via plist */
239 #define SecCKKSOutgoingQueueItemsAtOnce 100
240 #define SecCKKSIncomingQueueItemsAtOnce 50
243 NSString
* SecCKKSHostOSVersion(void);
247 /* C functions to interact with CKKS */
248 void SecCKKSInitialize(SecDbRef db
);
249 void SecCKKSNotifyBlock(SecDbConnectionRef dbconn
, SecDbTransactionPhase phase
, SecDbTransactionSource source
, CFArrayRef changes
);
251 // Called by XPC approximately every 3 days
252 void SecCKKS24hrNotification(void);
254 // Register this callback to receive a call when the item with this UUID next successfully (or unsuccessfully) exits the outgoing queue.
255 void CKKSRegisterSyncStatusCallback(CFStringRef cfuuid
, SecBoolCFErrorCallback callback
);
257 // Tells CKKS that the local keychain was reset, and that it should respond accordingly
258 void SecCKKSPerformLocalResync(void);
260 // Returns true if CloudKit keychain syncing should occur
261 bool SecCKKSIsEnabled(void);
263 bool SecCKKSEnable(void);
264 bool SecCKKSDisable(void);
266 bool SecCKKSResetSyncing(void);
268 bool SecCKKSSyncManifests(void);
269 bool SecCKKSEnableSyncManifests(void);
270 bool SecCKKSSetSyncManifests(bool value
);
272 bool SecCKKSEnforceManifests(void);
273 bool SecCKKSEnableEnforceManifests(void);
274 bool SecCKKSSetEnforceManifests(bool value
);
276 bool SecCKKSReduceRateLimiting(void);
277 bool SecCKKSSetReduceRateLimiting(bool value
);
280 bool SecCKKSTestsEnabled(void);
281 bool SecCKKSTestsEnable(void);
282 bool SecCKKSTestsDisable(void);
284 void SecCKKSTestResetFlags(void);
285 bool SecCKKSTestDisableAutomaticUUID(void);
286 void SecCKKSTestSetDisableAutomaticUUID(bool set
);
288 bool SecCKKSTestDisableSOS(void);
289 void SecCKKSTestSetDisableSOS(bool set
);
291 bool SecCKKSTestDisableKeyNotifications(void);
292 void SecCKKSTestSetDisableKeyNotifications(bool set
);
294 // TODO: handle errors better
295 typedef CF_ENUM(CFIndex
, CKKSErrorCode
) {
296 CKKSNotInitialized
= 9,
297 CKKSNotLoggedIn
= 10,
300 CKKSRemoteItemChangePending
= 12,
301 CKKSLocalItemChangePending
= 13,
302 CKKSItemChanged
= 14,
303 CKKSNoUUIDOnItem
= 15,
304 CKKSItemCreationFailure
= 16,
305 CKKSInvalidKeyClass
= 17,
306 CKKSKeyNotSelfWrapped
= 18,
307 CKKSNoTrustedPeer
= 19,
308 CKKSDataMismatch
= 20,
309 CKKSProtobufFailure
= 21,
310 CKKSNoSuchRecord
= 22,
311 CKKSMissingTLKShare
= 23,
312 CKKSNoPeersAvailable
= 24,
314 CKKSSplitKeyHierarchy
= 32,
315 CKKSOrphanedKey
= 33,
317 CKKSNoTrustedTLKShares
= 35,
318 CKKSKeyUnknownFormat
= 36,
319 CKKSNoSigningKey
= 37,
320 CKKSNoEncryptionKey
= 38,
323 CKKSiCloudGreyMode
= 41,
325 CKKSNoFetchesRequested
= 50,
328 typedef CF_ENUM(CFIndex
, CKKSResultDescriptionErrorCode
) {
329 CKKSResultDescriptionNone
= 0,
330 CKKSResultDescriptionPendingKeyReady
= 1,
331 CKKSResultDescriptionPendingSuccessfulFetch
= 2,
332 CKKSResultDescriptionPendingAccountLoggedIn
= 3,
333 CKKSResultDescriptionPendingUnlock
= 4,
334 CKKSResultDescriptionPendingBottledPeerModifyRecords
= 5,
335 CKKSResultDescriptionPendingBottledPeerFetchRecords
= 6,
337 CKKSResultDescriptionPendingZoneChangeFetchScheduling
= 1000,
338 CKKSResultDescriptionPendingViewChangedScheduling
= 1001,
339 CKKSResultDescriptionPendingZoneInitializeScheduling
= 1002,
340 CKKSResultDescriptionPendingOutgoingQueueScheduling
= 1003,
341 CKKSResultDescriptionPendingKeyHierachyPokeScheduling
= 1004,
344 // These errors are returned by the CKKS server extension.
345 // Commented out codes here indicate that we don't currently handle them on the client side.
346 typedef CF_ENUM(CFIndex
, CKKSServerExtensionErrorCode
) {
348 //CKKSServerMissingField = 1,
349 //CKKSServerMissingRecord = 2,
350 //CKKSServerUnexpectedFieldType = 3,
351 //CKKSServerUnexpectedRecordType = 4,
352 //CKKSServerUnepxectedRecordID = 5,
355 //CKKSServerMissingCurrentKeyPointer = 6,
356 //CKKSServerMissingCurrentKey = 7,
357 //CKKSServerUnexpectedSyncKeyClassInChain = 8,
358 CKKSServerUnexpectedSyncKeyInChain
= 9,
360 // Item/Currentitem record errors:
361 //CKKSServerKeyrollingNotAllowed = 10,
362 //CKKSServerInvalidPublicIdentity = 11,
363 //CKKSServerPublicKeyMismatch = 12,
364 //CKKSServerServiceNumberMismatch = 13,
365 //CKKSServerUnknownServiceNumber = 14,
366 //CKKSServerEncverLessThanMinVal = 15,
367 //CKKSServerCannotModifyWasCurrent = 16,
368 //CKKSServerInvalidCurrentItem = 17,
371 #define SecTranslateError(nserrorptr, cferror) \
373 *nserrorptr = (__bridge_transfer NSError*)cferror; \
375 CFReleaseNull(cferror); \
378 // Very similar to the secerror, secnotice, and secinfo macros in debugging.h, but add zoneNames
379 #define ckkserrorwithzonename(scope, zoneName, format, ...) \
381 os_log(secLogObjForScope("SecError"), scope "-%@: " format, (zoneName ? zoneName : @"unknown"), ##__VA_ARGS__); \
383 #define ckksnoticewithzonename(scope, zoneName, format, ...) \
385 os_log(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString:(zoneName ? zoneName : @"unknown")]), \
389 #define ckksinfowithzonename(scope, zoneName, format, ...) \
391 os_log_debug(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString:(zoneName ? zoneName : @"unknown")]), \
396 #define ckkserror(scope, zoneNameHaver, format, ...) \
398 NSString* znh = zoneNameHaver.zoneName; \
399 ckkserrorwithzonename(scope, znh, format, ##__VA_ARGS__) \
401 #define ckksnotice(scope, zoneNameHaver, format, ...) \
403 NSString* znh = zoneNameHaver.zoneName; \
404 ckksnoticewithzonename(scope, znh, format, ##__VA_ARGS__) \
406 #define ckksinfo(scope, zoneNameHaver, format, ...) \
408 NSString* znh = zoneNameHaver.zoneName; \
409 ckksinfowithzonename(scope, znh, format, ##__VA_ARGS__) \
414 #define ckksdebugwithzonename(scope, zoneName, format, ...) \
416 os_log_debug(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString:(zoneName ? zoneName : @"unknown")]), \
420 #define ckksdebug(scope, zoneNameHaver, format, ...) \
422 NSString* znh = zoneNameHaver.zoneName; \
423 ckksdebugwithzonename(scope, znh, format, ##__VA_ARGS__) \
426 #define ckksdebug(scope, ...) /* nothing */
430 NS_ASSUME_NONNULL_END
432 CF_ASSUME_NONNULL_END