TouchId.yml

name: Modules.TouchId
summary: Allows a Titanium application to use the iOS Touch ID authentication mechanism.
platforms: [iphone, ipad, android]
since: {iphone: "3.4.0", ipad: "3.4.0", android: "5.4.0"}
extends: Titanium.Module
description: |
    Touch ID is a security mechanism that uses a fingerprint to authenticate the user. The
    fingerprint sensor is located in the Home button of the device.  Users can use their fingerprint
    instead of entering their passcode for authentication.

    ### Requirements

    The Touch ID module is available with the Titanium SDK starting with Release 3.4.0.
    This module only works with devices running iOS 8.  You can only test the Touch ID module on a device.

    The device must have a Touch ID sensor in the Home button and Touch ID must be setup in order to use
    the Touch ID authentication mechanism.  You can set up Touch ID in iOS Setup Assistant or by
    tapping **Touch ID & Passcode** from Settings.

    For information on setting up Touch ID, see
    [iPhone 5s: Using Touch ID](http://support.apple.com/kb/HT5883).

    ### Getting Started

    Add the module as a dependency to your application by adding a **`<module>`** item to the
    **`<modules>`** element of your `tiapp.xml` file:

        <ti:app>
          ...
          <modules>
            <module platform="iphone">ti.touchid</module>
          </modules>
          ...
        </ti:app>

    Use `require()` to access the module from JavaScript:

        var TouchId = require("ti.touchid");

    The `TouchId` variable is a reference to the module. Make API calls using this reference:

        TouchId.authenticate({
            reason: "Need to modify personal settings.",
            callback: function(e) {
                Ti.API.info(e);
            }
        });
        
    ### Keychain Integration (iOS-only)

    Since 2.1.0, the module support basic and advanced keychain integrations to allow
    the user to store sensitive information in the native iOS keychain.
    
    **Important**: For devices running iOS 10 and later, you now must include an 
    entitlements file that enables Keychain Sharing Capabilities. To do so, create 
    a /platform/ios/name.entitlements file (replace name with the name element in 
    the tiapp.xml) with the following content:
        
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
        <plist version="1.0">
        <dict>
            <key>keychain-access-groups</key>
            <array>
                <!-- APP_ID same as the id value in the tiapp.xml file -->
                <string>$(AppIdentifierPrefix)APP_ID</string>
            </array>
        </dict>
        </plist>
    
    The following example demonstrates the basic usage to save, read and delete 
    values with the native iOS keychain:
        
        // Write to keychain
        TouchID.saveValueToKeychain({
            identifier: "password",
            value: "s3cr3t_p4$$w0rd",
            callback: function(e) {
                Ti.API.info(e);
            }
        });
        
        // Read from keychain
        TouchID.readValueFromKeychain({
            identifier: "password",
            callback: function(e) {
                Ti.API.info(e);
            }
        });
        
        // Delete from keychain
        TouchID.deleteValueFromKeychain({
            identifier: "password"
        });
    
    For advanced security options, you can specify accessibility mode to the keychain 
    that will be applied when writing items to the keychain, for example:
        
        TouchID.saveValueToKeychain({
            identifier: "password",
            accessibilityMode: TouchId.ACCESSIBLE_AFTER_FIRST_UNLOCK,
            accessControlMode: TouchId.ACCESS_CONTROL_DEVICE_PASSCODE,
            value: "s3cr3t_p4$$w0rd",
            callback: function(e) {
                Ti.API.info(e);
            }
        });

    ### Sample Application

    The module contains a sample application in the
    `<TITANIUM_SDK_HOME>/modules/iphone/ti.touchid/<VERSION>/example/` folder.

methods:
  - name: authenticate
    summary: Initiates the Touch ID authentication process.
    description: |
      A special note for Android:

      When you call this method in Android, if you provide an incorrect fingerprint and receive an error
      message "Unable to recognize fingerprint", do not call authenticate. Instead, get the user to try
      again. If you call authenticate, it will end up in a bad state. This flow will be improved in the
      next update for Android.
    parameters:
      - name: params
        summary: Dictionary of arguments passed to the method, e.g. the reason to autheicate and the callback.
        type: TouchIdAuthenticationType

  - name: invalidate
    summary: Invalidates the current Touch ID dialog.
    description: |
        The context is invalidated automatically when it is (auto)released. 
        
        This method allows invalidating it manually while it is still in scope.
        Invalidation terminates any existing policy evaluation and the respective call will
        fail with <Modules.TouchId.ERROR_APP_CANCELLED>. After the context has been invalidated, it can not be
        used for policy evaluation and an attempt to do so will fail with <Modules.TouchId.ERROR_INVALID_CONTEXT>.
    
    platforms: [iphone, ipad]
    since: "2.1.0"

  - name: deviceCanAuthenticate
    summary: Checks to see if device is configured for Touch ID authentication.
    description: |
        Example usage:
      
            if (!TiTouchId.deviceCanAuthenticate()) {
                alert('Message: ' + result.error + '\nCode: ' + result.code);  
            } else {
                alert('device can authenticate');
            }
    returns:
        type: DeviceCanAuthenticateResult

  - name: isSupported
    summary: Determines if the current device supports Touch ID.
    returns:
        type: Boolean

  - name: saveValueToKeychain
    summary: Saves a new value to the iOS keychain
    description: |
        Please ensure that the `identifier` does not contain any alphanumeric
        characters. The system keychain might reject the value in that case.
    parameters:
      - name: params
        summary: Dictionary of arguments passed to the keychain.
        type: KeychainItemType
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: readValueFromKeychain
    summary: Reads an existing value to the iOS keychain.
    description: |
        Please ensure that the `identifier` does not contain any alphanumeric
        characters. The system keychain might abort the access in that case.
    parameters:
      - name: params
        summary: Dictionary of arguments passed to the keychain.
        type: KeychainItemType
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: deleteValueFromKeychain
    summary: Deletes an existing value from the iOS keychain.
    description: |
        Please ensure that the `identifier` does not contain any alphanumeric
        characters. The system keychain might abort the deletion in that case.
    parameters:
      - name: params
        summary: Dictionary of arguments passed to the keychain.
        type: KeychainItemType
    platforms: [iphone, ipad]
    since: "2.1.0"

properties:

  - name: ERROR_AUTHENTICATION_FAILED
    summary: Constant indicating that the authentication was not successful.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_PASSCODE_NOT_SET
    summary: Constant indicating that the passcode is not set for the device.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    

  - name: ERROR_TOUCH_ID_NOT_AVAILABLE
    summary: Constant indicating that Touch ID is not available on the device.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_TOUCH_ID_NOT_ENROLLED
    summary: Constant indicating that Touch ID does not have any enrolled fingerprints.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_SYSTEM_CANCEL
    summary: |
        Constant indicating that iOS cancelled authentication, for example, if another
        application enters the foreground.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_USER_CANCEL
    summary: Constant indicating that the user canceled authentication.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_USER_FALLBACK
    summary: Constant indicating that the user tapped the fallback button to enter their passcode.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_APP_CANCELLED
    summary: Constant indicating that the app cancelled authentication.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_INVALID_CONTEXT
    summary: Constant indicating that there is an invalid context.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]

  - name: ERROR_TOUCH_ID_LOCKOUT
    summary: Constant indicating that Touch ID has locked out.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    
  - name: ACCESSIBLE_WHEN_UNLOCKED
    summary: |
        Item data can only be accessed while the device is unlocked. This is 
        recommended for items that only need be accesible while the application 
        is in the foreground.  Items with this attribute will migrate to a new 
        device when using encrypted backups.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_AFTER_FIRST_UNLOCK
    summary: |
        Item data can only be accessed once the device has been unlocked after 
        a restart.  This is recommended for items that need to be accesible by 
        background applications. Items with this attribute will migrate to a new 
        device when using encrypted backups.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_ALWAYS
    summary: |
        Item data can always be accessed regardless of the lock state of the device.  
        This is not recommended for anything except system use. Items with this 
        attribute will migrate to a new device when using encrypted backups.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_WHEN_PASSCODE_SET_THIS_DEVICE_ONLY
    summary: |
         Item data can only be accessed while the device is unlocked. This class 
         is only available if a passcode is set on the device. This is recommended 
         for items that only need to be accessible while the application is in the
         foreground. Items with this attribute will never migrate to a new 
         device, so after a backup is restored to a new device, these items 
         will be missing. No items can be stored in this class on devices 
         without a passcode. Disabling the device passcode will cause all 
         items in this class to be deleted.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_WHEN_UNLOCKED_THIS_DEVICE_ONLY
    summary: |
        Item data can only be accessed while the device is unlocked. This is 
        recommended for items that only need be accesible while the application 
        is in the foreground. Items with this attribute will never migrate to a 
        new device, so after a backup is restored to a new device, these items 
        will be missing.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY
    summary: |
        Item data can only be accessed once the device has been unlocked after a 
        restart. This is recommended for items that need to be accessible by 
        background applications. Items with this attribute will never migrate to 
        a new device, so after a backup is restored to a new device these items 
        will be missing.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESSIBLE_ALWAYS_THIS_DEVICE_ONLY
    summary: |
        Item data can always be accessed regardless of the lock state of the device.  
        This option is not recommended for anything except system use. Items with 
        this attribute will never migrate to a new device, so after a backup is
        restored to a new device, these items will be missing.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_USER_PRESENCE
    summary: |
        User presence policy using Touch ID or Passcode. Touch ID does not have 
        to be available or enrolled. Item is still accessible by Touch ID even 
        if fingers are added or removed.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_TOUCH_ID_ANY
    summary: |
        Constraint - Touch ID (any finger). Touch ID must be available and at least 
        one finger must be enrolled. Item is still accessible by Touch ID even if 
        fingers are added or removed.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_TOUCH_ID_CURRENT_SET
    summary: |
        Constraint - Touch ID from the set of currently enrolled fingers. Touch ID 
        must be available and at least one finger must be enrolled. When fingers 
        are added or removed, the item is invalidated.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_DEVICE_PASSCODE
    summary: Constraint - Device passcode.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_OR
    summary: |
        Constraint logic operation - When using more than one constraint, at least 
        one of them must be satisfied.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_AND
    summary: |
        Constraint logic operation - When using more than one constraint, all must
        be satisfied.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_PRIVATE_KEY_USAGE
    summary: Create access control for private key operations (i.e. sign operation).
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"
    
  - name: ACCESS_CONTROL_APPLICATION_PASSWORD
    summary: |
        Security: Application provided password for data encryption key generation. 
        This is not a constraint but additional item encryption mechanism.
    type: Number
    permission: read-only
    platforms: [iphone, ipad]
    since: "2.1.0"

---
name: TouchIdAuthenticationType
platforms: [android, iphone, ipad]
summary: Dictionary passed to <Modules.TouchId.authenticate>.
properties:
  - name: reason
    optional: false
    summary: |
        Note: This property is iOS only!

        Message displayed in the authentication dialog describing why the
        application is requesting authentication.
    type: String
    
  - name: maxBiometryFailures
    summary: |
        Note: This property is iOS only!

        Allows setting the limit for the number of failures during biometric 
        authentication. When the specified limit is exceeded, the evaluation of 
        the <Modules.TouchId.authenticate> method will fail with the error
        <Modules.TouchId.ERROR_AUTHENTICATION_FAILED>. By default this property 
        is undefined and the biometric authentication fails after 3 wrong attempts. 
        Please note that setting this property with high values does not prevent 
        biometry lockout after 5 wrong attempts.
    type: Number
    since: "2.1.0"
    osver: {ios: {min: "9.0"}}
    
  - name: allowableReuseDuration
    summary: |
        Note: This property is iOS only!

        This property can be set with a time interval in seconds. If the device 
        was successfully unlocked by Touch ID within this time interval, then 
        Touch ID authentication on this context will succeed automatically and the 
        reply block will be called without prompting user for Touch ID.

        The default value is 0, meaning that no previous TouchID unlock can be reused.

        This property is meant only for reusing Touch ID matches from the device 
        lock screen. It does not allow reusing previous Touch ID matches in 
        application or between applications.

        The maximum supported interval is 5 minutes and setting the value beyond 
        5 minutes does not increase the accepted interval.    
    type: Number
    since: "2.1.0"
    osver: {ios: {min: "9.0"}}
    
  - name: fallbackTitle
    summary: |
        Allows fallback button title customization. A default localized title 
        "Enter Password" is used when this property is left nil. If set to empty 
        string, the button will be hidden.
    type: String
    since: "2.1.0"
    osver: {ios: {min: "10.0"}}
    
  - name: cancelTitle
    summary: |
        Allows cancel button title customization. A default localized title "Cancel" 
        is used when this property is not defined or is set to empty string.
    type: String
    since: "2.1.0"
    osver: {ios: {min: "10.0"}}
  
  - name: callback
    optional: false
    summary: |
        Callback function executed after the authentication completes. 
        The callback function is passed a dictionary with three properties:

          * `success` (Boolean): Set to true if authentication succeeded.
          * `error` (String): System error message.
          * `code` (Number): Module `ERROR_*` constant indicating the reason for the failure.        
    type: Callback
    
---
name: DeviceCanAuthenticateResult
platforms: [android, iphone, ipad]
since: "1.0.1"
summary: Dictionary containing results for <Modules.TouchId.deviceCanAuthenticate>.
properties:
  - name: canAuthenticate 
    summary: Set to true if device is configured for touch ID authentication.
    type: Boolean

  - name: error
    summary: System error message if any.
    type: String

  - name: code
    summary: iOS only, Module `ERROR_*` constant indicating the reason for the failure if any.
    type: Number

---
name: KeychainItemType
platforms: [iphone, ipad]
since: "2.1.0"
summary: | 
    Dictionary passed to <Modules.TouchId.saveValueToKeychain>,
    <Modules.TouchId.readValueFromKeychain> or <Modules.TouchId.deleteValueFromKeychain>.
properties:
    - name: identifier
      optional: false
      summary: |
          Required identifier to create or receive a keychain item. The identifier 
          cannot contain alphanumeric characters or it might be rejected by the keychain.
      type: String
    
    - name: callback
      optional: false
      summary: |
          Required callback function that is executed after the the keychain item 
          is saved/received or rejected by the system keychain.
      type: Callback
      
    - name: accessGroup
      summary: |
          Optional identifier used to define the access group the keychain item
          should be valid. This can be used to share a keychain item across two
          or more apps that use the same organization group identifier.
          More information about keychain access groups can be found in the
          [official iOS documentation](https://developer.apple.com/reference/security/ksecattraccessgroup).
      type: String

    - name: accessibilityMode  
      summary: |
          Optional constant used for determining when a keychain item should be 
          readable. Use this property with caution to enable advanced access control.
          More information about this property and it's values can be found in the 
          [official iOS documentation](https://developer.apple.com/reference/security/1658642-keychain_services/1663541-keychain_item_accessibility_cons).
      type: Number
      constants: Modules.TouchId.ACCESSIBLE_*
      
    - name: accessControlMode
      summary: |
          Optional constants used to determine the access control with the specified 
          protection type and flags. The constants can be concatenated by using the
          Bit OR operator, e.g. `optionA | optionB | optionC`.
      type: Number
      constants: Modules.TouchId.ACCESS_CONTROL_*