Sanctum Frequency Asked Questions

What happens if starting a read or update operation fails?

If starting a read or update process fails you can start the same process using the same credentials which will clean up the previous operation. If this is retried 5 consecutive times without acknowledging a successful response then the vault will be locked.

What happens if ending a read or update operation fails?

Ending a read or update is simply acknowledging that the start operation was successful. If this operation happens to fail it should be retried due to the possibility that the user's outbound request may not have reached the system due to a network outage.

What happens if I lose my transaction token?

You can start the read or update process again using the same credentials (not the new ones given in the response). This will start the read or update process, however, if this is the fifth consecutive call to start this process without acknowledging the response then the vault will be locked and require an administrator to unlock it.

What happens if my transaction token expires?

After this expiry time you will be able to start the read or update process again using the same credentials as before (not the new ones given in the response).

What happens when there are failed attempts to access a vault?

To guard against brute force attacks, any failed attempts to access a vault (read/update/delete operations) will log a failed access attempt within Sanctum. Sanctum accumulates these failed attempts and will lock a vault if there are 3 consecutive failed access attempts.

How does an autoLockDate field affect a vault?

By default, all vaults created will have an autoLockDate. The autoLockDate will trigger the vault to be locked after a 1-year period of non-use. This means that a vault must not be accessed via a get-start or update-start operation for a period of 1 year to be automatically locked. If a successful get-start or update-start operation has been done against a vault, that vault's autoLockDate will be updated to 1 year in the future of that operation.

What is an external ref?

The externalRef field included in most of the requests exists so that you can track any operation or sequence of operations via your own reference.

Why do I need to specify a username?

The username field is used as a logical grouping of vaults. This username can be an identifier for the end user that the vault is associated with or it could be the identifier of an external system that created the vault. This will depend on the implementation of the application consuming the Sanctum API.

How does the maxUsage field affect a vault?

The maxusage field assigns a maximum amount of uses to a vault. If a vault has a specified a maxUsage value, this value will only be reduced by 1 when a successful get-end operation is executed.

What is a hashed pin?

A hashed pin is a base64 encoded SHA-512 hash of your pin combined with a 512 bit randomly generated salt. Haventec utilises a pin length of 4 digits, however any length may be used. In psuedocode, the hashed pin is calculated as follows for the first interaction:

        pin = enterPin();
        salt = generate512BitSalt();
        hashedPin = SHA512(salt + pin);
        storeSaltInSecureStore(salt);

    

When the user is required to authorise an action with a hashed pin:

        pin = enterPin();
        salt = getsaltFromSecureStore();
        hashedPin = SHA512(salt + pin);

    

This hashing process should occur on the client device (i.e. the browser or mobile application). The purpose of hashing the pin is that the Haventec servers will be unable to view the raw pin value and maintain the privacy of your pin.

For online vaults being stored on a browser, Haventec recommends the Stanford Javascript Cryptography Library (https://github.com/bitwiseshiftleft/sjcl) to calculate these hashes. Provided below is an Angular 2 service class showing the generation and calculation of the hash:

        import * as sjcl from "sjcl512";

        export class HT_CryptoService {

            public static getBase64Hash512SaltedPin(pin: string, salt: string): string {
                let hash512 = new sjcl.hash.sha512();
                hash512.update(JSON.parse(salt));
                hash512.update(pin);
                let hashed = hash512.finalize();

                return sjcl.codec.base64.fromBits(hashed);
            }

            public static generateSalt(): Array<number>[128] {
                return sjcl.random.randomWords(128);
            }

            public static saltToString(salt: Array<number>[128]): string {
                return (JSON.stringify(salt));
            }

            public static saltFromString(salt: string): Array<number>[128] {
                return (JSON.parse(salt));
            }

        }
    

Haventec recommends that the salt is stored in LocalStorage in browser scenarios. Provided below is an Angular 2 service class storing and retrieving the salt from LocalStorage. The storage of the salt should be namespaced based on the username to allow a browser to store the online vaults of several users.

    export class HT_DataService {

        public static storeSalt(username: string, salt: string): void {
            localStorage.setItem('ht_' + username.toLowerCase() + '_salt', salt);
        }

        public static getSalt(username: string) {
            return localStorage.getItem('ht_' + username.toLowerCase() + '_salt');
        }

        public static saltExists(username: string): boolean {
            return (localStorage.getItem('ht_' + username.toLowerCase() + '_salt') != null)
        }
    }


    

What is the Luhn algorithm?

The Luhn algorithm is a checksum used to validate a credit card number against accidental errors. All the Haventec credit card vaults validate the PAN passes the Luhn check. For more information, please read the reference here.

What is vault metadata?

Vault metadata is non-sensitive information to be associated with a vault. Haventec provides some default metadata such as maxUsage or autoLockDate. Users may define custom metadata upon vault creation to support their business logic.

The example below, will create 2 metadata tags for the vault, "examplekey" and "anotherExampleKey" with the values "exampleValue" and "anotherValue" respectively.

                {
                    ...
                    "metadata": {
                        "examplekey": "exampleValue",
                        "anotherExampleKey": "anotherValue"
                    }
                    ...
                }
            

To retreive a vault's metadata call the vault information endpoint; to retreive an offline generic vault's metadata call
GET /Sanctum/v1-2/vault/generic/offline/{{vaultUuid}}/info
There is currently a limit of 50 custom metadata tags per vault.