RapID Multiple Credential Support
The RapID client library supports multiple credentials on the same device using a label to uniquely identify each credential. This means you can register a credential against a label of your choice and use that credential later by providing the label to identify it. The following methods support multiple credentials:
identityExistscollectIdentityremoveIdentitysignData- with label
The following methods, which support only a single credential per device, are now deprecated and should not be used by developers:
signDataregisterDevice
The following methods are still current but they operate on all labels.
unregisterDeviceisDeviceRegistered
The method unregisterDevice will unregister All labels that you have created in your mobile app and isDeviceRegistered will return true if any label has been registered.
SDK Methods
All methods available on the RapID SDK are outlined below with information pertaining to their use. For specific code samples see the corresponding section on the SDK platform relevant to you.
Entering Background
The RapID client library must be notified when the application enters the background. This is achieved by calling the enteringBackground method. The
result of this call will determine if a user will need to re-authenticate their PIN or Fingerprint when resuming the app and performing an action that
requires access to the stored credential
Identity Exists
The method identityExists checks whether your app has an existing RapID credential present against a particular label name. It returns a Boolean value of true if a credential
is found under the specified label, otherwise false. The result of this call should determine whether you need to perform a new credential request operation for a
particular label.
Collect Identity
The method collectIdentity performs all of the internal operations and RapID server communication to create and store a RapID credential against a user defined label name. It replaces
the registerDevice method which only supported a single credential per device. You will need to pass in the RequestId that was returned from your server's call
to request a new credential and the label you wish to refer to it by. Internally, the RapID client library then examines the device to discover what credential
stores are available, selects the most suitable and generated a cryptographic key pair in the store. This is then used to sign a PKCS#10 certificate request,
which also binds the RequestId within the signed data.
The certificate request is transmitted to the RapID service, which locates and validates the request. It substitutes the actual unique user id for the request, then creates and returns the certificate to the client.
Finally, the library stores the certificate against the label reference, which is now ready for use. During its interaction with your client keystore, the RapID
client library will present any necessary user interface elements to perform user validation such as PIN or finger print enrolment. A RapidStatus value is
returned from the operation indicating the result.
Remove Identity
The method removeIdentity is similar to unregisterDevice with the addition of a label name parameter. It will delete only the RapID credential identified by the
given label name. All other credentials relating to other label names will remain intact.
Send Request
The sendRequest method performs a two-way TLS operation. The HttpRequest object allows you to specify the HTTP verb, URL, header, body, timeout, label name
and authentication mode on a per request basis. It returns a HTTP response object containing response header, body, status and error information.
Each platform wraps this core library method in different ways, meaning that in some cases you need to call it explicitly, whereas in other environments
it automatically intercepts your HTTP traffic, depending on your configured whitelist of URLs. The server certificate verification carried out by the
RapID client library will currently accept expired, revoked or incomplete chained certificates. Intermediary certificates added by a proxy are not supported.
Note: When the sendRequest API method is used for two-way TLS, a change of label to the same URL will cause ALL current sessions to be reset allowing the new credential to be used.
Sign Data
The method signData lets your app sign data with the private key of the RapID credential identified by the given label. It can force the user to re-authenticate
depending on the RapidAuthentication parameter passed in. It will return a SignResult object when successful (see platform specific SDKs for more information).
This feature's purpose is to implement security features beyond basic TLS client authentication such as transaction signing of out-of-band authentication.
Sign Result
The native RapID client libraries uses the SignResult object as a return type from the signData method. It allows more than one value to be returned from the method.
See the relevant platform specific SDKs for more information.
Unregister Device
The method unregisterDevice is intended primarily for app developers as a convenient means of clearing down a RapID app. It will delete All RapID keys and certificates that
have been installed, effectively resetting the credential store to its original state.
Is Device Registered
The method isDeviceRegistered checks whether your app has an existing RapID credential present against any label. It returns a Boolean value of true if a credential is present,
otherwise false. This method has now been replaced by IdentyExists which checks against a specific label as opposed to checking for any credential.
Verify Data
The method verifyData lets you verify the signed data using the public key from your RapID certificate that has the Digital Signature key usage. The input data is required
to be a PKCS7 bundle which contains the original data as well as the signature.
Logout
The method logout is intended to ensure that any further secure access requires the user to authenticate again.
Set Dialog Properties
The method setDialogProperties allows the RapID client library PIN create, verify, PIN authentication, fingerprint authentication and message dialog appearance to be customised.
Examples are given in the platform specific documentation and the SDK Programmers Guide.
RapID Status Codes
The following RapidStatus error codes are defined for the RapID client library.
| Rapid Status Name | Value | Description |
|---|---|---|
| RapidSuccess | 0 | The request completed successfully |
| RapidErrorUnknown | 1 | The client incurred an unknown error |
| RapidErrorParsingCertificate | 2 | The client was unable to read the certificate |
| RapidErrorCertificateJsonNotAString | 3 | The certificate was not in the format expected by the client |
| RapidErrorPkcs7IsEmpty | 4 | The client could not find the certificate from the server |
| RapidServerErrorUnknown | 5 | The server incurred an unknown error |
| RapidServerNoClientCertificateSupplied | 6 | The server was not supplied with the client certificate |
| RapidServerNoClientCertificateFound | 7 | The server was unable to locate the client certificate |
| RapidServerUnknownClientCertificate | 8 | The server received an unknown client certificate |
| RapidServerJWTValidationError | 9 | The server was unable to validate the JSON Web Token |
| RapidServerUnableToProcessJWT | 10 | The server was unable to process the JSON Web Token |
| RapidServerClientCertificateMismatch | 11 | The server detected a mismatch with the client certificate |
| RapidServerJWTThumbprintNotFound | 12 | The server could not locate the JSON Web Token thumbprint |
| RapidServerCertificateRequestInvalid | 13 | The server received an invalid certificate request |
| RapidServerCertificateRequestTimeout | 14 | The server received an expired certificate request |
| RapidServerCertificateRequestFailed | 15 | The server reported that the certificate request has failed |
| RapidServerCertificateAlreadyCollected | 16 | The certificate has already been collected |
| RapidServerCustomerNotFound | 17 | The server was unable to find the customer |
| RapidServerNoCustomerlicenses | 18 | The server reported that there are no customer licenses |
| RapidServerCertificateCollectRequestInvalid | 19 | The server received an invalid collect request from the client |
| RapidServerRequestNotFound | 20 | The server reported an unrecognized request |
| RapidServerCertificateAuthorityNotFound | 21 | The server was unable to locate the Certificate Authority |
| RapidServerIdentifierInvalid | 22 | The server received an invalid identifier |
| RapidClientAuthCertValidInFuture | 23 | The client authentication certificate is valid in the future |
| RapidClientAuthCertExpired | 24 | The client authentication certificate has expired |
| RapidClientUserCancelled | 25 | The client user cancelled an operation |
| RapidClientUserAuthFailed | 26 | The client user failed to authenticate. Seen on iOS after three failed Touch ID attempts |
| RapidClientDeviceBlocked | 27 | The client device has become PIN/Fingerprint blocked |
| RapidClientPinNotSet | 28 | The user’s PIN has not been set on the client |
| RapidClientCertificateNotValidForSigning | 29 | The certificate is not valid for signing on the client |
| RapidClientCertificateNotFound | 30 | The certificate was not found on the client |
| RapidClientInvalidParameter | 31 | An invalid parameter was detected on the client |