Security
- Certificate Pinning
- App Transport Security
- Data Generated and Stored by the SDK
- Brute-force attack prevention
- Local Data Manager
- Locked Authenticators
- SDK Hardening
Certificate Pinning
By default, the SDK will evaluate the certificate chain provided by the server for all performed requests. While this guarantees the certificate chain is valid, it does not prevent man-in-the-middle (MITM) attacks or other potential vulnerabilities. In order to mitigate MITM attacks, applications should use certificate pinning provided by the NevisServerPinningPolicy
.
The NevisServerPinningPolicy
evaluates the server trust provided by a URLAuthenticationChallenge
when connecting to the server over a secure HTTPS connection. The pinCertificates
option uses the pinned Subject Public Key Info (SPKI) to validate the server trust. The server trust is considered valid if one of the pinned SPKI hashes matches the server intermediate certificate SPKI hash (or the leaf certificate, if there is no intermediate certificate).
let configuration = NevisAuthenticationSession.Configuration(
// ...
.pinCertificates(hashes: ["<hash_value>"])
)
Note
Applications are encouraged to always pin certificates in production environments. If you still have to disable certificate pinning, you can use the.disablePinning
option.
See also Performing Manual Server Trust Authentication.
Extracting the SPKI Hash from a Certificate
The pinCertificates
option requires the SHA256 value of the Subject Public Key Info of the intermediate certificate(s). You can obtain it using the openssl
command:
openssl x509 -pubkey -noout -in <intermediate_cert>.pem | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -binary | openssl enc -base64
App Transport Security
App Transport Security (ATS) is a networking security feature available to apps that improves privacy and data integrity by ensuring your app’s network connections employ only industry-standard protocols and ciphers without known weaknesses. It is enabled by default and is different from certificate pinning done by the SDK.
If you want to check whether your endpoints are already compatible with ATS, you can run the following command on macOS:
/usr/bin/nscurl --ats-diagnostics --verbose <https://yOourdomain.com>
Data Generated and Stored by the SDK
The SDK generates and stores different types of sensitive data, including cryptographic keys, hashed application PIN and registration records. This data is stored in the Secure Enclave if possible (e.g. user authenticator private key), otherwise in the keychain.
The proper way to remove user key material is to perform a deregistration operation.
Though the SDK provides another solution for removing the stored data through LocalDataManager
. See LocalDataManager
Important
iOS preserves keychain items when an app is deleted, which means that data stored by the SDK still exist after re-installing an app, while not being accessible due to missing registration information. For this reason, it is the application responsibility to clear the keychain on a re-installation in order to remove all items associated with the application, including SDK data. This can be done by callingLocalDataManager.deleteAllData
.
Brute-force attack prevention
The PIN Authenticator is protected against non-sophisticated brute-force attacks. In case of a failed PIN verification attempts, the user has to wait for a predefined amount of time before being able to attempt the PIN verification again. After the 2nd failed attempt, a “cool-down” time is added as a penalty. The following table shows the added penalty for each failed attempt:
Number of failed attempts | Cool-Down (seconds) |
---|---|
1 | 0 |
2 | 0 |
3 | 60 |
4 | 180 |
Once the number of failed attempts is determined, the cool-down is calculated. In case cool-down is required, the current timestamp is saved and if a new PIN verification is started before the end of the cool-down period, the verification fails automatically.
When User interaction is initiated, the timeout for user interaction is extended with the cool-down time, to circumvent an unwanted timeout of the current operation.
Important In case the number of failed attempts would reach or exceed the configured maximum, the SDK will report a
FIDOError.userLockout
error, but no registration data is deleted.The failed attempts counter is only reset in case of successful authentication, or removal of the stored authenticator registration.
PIN Protection
The SDK stores a version of the PIN using PBKDF2.
The number of iterations used depends on the hardware used and calculated by the OS (CryptoCommon). For faster devices the calculated iterations is higher than for low-end devices, but the minimum iteration count is 10000.
Local Data Manager
As it is stated in its name, the scope of data management is local, meaning SDK only. No backend communication is executed within this manager.
Capabilities
- Retrieve all authenticators containing information about enrolment and registration for each authenticator.
- Retrieve the current
DispatchTargetConfiguration
if any. - Delete an authenticator registration.
- Delete
DispatchTargetConfiguration
. - Delete all data stored by the SDK.
Locked Authenticators
Fingerprint and face recognition authenticators are based on Touch ID and Face ID, respectively, and may be locked if there were too many failed attempts (see FIDOError.userLockout
). The only way to unlock these authenticators from this point onwards is for the user to enter the device passcode.
A solution that can be implemented by the application to unlock the biometry is to explicitly authenticate the user using passcode:
let context = LAContext()
let reason = "Enter the passcode to unlock the authenticator."
context.evaluatePolicy(LAPolicy.deviceOwnerAuthentication, localizedReason: reason, reply: { (success, error) in
if success {
// The authenticator will be available again for operations
}
})
SDK Hardening
The SDK is extensively obfuscated and protected against tampering and reverse engineering. It will detect any attempt of modifying the normal execution of the operations.
For a developer, the most important points to be taken into account are:
- Attaching a debugger will be detected.
- Executing the SDK in a jailbroken device will be detected.
When any kind of attack is detected, the SDK will prevent the normal execution of the operations following one of these patterns:
- Making the app crash.
- Stop responding to the operations.
- Throwing an exception.
Warning
Please make sure that you are not developing your application using a fully hardened SDK version.
Developing an Application using a Hardened SDK
Since a fully hardened SDK version will detect any attempt of debugging, and thus prevent the normal execution of operations, a special SDK flavor meant for development and integration is made available for developers.
This flavor, named Debug Hardened Simulator Flavor, has all the obfuscation and tampering detection features enabled, excluding the debugger detection, additionally it can be run in a simulator.
Important
For additional information, see: Flavors.