keychain/headers/SecAccessControl.h

   1 /*
   2  * Copyright (c) 2014 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 /*!
  25  @header SecAccessControl
  26  SecAccessControl defines access rights for items.
  27  */
  28
  29 #ifndef _SECURITY_SECACCESSCONTROL_H_
  30 #define _SECURITY_SECACCESSCONTROL_H_
  31
  32 #include <Security/SecBase.h>
  33 #include <CoreFoundation/CFError.h>
  34 #include <sys/cdefs.h>
  35
  36 __BEGIN_DECLS
  37
  38 CF_ASSUME_NONNULL_BEGIN
  39 CF_IMPLICIT_BRIDGING_ENABLED
  40
  41 /*!
  42  @function SecAccessControlGetTypeID
  43  @abstract Returns the type identifier of SecAccessControl instances.
  44  @result The CFTypeID of SecAccessControl instances.
  45  */
  46 CFTypeID SecAccessControlGetTypeID(void)
  47 __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
  48
  49 /*!
  50  @typedef SecAccessControlCreateFlags
  51
  52  @constant kSecAccessControlUserPresence
  53  User presence policy using biometry or Passcode. Biometry does not have to be available or enrolled. Item is still
  54  accessible by Touch ID even if fingers are added or removed. Item is still accessible by Face ID if user is re-enrolled.
  55
  56  @constant kSecAccessControlBiometryAny
  57  Constraint: Touch ID (any finger) or Face ID. Touch ID or Face ID must be available. With Touch ID
  58  at least one finger must be enrolled. With Face ID user has to be enrolled. Item is still accessible by Touch ID even
  59  if fingers are added or removed. Item is still accessible by Face ID if user is re-enrolled.
  60
  61  @constant kSecAccessControlTouchIDAny
  62  Deprecated, please use kSecAccessControlBiometryAny instead.
  63
  64  @constant kSecAccessControlBiometryCurrentSet
  65  Constraint: Touch ID from the set of currently enrolled fingers. Touch ID must be available and at least one finger must
  66  be enrolled. When fingers are added or removed, the item is invalidated. When Face ID is re-enrolled this item is invalidated.
  67
  68  @constant kSecAccessControlTouchIDCurrentSet
  69  Deprecated, please use kSecAccessControlBiometryCurrentSet instead.
  70
  71  @constant kSecAccessControlDevicePasscode
  72  Constraint: Device passcode
  73
  74  @constant kSecAccessControlWatch
  75  Constraint: Watch
  76
  77  @constant kSecAccessControlOr
  78  Constraint logic operation: when using more than one constraint, at least one of them must be satisfied.
  79
  80  @constant kSecAccessControlAnd
  81  Constraint logic operation: when using more than one constraint, all must be satisfied.
  82
  83  @constant kSecAccessControlPrivateKeyUsage
  84  Create access control for private key operations (i.e. sign operation)
  85
  86  @constant kSecAccessControlApplicationPassword
  87  Security: Application provided password for data encryption key generation. This is not a constraint but additional item
  88  encryption mechanism.
  89 */
  90 typedef CF_OPTIONS(CFOptionFlags, SecAccessControlCreateFlags) {
  91     kSecAccessControlUserPresence           = 1u << 0,
  92     kSecAccessControlBiometryAny            API_AVAILABLE(macos(10.13.4), ios(11.3)) = 1u << 1,
  93     kSecAccessControlTouchIDAny             API_DEPRECATED_WITH_REPLACEMENT("kSecAccessControlBiometryAny", macos(10.12.1, 10.13.4), ios(9.0, 11.3)) = 1u << 1,
  94     kSecAccessControlBiometryCurrentSet     API_AVAILABLE(macos(10.13.4), ios(11.3)) = 1u << 3,
  95     kSecAccessControlTouchIDCurrentSet      API_DEPRECATED_WITH_REPLACEMENT("kSecAccessControlBiometryCurrentSet", macos(10.12.1, 10.13.4), ios(9.0, 11.3)) = 1u << 3,
  96     kSecAccessControlDevicePasscode         API_AVAILABLE(macos(10.11), ios(9.0)) = 1u << 4,
  97     kSecAccessControlWatch                  API_AVAILABLE(macos(10.15), ios(NA), iosmac(13.0)) = 1u << 5,
  98     kSecAccessControlOr                     API_AVAILABLE(macos(10.12.1), ios(9.0)) = 1u << 14,
  99     kSecAccessControlAnd                    API_AVAILABLE(macos(10.12.1), ios(9.0)) = 1u << 15,
 100     kSecAccessControlPrivateKeyUsage        API_AVAILABLE(macos(10.12.1), ios(9.0)) = 1u << 30,
 101     kSecAccessControlApplicationPassword    API_AVAILABLE(macos(10.12.1), ios(9.0)) = 1u << 31,
 102 } __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
 103
 104 /*!
 105  @function SecAccessControlCreateWithFlags
 106  @abstract Creates new access control object based on protection type and additional flags.
 107  @discussion Created access control object should be used as a value for kSecAttrAccessControl attribute in SecItemAdd,
 108  SecItemUpdate or SecKeyGeneratePair functions.  Accessing keychain items or performing operations on keys which are
 109  protected by access control objects can block the execution because of UI which can appear to satisfy the access control
 110  conditions, therefore it is recommended to either move those potentially blocking operations out of the main
 111  application thread or use combination of kSecUseAuthenticationContext and kSecUseAuthenticationUI attributes to control
 112  where the UI interaction can appear.
 113  @param allocator Allocator to be used by this instance.
 114  @param protection Protection class to be used for the item. One of kSecAttrAccessible constants.
 115  @param flags If no flags are set then all operations are allowed.
 116  @param error Additional error information filled in case of failure.
 117  @result Newly created access control object.
 118  */
 119 __nullable
 120 SecAccessControlRef SecAccessControlCreateWithFlags(CFAllocatorRef __nullable allocator, CFTypeRef protection,
 121                                                     SecAccessControlCreateFlags flags, CFErrorRef *error)
 122 API_AVAILABLE(macos(10.10), ios(8.0));
 123
 124 CF_IMPLICIT_BRIDGING_DISABLED
 125 CF_ASSUME_NONNULL_END
 126
 127 __END_DECLS
 128
 129 #endif // _SECURITY_SECACCESSCONTROL_H_