Certification Process

In order for a user to be able to authenticate online and sign documents, they need to have first completed the certification process.

This process involves three steps: Phone Verification, Registration and Certification.

Phone Verification

The device that the app is running on needs to be verified before the user can register an account.

NB Even if the app supports multiple entities, the device only needs to be verified once.

Before the device is verified, the user has a status of UNVERIFIED

To verify the device the user first needs to request a verification code:

Swift3

    SDK.getClient.requestUserDeviceVerification(
        onSuccess: {
            // Verification Request Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onDeviceVerificationLimitError: { (error) in
                // Handle device verification limit error
        }, onClientError:  { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestUserDeviceVerificationOnSuccess:^ {
          // Verification Request Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onDeviceVerificationLimitError:^void(NSError * _Nonnull error) {
            // Handle device verification limit error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
     ];

Documentation

If the verification request is successfully made, an SMS with a verification code is sent to the phone number the user registered with.

This code can then be used to verify the device as follows:

Swift3

    SDK.getClient.verifyUserDevice(withVericationCode: code,
        onSuccess: {
            // Handle Verification Success
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onValidationError: { (error) in
                // Handle validation error
        }, onExpiredVerificationCodeError: { (error) in
                // Handle expired verification code error
        }, onUserLockedError: { (error) in
                // Handle locked user error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient verifyUserDeviceWithVericationCode:code
        onSuccess:^{
            // Handle Verification Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
                // Handle validation error
        }
        onExpiredVerificationCodeError:^void(NSError * _Nonnull error) {
                // Handle expired verification code error
        }
        onUserLockedError:^void(NSError * _Nonnull error) {
                // Handle locked user error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
     ];

Documentation

Phone Verification Flow

Registration

Once the user’s device has been verified successfully, the user will have a status of UNREGISTERED.

NB To check the status of a user, the API call requestUser can be used as follows:

Swift3

    SDK.getClient.requestUser(
        onSuccess: { (user) in
            if user.status == User.Status.unregistered {
                // Unregistered
            }
        }, onNoConnection: {
            // Handle no connection
        }, onInvalidToken: { (error) in
            // Handle invalid token
        }, onClientError:  { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestUserOnSuccess:^(User * _Nonnull user) {
            if (user.status == UserStatusUnregistered) {
                // Unregistered
            }
        }
        onNoConnection:^void() {
         // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
         // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
          // Handle client error
        }
     ];

Documentation

To register an account for the selected entity, the user needs to fill in a registration form. The identity fields for this entity can be retrieved and populated as follows:

Swift3

    var user = User()
    SDK.getClient.requestEntityDetails(
        onSuccess: { (entityDetails) in
            if let userFieldDefinitions = entityDetails.userFieldDefinitions {
                // Populate the user object for each field
                for field in userFieldDefinitions {
                    if let fieldName = field.name {
                        user[fieldName] = "XXX"
                    }
                }
            }
        }, onClientError: { (error) in
            // Handle client error
        }
    )

ObjC

    User *user = [[User alloc] init];
    [biidCoreSDK.getClient requestEntityDetailsOnSuccess:^(EntityDetails * _Nonnull entityDetails) {
            NSArray<FieldDefinition*> *userFieldDefinitions = entityDetails.userFieldDefinitions;
            // Populate the user object for each field
            for (FieldDefinition *field in userFieldDefinitions) {
                user[field.name] = @"XXX";
            }
        }
        onClientError:^void(NSError * _Nonnull error) {
           // Handle client error
        }
    ];

NB In the above examples no checks are being made on the type of field being populated. In real world code, checks should be made on each field and appropriate values assigned to them accordingly i.e. correctly formatted dates should be assigned to date fields, numbers only to numeric fields etc.

Documentation

The populated User object can then be used to register the user as follows:

Swift3

    SDK.getClient.registerUser(withUser: user,
        onSuccess: {
            // Handle Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token Error
        }, onValidationError: { (error) in
            // Handle field validation Error
        }, onUserAlreadyRegisteredError: { (error) in
            // Handle user already registered Error
        }, onClientError: { (error) in
            // Handle client error
        }
    )

ObjC

    [biidCoreSDK.getClient registerUser:(User * _Nonnull)user
        onSuccess:^{
          // Handle Success
        }
        onNoConnection:^void() {
        // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
        // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
        onUserAlreadyRegisteredError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
        onClientError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
     ];

Documentation

Registration Flow

Certification

For a user to become certified, a Digital Certificate should be issued by a recognised Certification Authority (CA), and a private key should be generated and securely stored in the Secure Enclave of the device.

A registered user on a verified device will have a status of UNCERTIFIED.

A user can be certified in different ways, depending on the Accreditation Level required for certification.

The accreditation process is the process of verifying the user identity, either online or in person, to enable the CA to issue a Digital Certificate for the user.

The biid Platform supports 4 levels of accreditations (Level 1 to Level 4). For each level there are different legal and procedural requirements, needed to verify the user identity.

Different accreditation levels can be defined for different entities and an entity can support multiple accreditation levels, with each level replacing the previous one.

Once an accreditation process is successfully completed, the biid Platform will generate a 16 digit code for the user. This code should be kept safe and secret, in order to protect the user account. This code is known as a DIAC, which stands for Digital Identity Activation Code.

Receipt of a DIAC, either from an API or via email, etc., is a prerequisite for completing the certification process, as a Digital Certificates can only be generated when providing a valid DIAC for the specific accreditation level.

The following paragraphs detail the requirements and processes a user needs to follow in order to get accredited and certified to a specific level.

Level 1 Certification Process

An accreditation Level 1 allows a user to self accredit i.e. registering their details online without the need of an operator reviewing the provided information.

Once the Level 1 accreditation process is complete, the user will be issued a self signed Digital Certificate issue from the biid platform directly (not from external Certificate Authority).

This type of certificate does not provide any legal validity when signing documents but it can still be used to authenticate online and authorise transactions.

NB If a user has a status of UNCERTIFIED and an accreditation Level 1, the biid platform exposes an API to auto-certify the user. In this case the user does not need to perform any manual action such as typing their Level 1 DIAC into a certification screen.

Certifying a user for accreditation Level 1 can be done as follows:

Swift3

    SDK.getClient.certifyUserAtLevel1(
        onSuccess: {
            // Handle Certification Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onUserNotAccreditedError: { (error) in
            // Handle user not accredited error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient SDK.getClient.certifyUserAtLevel1OnSuccess^{
            // Handle Certification Success
        }
        onNoConnection:^void() {
             // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
        }
        onUserNotAccreditedError:^void(NSError * _Nonnull error) {
            // Handle user not accredited error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

On a successful response, the user’s status will be set to CERTIFIED.

Documentation

Level 1 Certification Flow

Level 2 and Level 3 Certification Process

Level 2 and Level 3 accreditations may require the user to provide additional information and proof of identity. An operator of the entity will then have to review and validate this information, before the user can be accredited and a DIAC generated.

The amount of details and documentation required to accredit a user Level 2 or Level 3 may differ substantially, but in general the accreditation process depends on the legal framework the generated biid identity needs to comply with.

For instance, if a Qualified Digital Certificate, according to the European eIDAS Regulation need to be issued, the accreditation process will require the user provides a copy of a valid ID document (e.g. a Passport or national ID card) as well as undertaking an identity verification process that might include biometric verification, face analysis and even a visit to a local checkpoint, to meet an operator in person.

The required accreditation process is always agreed between the organisation that provides the biid service and the Certification Authority that will need to issue Digital Certificates to end users.

Level 2 accreditation (known as Low in the eIDAS Regulation) does not require the user to visit a checkpoint or undertake a video call in order to verify their identity, it does however require that an operator approves the user accreditation request.

Level 3 accreditation (known as Substantial in the eIDAS Regulation) requires that the user either visit in person an authorised checkpoint, undertake a video call with an operator or use a recognised ID verification tool, in order to formally verify their identity.

Full details on the eIDAS Regulation can be found here.

NB Locations at which a user can be accredited can be retrieved using the Checkpoint API: requestCheckpoints, requestNearestCheckpoints and requestCheckpointDetails

Once the accreditation process has been completed and the DIAC received, the user can certify by entering the DIAC with the certifyUser API, as follows:

Swift3

    SDK.getClient.certifyUser(withDIAC: code,
        onSuccess: {
             // Handle Certification Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onValidationError: { (error) in
            // Handle validation error
        }, onUserNotAccreditedError: { (error) in
            // Handle user not accredited error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient certifyUserWithDIAC:code
        onSuccess:^{
            // Handle Certification Success
        }
        onNoConnection:^void() {
           // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
           // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
            // Handle validation error
        }
        onUserNotAccreditedError:^void(NSError * _Nonnull error) {
            // Handle user not accredited error
        }
        onClientError:^void(NSError * _Nonnull error) {
           // Handle client error
        }
    ];

In the background the certifyUser process is made up of the following steps:

  1. An asymmetric key pair is created on the device.
  2. A signing request (CSR) is generated, signed with the private key and sent along with the DIAC, as part of the API request.
  3. If the DIAC and CSR are valid, the CSR is sent off to the appropriate Certification Authority. The certifyRequest will then return a success response and the user status will be set to CERTIFICATE_PENDING.
  4. If the CA issues a signed digital certificate, the next call to requestUser will show the status CERTIFIED. The signed certificate is then retrieved and securely stored on the device.

NB If requestUser is called immediately after a request for certification and the user is successfully certified, then it is likely that the request will return an InvalidTokenError error as the cached token will no longer be valid. This can be resolved by initiating the action detailed in the resolution property of the error. See InvalidTokenError for further details.

Documentation

Level 2 and Level 3 Certification Flow

Level 4 Certification Process

A Level 4 accreditation (known as High in the eIDAS Regulation) is subject to the same requirements of a Level 3 accreditation. However the user may be required to provide some additional information, when registering via the App.

Once the accreditation process has been successfully completed a Level 4 DIAC is issued to the user. Certifying with a Level 4 DIAC allows the user to get a Qualified Digital Certificate on the Cloud i.e. securely stored in a Cloud HSM.

A Qualified Certificate stored in an HSM enables Qualified Electronic Signatures according to the eIDAS regulation.

NB Access to the HSM is secured via a password that the user sets during the certification process. This password is also required when Signing documents for a user accredited to Level 4 (see Document Signing)

Swift3

    SDK.getClient.certifyUserAtLevel4(withDIAC: code, andPassword: password
        onSuccess: {
            // Handle Certification Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onUserNotAccreditedError: { (error) in
            // Handle user not accredited error
        }, onValidationError: { [weak self] (error) in
            // Handle user validation error
        }, onDeviceNotVerified: { (error) in
            // Handle device not verified error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient certifyUserAtLevel4WithDIAC:code password:password
        onSuccess:^{
            // Handle Certification Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onUserNotAccreditedError:^void(NSError * _Nonnull error) {
            // Handle user not accredited error
        }
        onValidationError:^void(NSError * _Nonnull error) {
            // Handle user validation error
        }
        onDeviceNotVerified:^void(NSError * _Nonnull error) {
            // Handle device not verified error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

Level 4 Certification Flow

No matter the accreditation level, once successfully certified, the user will be able to authenticate online, authorise transactions and sign documents.

The legal validity of the digital signature will instead depend on the accreditation level of the user, with Level 4 providing the highest level of validity, comparable to a notarised signature.

Uncertify

In certain circumstances the user may want to uncertify for the current selected entity on the device.

This can be done using the uncertify() API.

Swift3

    SDK.getClient.uncertify(
        onSuccess: {
            // Handle Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token Error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

     [biidCoreSDK.getClient uncertifyOnSuccess:^ {
             // Handle Success
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onClientError:^void(NSError * _Nonnull error) {
             // Handle client error
         }
     ];

After successfully calling uncertify(), subsequent calls to other APIs will result the return of an InvalidTokenError error as the cached token will no longer be valid. This can be resolved by initiating the action detailed in the resolution property of the error. See InvalidTokenError for further details.

At this point the user’s status for this entity will be UNCERTIFIED.

Documentation