Appendix

Sequence diagrams

Mobile Gateway - Session establishment sequence diagram

The diagram below describes the session establishment between the SDK and the Mobile Gateway.

Registration sequence diagram

The diagram below describes the enrollment of the SDK and the registration of a DSS profile.

Signing sequence diagram

The diagram below describes the signing flow when the signing process is initiated from an external SCA and the SDK is used to authenticate the user and unlock the signature.

DSS Key management

Key specification

256 bits Elliptic Curve (NIST P-256 curve)

Key security

Android

The key is explicitly configured to require user authentication for every use.

This authorization applies only to private key operations. Public key operations are not restricted. It is requested using the system Biometric Prompt with a CryptoObject defining the cryptographic operation to be performed by the operating system.

The key is irreversibly invalidated by the operating system once the secure lock screen of the device is disabled, or when (reconfigured to None, Swipe or other mode which does not authenticate the user) or when the secure lock screen is forcibly reset (e.g., by a Device Administrator), see the KeyGenParameterSpec documentation.

The key is also irreversibly invalided by the operating system on biometric enrollment, or when no more biometrics are enrolled (e.g., when user has removed all registered fingerprints).

The key is explicitly configured to be valid for a duration.

iOS

In RSS iOS 2.6.0, DSS keys are created with kSecAccessControlBiometryCurrentSet | kSecAccessControlPrivateKeyUsage and kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly.

Private-key operations require Face ID or Touch ID. The device passcode must be configured, but it is not a fallback authentication method for using the DSS private key. Retrieving the public key does not require biometric authentication.

The key is bound to the current biometric enrollment and to a device with a passcode. Changes to the biometric enrollment or removal of the passcode invalidate the key. See kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly.

To support batch signing, the SDK calculates a bounded authentication reuse window (TTL) when generating the key, using signing-time measurements and the configured maximum duration. Within this window, it can reuse an authenticated LAContext for private-key operations; after expiry, biometric authentication is requested again. This is authentication-context reuse, not an extension of the key's lifetime.

If authentication or a key operation fails, the SDK reports the error to the application. The application must distinguish cancellation or temporary biometric unavailability from key invalidation, refresh the profile state, and drive reactivation when necessary. The SDK does not automatically present or complete the application's reactivation flow.

Key lifecycle

Generation of the key

A new key pair (private / public keys) is generated every time a new profile is activated.

The key pair is generated in the TEE with an alias corresponding to the dssProfileId prefixed by the username of the user and _ separator. For example, on iOS: UhOb5ZUX21c9KKifNImBvZj8Zd337miNAcyfi35xlwA=_PROFILE-X.

To sign multiple consent tokens, the SDK configures a bounded authentication window based on the estimated time needed for the maximum number of elements at maximum payload size, with a margin and an upper duration limit. On iOS, this controls reuse of the authentication context; it does not expire the key itself.

Android

Once the key is created, we ensure that the key is correctly configured and resides in a secure hardware (Trusted Execution Environment (TEE) or a Secure Element (SE)) using the following KeyInfo methods.

KeyInfo.isInsideSecureHardware(): The key resides in a a TEE or a SE

KeyInfo.isUserAuthenticationRequired(): The key requires a user authentication to be used

KeyInfo.isUserAuthenticationRequirementEnforcedBySecureHardware(): The key requires a user authentication for every cryptographic operation (e.g. no temporal validity interval authorizations)

These checks are required to ensure the device's vendor fulfils the security requirements set by the Android Open Source Project.

iOS

Storage in the TEE is enforced at the key creation specified by Apple's documentation.

Public key operations

The public key is retrieved for every requests with the DSS:

• Register end user
• Get pending requests
• Get consent token
• Sign consent token

The use of the public key does not require user authentication.

Private key operations

The cryptographic operations with the private key are needed to sign with ECDSA the following DSS requests:

• Register end user
• Sign consent token

These operations are performed directly by the TEE. The user has to authenticate to unlock the key. When initializing the cryptographic operation, an error might be raised if the key has been irreversibly invalided by the system.

Key invalidation

The key pair is invalidated in the following cases:

• The biometric enrollment changes on iOS, or a new biometric is enrolled on Android.
• The device passcode is removed (iOS).
• The device's security lock is reset or disabled, or the user has removed all registered biometrics (Android only).
• During log in, if the application is disenrolled by the security back-end
• The application is disenrolled by the app (through API)

Once the key pair is invalidated, cryptographic operations are not possible anymore and a new DSS registration is required.

SAP Confirmation code

The confirmation code for a given document signing request is part of the SAP (Signature Activation Protocol) when the document to be signed is displayed, and the DTBS (Data To Be Signed) is generated on a different SCA (Signature Creation Application) device than the SIC (Signer Interaction Component) device.

The confirmation code's purpose is to allow the signer to easily correlate a signature activation request displayed on both the SCA and the SIC.

Specifications

The confirmation code shall be displayed to the signer on the SCA after submitting the DTBSR (Data To Be Signed Representation) to the SSA.

The confirmation code shall not be transmitted between the SCA and the SIC, only a "wake up" mobile push notification containing no transaction-related data should be sent to the SIC in order to initiate the SAP.

The SIC shall fetch the pending signature activation request from the SSA, and display the same confirmation code to the signer.

The confirmation code is derived from the responseID (defined in ETSI TS 119 432, chapter 7.26) on both the SCA and the SIC.

Derivation algorithm

The responseID is generated randomly by the DSS when submitting the DTBS from the SCA. The confirmation code is based on a decimal value derived from this responseID through the following algorithm:

1. Hash the responseID string's UTF-8 encoded value through SHA-256
2. Take the first 4 bytes and cast it as an unsigned integer
3. Use the resulting value modulo 100'000'000

The confirmation code is displayed in two groups of 4 digits, padded with zeros if needed, eg: 1234-5678

Inventory of cryptographic keys

The table below lists all cryptographic keys used by the SDK and its services. The list does not contain keys used exclusively by server modules.

iOS Error Codes

The table below list all available errors that may be raised by the iOS native SDK with Domain ch.sysmosoft.sense.framework.ErrorDomain. The integer error code can be used to identify specifically the type of the error.

DSS Error mapping

The table below list all available errors that may be raised by the DSS server component. The integer error code can be used to identify specifically the type of the error.

Client error codes

List of error codes that are likely to happen in case of registration synchronisation or signing timeout issues.

Most of code 32 errors (eg. when the application was reinstalled) can be prevented by checking the profile registration status before attempting to register or use a profile.

Some code 39 errors can still happen when a profile was unregistered from the backend or registered from a different device when the registration status was not yet refreshed. In that case, users should be prompted to delete and re-activate the profile.

Code 58 errors may happen in case the of a retry of a signing authentication that succeeded (users must be prevented from submitting the same request twice). Code 59 errors can happen when users take too much time for the biometric authentication. Usually, the user has 90 seconds to authenticate. In both cases, the application should synchronise with server and reload the pending request(s) and/or check for contract status.

Code 60 errors happen when the validation of integrity token against google playintegrity fails.

DSS component version: 3.0.0

Other error codes

With the exception of the client error codes from the previous section, other error codes are likely to be due to a configuration issue or temporary malfunction due to the failure of a backend component.

In that case, users should be prompted to retry a later, with the DSS error code printed in case the error persists and they need to contact the support.

DSS component version: 3.0.0