Egomet FIDO SDK for iOS

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).

Table of contents

1. System Requirements

2. 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.

2.1 Retrieve App Bundle ID

  1. Select the top project item in the navigator (located on the left side of the project window).
  2. Select Targets.
  3. Select the General tab.
  4. Copy the Bundle identifier field in the Identity section.

xcode general tab identity xcodeGeneralTabIdentity

2.2 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.

  1. Open a terminal with OpenSSL.
  2. Generate both, private key and CSR by running the following command:
    openssl req -new -newkey rsa:2048 -nodes -keyout yourPrivete.key -out egometFidoSdk.csr
  3. 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).

3. How to integrate Egomet FIDO SDK

3.1 Xcode integration

In Xcode add MVFidoSDK.framework into your project:

  1. Select the project file from the project navigator (located on the left side of the project window).
  2. From the Targets section, select the framework destination target.
  3. Select the General tab and find Embedded Binaries.

xcode general tab xcodeGeneralTab

  1. Click the + button and then press the "Add Other" button in order to select MVFidoSDK.framework.

xcode add embedded binaries xcodeAddEmbeddedBinaries

  1. If your device supports the Face ID feature, add the key NSFaceIDUsageDescription in the info.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.
  2. In order to access the production and test servers add the following properties in the info.plist file:

    <key>NSAppTransportSecurity</key>
    <dict>
    <key>NSExceptionDomains</key>
    <dict>
    <key>fido-api.movenda.com</key>
    <dict>
      <key>NSExceptionAllowsInsecureHTTPLoads</key>
      <true/>
    </dict>
    <key>fido-api-staging.movenda.com</key>
    <dict>
      <key>NSExceptionAllowsInsecureHTTPLoads</key>
      <true/>
    </dict>
    </dict>
    </dict>

3.2 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.

  1. Open a terminal with OpenSSL.
  2. Generate a PKCS#12 by running the following command:
    openssl pkcs12 -export -out yourKeyStore.p12 -inkey yourPrivete.key -in yourSignedCertificate.crt
  3. Place your licence file "yourKeyStore.p12" in your project folder.

3.3 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() {

    let pkcs12 = Bundle.main.url(forResource: <PKCS12 filename>, withExtension: "p12")

    self.movendaFidoSdk = MovendaFidoSDK.staging(bundleID:Bundle.main.bundleIdentifier, pkcs12:PKCS12(bundle:pkcs12, password:<password pkcs12>))

  }

  // MovendaFidoDelegate implementation

}

4. Operations

Commons usage patterns for enabling the operations:

4.1 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:<username>)

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).

To manage the responses of the registration operation implement the MovendaFidoDelegate protocol:

func didFinishRegistration(authenticatorOwnership: AuthenticatorOwnership)
{
  print("Successful registration for user \(authenticatorOwnership)")
}

func didFinishRegistration(error: Error)
{
  print("Registration failed \(error)")
}

The AuthenticatorOwnership is the object that identifies your username and the current device in the Egomet FIDO system.

We recommend to store this object 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.

4.2 User authentication

This operation permits to authenticate the user.

Start the user authentication process by invoking the authentication method:

self.movendaFidoSdk?.authentication()

To manage the responses of the authentication operation implement the MovendaFidoDelegate protocol:

func didFinishAuthentication(authenticatorOwnership: AuthenticatorOwnership)
{
  print("Successful authentication for user \(authenticatorOwnership)")
}

func didFinishAuthentication(error: Error)
{
  print("Authentication failed \(error)")
}

4.3 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()
{
  print("De-registration finished")
}

func didFinishDeregistration(error: Error)
{
  print("De-registration failed \(error)")
}

4.4 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:

More transactions types can be added later by submitting a request to egomet-support@movenda.com

4.4.1 Payment transaction

This operation permits to create a payment transaction that can be confirmed later using the confirm transaction method.

In order to create a payment transaction, you must create the PaymentTransaction object. After that, invoke the createTransaction method by passing in input 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");  

self.movendaFidoSdk?.create(paymentTransaction: payementTransaction)

To manage the responses of the business transaction operation implement the MovendaFidoDelegate protocol:

func didFinishBusinessTransaction(paymentTransaction: PaymentTransaction)
{
  print("Created Payment Transaction \(paymentTransaction)")  
}

func didFinishBusinessTransaction(error: Error)
{
  print("Transaction not created \(error)")
}

At this point you can ask the user confirmation:

self.movendaFidoSdk?.transactionConfirmation(authenticatorOwnership: <AuthenticatorOwnership>)

Finally manage the response:

func didFinishTransactionConfirmation(authenticatorOwnership: AuthenticatorOwnership)
{
  print("Confirmed Transaction for user  \(authenticatorOwnership)")
}

func didFinishTransactionConfirmation(error: Error)
{
  print("Transaction confirmation failed \(error)")
}

The image generated by the Egomet FIDO system will look like this:

payment transaction paymentTransaction

4.4.2 Free-text transaction

This operation permits to create a free-text transaction that can be confirmed later using the transactionConfirmation method.

In order to create a transaction that includes a generic content, you must create the FreeTextTransaction object. After that, invoke the createTransaction method by passing in input 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)

To manage the responses of the business transaction operation implement the MovendaFidoDelegate protocol:

func didFinishBusinessTransaction(freeTextTransaction: FreeTextTransaction)
{
  print("Created Free Text Transaction \(freeTextTransaction)")
}

func didFinishBusinessTransaction(error: Error)
{
  print("Transaction not created \(error)")
}

At this point you can ask the user confirmation:

self.movendaFidoSdk?.transactionConfirmation(authenticatorOwnership: <AuthenticatorOwnership>)

Finally manage the response:

func didFinishTransactionConfirmation(authenticatorOwnership: AuthenticatorOwnership)
{
  print("Confirmed Transaction for user  \(authenticatorOwnership)")
}

func didFinishTransactionConfirmation(error: Error)
{
  print("Transaction confirmation failed \(error)")
}

The image generated by the Egomet FIDO system will look like this:

free-text transaction freeTextTransaction

4.4.3 Bank transfer transaction

In order to create a transaction that includes a bank transfer, you must create the BankTransferTransaction object. After that, invoke the createTransaction method by passing in input 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"))

To manage the responses of the business transaction operation implement the MovendaFidoDelegate protocol:

func didFinishBusinessTransaction(bankTransferTransaction: BankTransferTransaction)
{
  print("Created Bank Transfer Transaction \(bankTransferTransaction)")
}

func didFinishBusinessTransaction(error: Error)
{
  print("Transaction not created \(error)")
}

At this point you can ask the user confirmation:

self.movendaFidoSdk?.transactionConfirmation(authenticatorOwnership: <AuthenticatorOwnership>)

Finally manage the response:

func didFinishTransactionConfirmation(authenticatorOwnership: AuthenticatorOwnership)
{
  print("Confirmed Transaction for user  \(authenticatorOwnership)")
}

func didFinishTransactionConfirmation(error: Error)
{
  print("Transaction confirmation failed \(error)")
}

The image generated by the Egomet FIDO system will look like this:

bank transfer transaction bankTransferTransaction

5. SDK error management

The SDK can generate the following types of errors: