keychain/ckks/CKKS.h

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