iOS guide
FIDO UAF SDK
Egomet iOS SDK turns the FIDO Protocol with swift, allowing a rapid integration with the FIDO Services.
This guide allows the developer to integrate the SDK in the Relying Party Client App (AKA RPClient).
System Requirements
- Swift 4.2+
- iOS 11+
- Touch ID / Face ID
Request your Egomet FIDO SDK license
In order to make your App work with the SDK, you must enable your SDK license by submitting your App Bundle ID and CSR.
Retrieve App Bundle ID
- Select the top project item in the navigator (located on the left side of the project window).
- Select
Targets
. - Select the
General
tab. - Copy the
Bundle identifier
field in theIdentity
section.
Generate CSR
The following instructions will guide you through the CSR generation process via OpenSSL. If you already generated the CSR and received your trusted SSL certificate, check “License file integration” and disregard the steps below.
- Open a terminal with OpenSSL.
- Generate both, private key and CSR by running the following command:
openssl req -new -newkey rsa:2048 -nodes -keyout yourPrivete.key -out egometFidoSdk.csr
- Enter the following CSR details when prompted:
- Country Name: The official two-letter country code (i.e. IT, US) where your organization is legally incorporated.
- State or Province: The state or province where your organization is legally incorporated. Do not abbreviate.
- Locality Name: The locality or city where your organization is legally incorporated. Do not abbreviate.
- Organization Name: The full legal name of your organization including the corporate identifier.
- Organization Unit (OU): Your department such as ‘Information Technology’ or ‘Website Security’.
- Common Name: Use the FQDN (fully-qualified domain name) to indicate your service name (e.g.: demo.movenda.com).
How to integrate Egomet FIDO SDK
Xcode integration
In Xcode add MVFidoSDK.framework into your project:
- Select the project file from the project navigator (located on the left side of the project window).
- From the
Targets
section, select the framework destination target. - Select the
General
tab and findEmbedded Binaries
.
- Click the + button and then press the “Add Other” button in order to select
MVFidoSDK.framework
.
- If your device supports the Face ID feature, add the key
NSFaceIDUsageDescription
in theinfo.plist
file. The value of this key rappresents the message that your end user will view when the app will request the FaceID usage permission.
License file integration
The following instructions will guide you through the PKCS#12
generation process with OpenSSL. If you already received your trusted SSL certificate and generated the PKCS#12, go to the third step of this section.
- Open a terminal with OpenSSL.
- Generate a PKCS#12 by running the following command:
openssl pkcs12 -export -out yourKeyStore.p12 -inkey yourPrivete.key -in yourSignedCertificate.crt
- Place your licence file “yourKeyStore.p12” in your project folder.
SDK initialization
Import the Egomet FIDO SDK module within .swift
files (e.g.: yourfile.swift):
import MVFidoSDK
To initialize the SDK you must pass your PKCS#12 and its related password (e.g.: yourKeyStore.p12).
Use the method staging
only during the testing phase of the Egomet service.
Use the method production
for production phase.
For all operations use the protocol MovendaFidoDelegate
in your ViewController.
Here’s an example for the staging enviroment:
class ViewController: UIViewController, MovendaFidoDelegate
{
var movendaFidoSdk:MovendaFidoSDK?
override func viewDidLoad() {
super.viewDidLoad()
// setup views, as you would normally do in viewDidLoad
egometInit()
}
func egometInit() {
if let localPkcs12Path = Bundle.main.url(forResource: <PKCS12 filename>, withExtension: "p12"), let localPkcs12Data = try? Data(contentsOf: localPkcs12Path)
{
self.movendaFidoSdk = MovendaFidoSDK.staging(bundleID:bundleID:Bundle.main.bundleIdentifier!, pkcs12:PKCS12(bundle:localPkcs12Data, password:<password pkcs12>))
self.movendaFidoSdk?.delegate = self
}
}
// MovendaFidoDelegate implementation
}
You can check the SDK version by using the following method:
self.movendaFidoSdk?.version()
Operations
Commons usage patterns for enabling the operations:
- User Registration;
- User Authentication;
- User De-registration;
- Transaction confirmation.
User registration
This operation permits to enroll your device as a fast and secure authentication method.
Start the user registration process by invoking the registration
method:
self.movendaFidoSdk?.registration(username:<String>, rpChallenge:<UUID>)
NOTE:
- the string username must be a human-readable username intended to allow the user to distinguish and select from among different accounts (e.g: email address);
- the rpChallenge is a random UUID (RFC 4122) generated by RPClient App back-end
To manage the responses of the registration operation implement the MovendaFidoDelegate
protocol:
func didFinishRegistration(response:UafServerResponse)
{
// submit registration result to RPClient App back-end
}
func didFinishRegistration(error: Error)
{
// manage registration error
}
The UafServerResponse
represents the result of the FIDO Server computation: it contains the registration result along with the AuthenticatorOwnership
which carries on the username and the fidoId (i.e.: the current device in the Egomet FIDO system).
{
"operation_result" : {
"status" : "EXECUTED_SUCCESS"
}
"authenticator_ownership" : {
"fido_id" : "8963298209427",
"username" : "john.doe@aol.com"
},
"rp_challenge" : "ddcd964f-f89c-4896-b2e4-9a1976d39d48",
"signature" : "MzAyMDgyODI3NzgyODI4MjgyMUFGODI3MzI2NjM2NjY2NjYyMjBCQURDQUZFREVBRDY2REVBRkJBQkU4MjczNDc2NDY0Ng"
}
We recommend sending UafServerResponse
to RP back-end in order to:
- verify the signature with the FIDO Server public key
- inform your back-end about the registration result
We recommend also storing AuthenticatorOwnership
in your system in order to perform the next FIDO operation.
In the AuthenticatorOwnership
there are two properties: the registered username
and the fidoID
assigned by the Egomet FIDO system.
User authentication
This operation permits to authenticate the user.
Start the user authentication process by invoking the authentication
method:
self.movendaFidoSdk?.authentication(rpChallenge:<UUID>)
To manage the responses of the authentication operation implement the MovendaFidoDelegate
protocol:
func didFinishAuthentication(response:UafServerResponse)
{
// submit authentication result to RPClient App back-end
}
func didFinishAuthentication(error: Error)
{
// manage authentication error
}
We recommend sending UafServerResponse
to RP back-end in order to:
- verify the signature with the FIDO Server public key
- inform your back-end about the authentication result
User de-registration
This operation permits to de-register the device that was registered as an authentication method for a user.
Start the user de-registration process by invoking the deregistration
method:
self.movendaFidoSdk?.deregistration(authenticatorOwnership:<AuthenticatorOwnership>)
To manage the responses of the de-registration operation implement the MovendaFidoDelegate
protocol:
func didFinishDeregistration()
{
// de-registration finished
}
func didFinishDeregistration(error: Error)
{
// manage de-registration error
}
Creation and confirmation of business transaction
The SDK permits to build and confirm business transaction in order to accomplish various scenarios where a digital signature is required.
The SDK comes with 3 out-of-the-box transaction types:
- Payment transaction;
- Freetext transaction;
- Bank transfer transaction.
More transactions types can be added later by submitting a request to egomet-support@movenda.com
Payment transaction
This operation permits to confirm a payment transaction.
In order to create a payment transaction, you must create the PaymentTransaction
object.
let payementTransaction:PaymentTransaction = PaymentTransaction(authenticatorOwnership: <AuthenticatorOwnership>,payee:Payee(name:"AMAZON IT", website:"www.amazon.it", timeZone:TimeZone(identifier: "Europe/Rome") ?? TimeZone.current, locale:Locale(identifier: "it_IT")), order:"8991101200003200013", card:"MASTERCARD", cardExpiration:"MAY 2021", accountNumber:"8364648888", authorizationNumber:"***********738", amount:"231,75",currency: "EUR");
At this point you can ask the user confirmation:
self.movendaFidoSdk?.transactionConfirmation(paymentTransaction:<PaymentTransaction>, rpChallenge:<UUID>)
Finally manage the response:
func didFinishTransactionConfirmation(response:UafServerResponse)
{
// submit transaction result to RPClient App back-end
}
func didFinishTransactionConfirmation(error: Error)
{
// manage transaction confirmation error
}
The image generated by the Egomet FIDO system will look like this:
Free-text transaction
This operation permits to create a free-text transaction.
In order to create a transaction that includes a generic content, you must create the FreeTextTransaction
object:
let freeText = "I hereby agree to pay the CARs LTD for use of the Vehicle as follows: Fees: $10 per day/week. Fuel: is not required to pay for the use of fuel. Excess Mileage: $15 per mile Deposit: $200."
let freeTextTransaction:FreeTextTransaction = FreeTextTransaction(authenticatorOwnership: <AuthenticatorOwnership>,text:freeText)
At this point you can ask the user confirmation:
self.movendaFidoSdk?.transactionConfirmation(freeTextTransaction:<FreeTextTransaction>, rpChallenge:<UUID>)
Finally manage the response:
func didFinishTransactionConfirmation(response:UafServerResponse)
{
// submit transaction result to RPClient App back-end
}
func didFinishTransactionConfirmation(error: Error)
{
// manage transaction confirmation error
}
The image generated by the Egomet FIDO system will look like this:
Bank transfer transaction
In order to create a transaction that includes a bank transfer, you must create the BankTransferTransaction
object:
let bankTransferTransaction:BankTransferTransaction = BankTransferTransaction(authenticatorOwnership: <AuthenticatorOwnership>, account:"00000035001110", beneficiary:"Andrew Castel", iban:"IT80U076000000001111332", trn:"160223108400006231239100IT", cause:"House rent", amount:"550", timeZone:TimeZone(identifier: "Europe/Rome") ?? TimeZone.current,locale:Locale(identifier: "it_IT"))
At this point you can ask the user confirmation:
self.movendaFidoSdk?.transactionConfirmation(bankTransferTransaction:<BankTransferTransaction>, rpChallenge:<UUID>)
Finally manage the response:
func didFinishTransactionConfirmation(response:UafServerResponse)
{
// submit transaction result to RPClient App back-end
}
func didFinishTransactionConfirmation(error: Error)
{
// manage transaction confirmation error
}
The image generated by the Egomet FIDO system will look like this:
SDK error management
The SDK can generate the following types of errors:
UAFApplicationError :
- userCancelled → The user declined the UAF operation by pressing the Cancel button;
- authenticationTimeout → User didn’t perform any action (accept/cancel) on FIDO request;
- noSuitableAuthenticator → No authenticator matching the authenticator policy;
ConnectionError:
- connectionUnavailable → Called when a transport connection error occurs;
- serverUnderMaintenance → Called when Egomet System is under maintenance;
SDKError:
- internalSDK → Called when occurs SDK internal error;
- transactionNotFound → Called when transaction doesn’t exist for that
fidoID
or thefidoID
wasn’t found on the Egomet FIDO System; - userNotRegistered → Called when the user is not registered;
- certificateExpired → Called when the client certificate bundled in p12 file has expired. You must contact egomet-support@movenda.com for a certificate renewal;
You are set up now.
Fill in the requested information and request the SDK. If you still have doubts, consult the guides below.
Get the FIDO UAF SDK