Secure Authentication with ASEE Token Library – How To Tutorial for iOS

This tutorial will guide you how to import ASEE Token Library and properly activate and load token instance.

Requirements

TokenSDK has following requirements for development:

Importing the SDK

SDK is delivered in a .zip format. After unzipping the delivered file you will be faced with two separate folders. One folder named SWIFT and the other one named ObjectiveC.

Both folders inside of them have folder SDK in which you can find XCFrameworks. To import the said framework:

1. Go to File – > Add Files to “YourProjectName”
   1.1. Choose the appropriate .xcframework for your target depending on the language
   1. Copy items if needed

2. Make sure to Embed & Sign your frameworks

3. Disable bitcode in build settings:

4. It is also needed to enable Always Embed Swift Standard Libraries

After importing the SDK we can move onto implementation.

Step 1. Activating token

On the first app instance, we should require the user to activate the token. This is done using the activateAndLoad method which is used to actiavte token on the device and immidielty loads it.

public class func activateAndLoad(

tokenName: String,

keychainAccessGroup: ASEETokenLib.CharArrayExt,

userID: ASEETokenLib.CharArrayExt,

clientID: ASEETokenLib.CharArrayExt,

activationCode: ASEETokenLib.CharArrayExt,

licenceKey: ASEETokenLib.CharArrayExt,

pin: ASEETokenLib.CharArrayExt,

serverInfo: ASEETokenLib.ServerInfo,

slotsToUnlock: [CharArrayExt],

success: @escaping(_ returnValue: TokenFacade?) -> Void,

failure: @escaping(_ err: Error) -> Void

) throws

Let’s further explain the parameters required for this method.

Token Name

tokenName is a constant name for your token and you will use it every time you want to get its instance with methods such as loadToken, getToken, etc., or to check if the token is secured with biometrics.

Keychain Access Group

Keychain Access Group is used to enable Keychain sharing to take advantage of the highest possible security for storing token data.

Please note that multiple keychain groups are not allowed in TokenSDK!

User ID

Activating the token with User ID is an additional security measure and it should be configured on SxS. If its not configured, the effect will be the same as if a regular method is used which does not send userId.

Activation Code and Client ID

Activation Code and Client ID form a 16-digit code that is used for activation. Usually, they are sent through different mediums, for example, 8 numbers of activation code are given on paper and the other 8 numbers are sent via SMS.

License Key

A license key is provided by ASEE to allow using this SDK.

PIN

Usually, the PIN is a 4 or 6-digit number that is later used for loading tokens and verifying transactions.

The SDK provides method isPINStrong which helps you determine if the entered pin satisfies certain constraints such as if the pin should not be ascending (1234).

We also recommend creating a custom keyboard for entering PIN. If a stock OS keyboard is used for data input, the user can be exposed to keylogger attacks.

Server Info

ServerInfo object contains data for connecting to the SxS server to enable token activation.

There are three exposed functions with different certificate pinning.

public static func create(dskppProxyURL: CharArrayExt, mtmProxyURL: CharArrayExt, niProxyURL: CharArrayExt? = nil, organizationID: Int, serviceID: Int, publicKeyModulus: CharArrayExt? = nil, publicKeyExponent: CharArrayExt? = nil, sxsVersion: SxSVersion) -> ServerInfo

public static func createWithPublicKeyPinning(dskppProxyURL: CharArrayExt, mtmProxyURL: CharArrayExt, niProxyURL: CharArrayExt? = nil, organizationID: Int, serviceID: Int, publicKeyModulus: CharArrayExt? = nil, publicKeyExponent: CharArrayExt? = nil, trustedCertificates: [CharArrayExt], sxsVersion: SxSVersion) throws -> ServerInfo 

public static func createWithCertificatePinning(dskppProxyURL: CharArrayExt, mtmProxyURL: CharArrayExt, niProxyURL: CharArrayExt? = nil, organizationID: Int, serviceID: Int, publicKeyModulus: CharArrayExt? = nil, publicKeyExponent: CharArrayExt? = nil, trustedCertificates: [CharArrayExt], sxsVersion: SxSVersion) throws -> ServerInfo 

In case of failure, error code is returend with which you can look up the ASEE Documentation to see what failed.

try TokenFacade.activateAndLoad(tokenName: tokenName, keychainAccessGroup: keychainAccessGroup, userID: userID, clientID: clientID, activationCode: activationCode, licenceKey: licenceKey, pin: pin, serverInfo: serverInfo, success: { (tokenInstance) in

                DispatchQueue.main.async {
            //present new screen
                        }


            }) { (error) in
                ASEEErrorHelper.checkError(from: self, error: error)

Activating Token

After adding all the necessary parameters and if the communication with SxS was successful, success completion handler will be called and our token will be activated and loaded into memory.

In case of failure, error code is returend with which you can look up the ASEE Documentation to see what failed.

try TokenFacade.activateAndLoad(tokenName: tokenName, keychainAccessGroup: keychainAccessGroup, userID: userID, clientID: clientID, activationCode: activationCode, licenceKey: licenceKey, pin: pin, serverInfo: serverInfo, success: { (tokenInstance) in

                DispatchQueue.main.async {
            //present new screen
                        }


            }) { (error) in
                ASEEErrorHelper.checkError(from: self, error: error)

Conclusion

If the activation is successful, a token instance will be returned and further token manipulation can be done such as changing the pin, securing the token with biometrics or approving transactions or calculations such as OTP, Challenge/Response.