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 <ipc/securityd_client.h>
  28 #include <utilities/SecDb.h>
  29 #include <utilities/SecCFWrappers.h>
  30 #include <dispatch/dispatch.h>
  31 #include <xpc/xpc.h>
  32
  33 #ifdef __OBJC__
  34 #import <Foundation/Foundation.h>
  35
  36 typedef NS_ENUM(NSUInteger, SecCKKSItemEncryptionVersion) {
  37     CKKSItemEncryptionVersionNone = 0,  // No encryption present
  38     CKKSItemEncryptionVersion1 = 1,     // Current version, AES-SIV 512, not all fields authenticated
  39     CKKSItemEncryptionVersion2 = 2,     // Seed3 version, AES-SIV 512, all fields (including unknown fields) authenticated
  40 };
  41
  42 extern const SecCKKSItemEncryptionVersion currentCKKSItemEncryptionVersion;
  43
  44 /* Queue Actions */
  45 extern NSString* const SecCKKSActionAdd;
  46 extern NSString* const SecCKKSActionDelete;
  47 extern NSString* const SecCKKSActionModify;
  48
  49 /* Queue States */
  50 @protocol SecCKKSItemState
  51 @end
  52 typedef NSString<SecCKKSItemState> CKKSItemState;
  53 extern CKKSItemState* const SecCKKSStateNew;
  54 extern CKKSItemState* const SecCKKSStateUnauthenticated;
  55 extern CKKSItemState* const SecCKKSStateInFlight;
  56 extern CKKSItemState* const SecCKKSStateReencrypt;
  57 extern CKKSItemState* const SecCKKSStateError;
  58 extern CKKSItemState* const SecCKKSStateDeleted; // meta-state: please delete this item!
  59
  60 /* Processed States */
  61 @protocol SecCKKSProcessedState
  62 @end
  63 typedef NSString<SecCKKSProcessedState> CKKSProcessedState;
  64 extern CKKSProcessedState* const SecCKKSProcessedStateLocal;
  65 extern CKKSProcessedState* const SecCKKSProcessedStateRemote;
  66
  67 /* Key Classes */
  68 @protocol SecCKKSKeyClass
  69 @end
  70 typedef NSString<SecCKKSKeyClass> CKKSKeyClass;
  71 extern CKKSKeyClass* const SecCKKSKeyClassTLK;
  72 extern CKKSKeyClass* const SecCKKSKeyClassA;
  73 extern CKKSKeyClass* const SecCKKSKeyClassC;
  74
  75 /* Useful CloudKit configuration */
  76 extern NSString* const SecCKKSContainerName;
  77 extern bool SecCKKSContainerUsePCS;
  78 extern NSString* const SecCKKSSubscriptionID;
  79 extern NSString* const SecCKKSAPSNamedPort;
  80
  81 /* Item CKRecords */
  82 extern NSString* const SecCKRecordItemType;
  83 extern NSString* const SecCKRecordHostOSVersionKey;
  84 extern NSString* const SecCKRecordEncryptionVersionKey;
  85 extern NSString* const SecCKRecordParentKeyRefKey;
  86 extern NSString* const SecCKRecordDataKey;
  87 extern NSString* const SecCKRecordWrappedKeyKey;
  88 extern NSString* const SecCKRecordGenerationCountKey;
  89 extern NSString* const SecCKRecordPCSServiceIdentifier;
  90 extern NSString* const SecCKRecordPCSPublicKey;
  91 extern NSString* const SecCKRecordPCSPublicIdentity;
  92 extern NSString* const SecCKRecordServerWasCurrent;
  93
  94 /* Intermediate Key CKRecord Keys */
  95 extern NSString* const SecCKRecordIntermediateKeyType;
  96 extern NSString* const SecCKRecordKeyClassKey;
  97 //extern NSString* const SecCKRecordWrappedKeyKey;
  98 //extern NSString* const SecCKRecordParentKeyRefKey;
  99
 100 /* TLK Share CKRecord Keys */
 101 // These are a bit special; they can't use the record ID as information without parsing.
 102 extern NSString* const SecCKRecordTLKShareType;
 103 extern NSString* const SecCKRecordSenderPeerID;
 104 extern NSString* const SecCKRecordReceiverPeerID;
 105 extern NSString* const SecCKRecordReceiverPublicEncryptionKey;
 106 extern NSString* const SecCKRecordCurve;
 107 extern NSString* const SecCKRecordEpoch;
 108 extern NSString* const SecCKRecordPoisoned;
 109 extern NSString* const SecCKRecordSignature;
 110 extern NSString* const SecCKRecordVersion;
 111 //extern NSString* const SecCKRecordParentKeyRefKey; // reference to the key contained by this record
 112 //extern NSString* const SecCKRecordWrappedKeyKey;   // key material
 113
 114 /* Current Key CKRecord Keys */
 115 extern NSString* const SecCKRecordCurrentKeyType;
 116 // The key class will be the record name.
 117 //extern NSString* const SecCKRecordParentKeyRefKey; <-- represent the current key for this key class
 118
 119 /* Current Item CKRecord Keys */
 120 extern NSString* const SecCKRecordCurrentItemType;
 121 extern NSString* const SecCKRecordItemRefKey;
 122 //extern NSString* const SecCKRecordHostOSVersionKey; <-- the OS version which last updated the record
 123
 124 /* Device State CKRexord Keys */
 125 extern NSString* const SecCKRecordDeviceStateType;
 126 extern NSString* const SecCKRecordCirclePeerID;
 127 extern NSString* const SecCKRecordCircleStatus;
 128 extern NSString* const SecCKRecordKeyState;
 129 extern NSString* const SecCKRecordCurrentTLK;
 130 extern NSString* const SecCKRecordCurrentClassA;
 131 extern NSString* const SecCKRecordCurrentClassC;
 132
 133 /* Manifest master CKRecord Keys */
 134 extern NSString* const SecCKRecordManifestType;
 135 extern NSString* const SecCKRecordManifestDigestValueKey;
 136 extern NSString* const SecCKRecordManifestGenerationCountKey;
 137 extern NSString* const SecCKRecordManifestLeafRecordIDsKey;
 138 extern NSString* const SecCKRecordManifestPeerManifestRecordIDsKey;
 139 extern NSString* const SecCKRecordManifestCurrentItemsKey;
 140 extern NSString* const SecCKRecordManifestSignaturesKey;
 141 extern NSString* const SecCKRecordManifestSignerIDKey;
 142 extern NSString* const SecCKRecordManifestSchemaKey;
 143
 144 /* Manifest leaf CKRecord Keys */
 145 extern NSString* const SecCKRecordManifestLeafType;
 146 extern NSString* const SecCKRecordManifestLeafDERKey;
 147 extern NSString* const SecCKRecordManifestLeafDigestKey;
 148
 149 /* Zone Key Hierarchy States */
 150 @protocol SecCKKSZoneKeyState
 151 @end
 152 typedef NSString<SecCKKSZoneKeyState> CKKSZoneKeyState;
 153
 154 // Class has just been created.
 155 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateInitializing;
 156 // CKKSZone has just informed us that its setup is done (and completed successfully).
 157 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateInitialized;
 158 // Everything is ready and waiting for input.
 159 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateReady;
 160 // A Fetch has just been completed which includes some new keys to process
 161 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateFetchComplete;
 162 // We'd really like a full refetch.
 163 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateNeedFullRefetch;
 164 // We've received a wrapped TLK, but we don't have its contents yet. Wait until they arrive.
 165 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateWaitForTLK;
 166 // We've received a wrapped TLK, but we can't process it until the keybag unlocks. Wait until then.
 167 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateWaitForUnlock;
 168 // Things are unhealthy, but we're not sure entirely why.
 169 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateUnhealthy;
 170 // Something has gone horribly wrong with the current key pointers.
 171 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateBadCurrentPointers;
 172 // Something has gone wrong creating new TLKs.
 173 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateNewTLKsFailed;
 174 // Something isn't quite right with the TLK shares.
 175 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateHealTLKShares;
 176 // Something has gone wrong fixing TLK shares.
 177 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateHealTLKSharesFailed;
 178 // The key hierarchy state machine needs to wait for the fixup operation to complete
 179 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateWaitForFixupOperation;
 180
 181 // Fatal error. Will not proceed unless fixed from outside class.
 182 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateError;
 183 // This CKKS instance has been cancelled.
 184 extern CKKSZoneKeyState* const SecCKKSZoneKeyStateCancelled;
 185
 186 // If you absolutely need to numberify one of the above constants, here's your maps.
 187 NSDictionary<CKKSZoneKeyState*, NSNumber*>* CKKSZoneKeyStateMap(void);
 188 NSDictionary<NSNumber*, CKKSZoneKeyState*>* CKKSZoneKeyStateInverseMap(void);
 189 NSNumber* CKKSZoneKeyToNumber(CKKSZoneKeyState* state);
 190 CKKSZoneKeyState* CKKSZoneKeyRecover(NSNumber* stateNumber);
 191
 192 /* Hide Item Length */
 193 extern const NSUInteger SecCKKSItemPaddingBlockSize;
 194
 195 /* Aggd Keys */
 196 extern NSString* const SecCKKSAggdPropagationDelay;
 197 extern NSString* const SecCKKSAggdPrimaryKeyConflict;
 198 extern NSString* const SecCKKSAggdViewKeyCount;
 199 extern NSString* const SecCKKSAggdItemReencryption;
 200
 201 extern NSString* const SecCKKSUserDefaultsSuite;
 202
 203 extern NSString* const CKKSErrorDomain;
 204 extern NSString* const CKKSServerExtensionErrorDomain;
 205
 206 /* Queue limits: these should likely be configurable via plist */
 207 #define SecCKKSOutgoingQueueItemsAtOnce 100
 208 #define SecCKKSIncomingQueueItemsAtOnce 10
 209
 210 #endif // OBJ-C
 211
 212 /* C functions to interact with CKKS */
 213 void SecCKKSInitialize(SecDbRef db);
 214 void SecCKKSNotifyBlock(SecDbConnectionRef dbconn, SecDbTransactionPhase phase, SecDbTransactionSource source, CFArrayRef changes);
 215
 216 // Called by XPC approximately every 3 days
 217 void SecCKKS24hrNotification(void);
 218
 219 // Register this callback to receive a call when the item with this UUID next successfully (or unsuccessfully) exits the outgoing queue.
 220 void CKKSRegisterSyncStatusCallback(CFStringRef cfuuid, SecBoolCFErrorCallback callback);
 221
 222 // Returns true if CloudKit keychain syncing should occur
 223 bool SecCKKSIsEnabled(void);
 224
 225 bool SecCKKSEnable(void);
 226 bool SecCKKSDisable(void);
 227
 228 bool SecCKKSResetSyncing(void);
 229
 230 bool SecCKKSSyncManifests(void);
 231 bool SecCKKSEnableSyncManifests(void);
 232 bool SecCKKSSetSyncManifests(bool value);
 233
 234 bool SecCKKSEnforceManifests(void);
 235 bool SecCKKSEnableEnforceManifests(void);
 236 bool SecCKKSSetEnforceManifests(bool value);
 237
 238 bool SecCKKSShareTLKs(void);
 239 bool SecCKKSEnableShareTLKs(void);
 240 bool SecCKKSSetShareTLKs(bool value);
 241
 242 // Testing support
 243 bool SecCKKSTestsEnabled(void);
 244 bool SecCKKSTestsEnable(void);
 245 bool SecCKKSTestsDisable(void);
 246
 247 void SecCKKSTestResetFlags(void);
 248 bool SecCKKSTestDisableAutomaticUUID(void);
 249 void SecCKKSTestSetDisableAutomaticUUID(bool set);
 250
 251 bool SecCKKSTestDisableSOS(void);
 252 void SecCKKSTestSetDisableSOS(bool set);
 253
 254 bool SecCKKSTestDisableKeyNotifications(void);
 255 void SecCKKSTestSetDisableKeyNotifications(bool set);
 256
 257
 258 XPC_RETURNS_RETAINED xpc_endpoint_t
 259 SecServerCreateCKKSEndpoint(void);
 260
 261 // TODO: handle errors better
 262 typedef CF_ENUM(CFIndex, CKKSErrorCode) {
 263     CKKSNotLoggedIn = 10,
 264     CKKSNoSuchView = 11,
 265
 266     CKKSRemoteItemChangePending = 12,
 267     CKKSLocalItemChangePending = 13,
 268     CKKSItemChanged = 14,
 269     CKKSNoUUIDOnItem = 15,
 270     CKKSItemCreationFailure = 16,
 271     CKKSInvalidKeyClass = 17,
 272     CKKSKeyNotSelfWrapped = 18,
 273     CKKSNoTrustedPeer = 19,
 274     CKKSDataMismatch = 20,
 275     CKKSProtobufFailure = 21,
 276     CKKSNoSuchRecord = 22,
 277     CKKSMissingTLKShare = 23,
 278     CKKSNoPeersAvailable = 24,
 279 };
 280
 281 // These errors are returned by the CKKS server extension.
 282 // Commented out codes here indicate that we don't currently handle them on the client side.
 283 typedef CF_ENUM(CFIndex, CKKSServerExtensionErrorCode) {
 284     // Generic Errors
 285     //CKKSServerMissingField = 1,
 286     //CKKSServerMissingRecord = 2,
 287     //CKKSServerUnexpectedFieldType = 3,
 288     //CKKSServerUnexpectedRecordType = 4,
 289     //CKKSServerUnepxectedRecordID = 5,
 290
 291     // Chain errors:
 292     //CKKSServerMissingCurrentKeyPointer = 6,
 293     //CKKSServerMissingCurrentKey = 7,
 294     //CKKSServerUnexpectedSyncKeyClassInChain = 8,
 295     CKKSServerUnexpectedSyncKeyInChain = 9,
 296
 297     // Item/Currentitem record errors:
 298     //CKKSServerKeyrollingNotAllowed = 10,
 299     //CKKSServerInvalidPublicIdentity = 11,
 300     //CKKSServerPublicKeyMismatch = 12,
 301     //CKKSServerServiceNumberMismatch = 13,
 302     //CKKSServerUnknownServiceNumber = 14,
 303     //CKKSServerEncverLessThanMinVal = 15,
 304     //CKKSServerCannotModifyWasCurrent = 16,
 305     //CKKSServerInvalidCurrentItem = 17,
 306 };
 307
 308 #define SecTranslateError(nserrorptr, cferror) \
 309     if(nserrorptr) { \
 310        *nserrorptr = (__bridge_transfer NSError*) cferror; \
 311     } else { \
 312        CFReleaseNull(cferror); \
 313     }
 314
 315 // Very similar to the secerror, secnotice, and secinfo macros in debugging.h, but add zoneNames
 316 #define ckkserrorwithzonename(scope, zoneName, format, ...) { os_log(secLogObjForScope("SecError"), scope "-%@: " format, (zoneName ? zoneName : @"unknown"), ## __VA_ARGS__); }
 317 #define ckksnoticewithzonename(scope, zoneName, format, ...) { os_log(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString: (zoneName ? zoneName : @"unknown")]), format, ## __VA_ARGS__); }
 318 #define ckksinfowithzonename(scope, zoneName, format, ...) { os_log_debug(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString: (zoneName ? zoneName : @"unknown")]), format, ## __VA_ARGS__); }
 319
 320 #define ckkserror(scope, zoneNameHaver, format, ...) \
 321 { NSString* znh = zoneNameHaver.zoneName; \
 322   ckkserrorwithzonename(scope, znh, format, ## __VA_ARGS__) \
 323 }
 324 #define ckksnotice(scope, zoneNameHaver, format, ...) \
 325 { NSString* znh = zoneNameHaver.zoneName; \
 326   ckksnoticewithzonename(scope, znh, format, ## __VA_ARGS__) \
 327 }
 328 #define ckksinfo(scope, zoneNameHaver, format, ...) \
 329 { NSString* znh = zoneNameHaver.zoneName; \
 330   ckksinfowithzonename(scope, znh, format, ## __VA_ARGS__) \
 331 }
 332
 333 #undef ckksdebug
 334 #if !defined(NDEBUG)
 335 #define ckksdebugwithzonename(scope, zoneName, format, ...) { os_log_debug(secLogObjForCFScope((__bridge CFStringRef)[@(scope "-") stringByAppendingString: (zoneName ? zoneName : @"unknown")]), format, ## __VA_ARGS__); }
 336 #define ckksdebug(scope, zoneNameHaver, format, ...) \
 337 { NSString* znh = zoneNameHaver.zoneName; \
 338   ckksdebugwithzonename(scope, znh, format, ## __VA_ARGS__) \
 339 }
 340 #else
 341 #define ckksdebug(scope,...)    /* nothing */
 342 #endif
 343
 344 #endif /* CKKS_h */