pay-publicauth

Payments Public API Authentication Service

API Keys

Anatomy of an api key:

api_live_u3tl8gajo9paj0xki31jm1psr3v21m5urh50zoa7a262w4ntzoo6cqhu82
`-------`'-----------------------------------'
 PREFIX           RANDOM BASE32 STRING
`--------------------------------------------'`------------------------'
                   TOKEN                        CHECKSUM

API KEY generation algorithm:

1. TOKEN := 130 bit random number and encode to base32, optionally prefixed with a human readable string based on the token account type
2. CHECKSUM := hmacSha1(concat(TOKEN, TOKEN_API_HMAC_SECRET))
3. API_KEY := concat(TOKEN, CHECKSUM)
4. TOKEN_HASH := bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT)
5. store TOKEN_HASH in database
6. return API_KEY

API KEY validation algorithm:

1. API_KEY is provided as Authorization: Bearer someverylongstringandachecksum
2. Extract API_KEY := someverylongstringandachecksum
3. Split the string at a known character index based on the length of the sha1 suffix ie. TOKEN := someverylongstring ACTUAL_CHECKSUM := andachecksum
4. verify that hmacsha1(concat(TOKEN, TOKEN_API_HMAC_SECRET)) == ACTUAL_CHECKSUM
5. TOKEN_HASH := bcrypt(TOKEN, TOKEN_DB_BCRYPT_SALT)
6. lookup TOKEN_HASH in database; return true iff found

Environment variables

Integration tests

To run the integration tests, the DOCKER_HOST and DOCKER_CERT_PATH environment variables must be set up correctly. On OS X the environment can be set up with:

    eval $(boot2docker shellinit)
    eval $(docker-machine env <virtual-machine-name>)

The command to run the integration tests is:

    mvn test

API Specification

The API Specification provides more detail on the paths and operations including examples.

Licence

MIT License

Responsible Disclosure

GOV.UK Pay aims to stay secure for everyone. If you are a security researcher and have discovered a security vulnerability in this code, we appreciate your help in disclosing it to us in a responsible manner. We will give appropriate credit to those reporting confirmed issues. Please e-mail [email protected] with details of any issue you find, we aim to reply quickly.