Game API Advanced Security
The Game API provides a choice of standard or advanced security. Advanced security is more complex than standard security, but provides a higher level of security. Each player is assigned a set of cryptography keys, to ensure that encrypted sensitive data (such as prizeInfo) can only be decrypted by the specific player. Advanced security also provides additional security for player authorization (in addition to the API key) by using an encrypting player token in the exchange between the client and server.
Register a player with Advanced Security
With the advanced security option, each player has their own client keys to minimize the risk that a player could decrypt sensitive information belonging to another player. Therefore, to authenticate a player, you must have three key files in .pem format:
- Client Public Key
- Client Private Key
- Game Public Key
You can find the value of the game public key in the Game Settings tab of the Leaderboards and Tournaments Console (see figure above). You must generate the client public and private keys. See the notes below for information about generating these keys.
When you register a new player, the system adds the player (and their device) to Amazon Leaderboards and Tournaments Service, conducts a key exchange, and returns an encrypted player token.
Purpose
When you register a game, the system assigns a key pair to the game. You use the game keys to securely provide the client public key to the Amazon Leaderboards and Tournaments Service. The Leaderboards and Tournaments service uses client public key to encrypt sensitive information in future responses.
Request
The Register Player request initiates the key exchange. The game app encrypts the client Public Key against the game Public Key and uses the resulting encrypted client Public Key in the body of the request (encryptedPayload field).
Response
The successful response message contains an encrypted player token. The player token is encrypted against the client Public Key that you provided in the request. You need to decrypt this token using the client Private Key, then re-encrypt the token using the game Public Key. Store this token for long term use. You will send it in all future authenticate calls for the player.
Generating player keys
The public game key is provided by Leaderboards and Tournaments in base64 encoded DER format. This is also known as PEM format but without the headers. You can add headers/footers around the key to create a PEM format key:
-----BEGIN PUBLIC KEY-----
[KEY TEXT]
-----END PUBLIC KEY-----
Many openssl implementations have the “public exponent” for the key generation as e=3, which works. However, an exponent of 65537 is considered better because it is slightly faster in implementation (see https://en.wikipedia.org/wiki/Coppersmith%27s_attack).
Use “PKCS1_v1_5” padding format for formatting the public game key. As mentioned below, openSSL recommends OAEP for new applications (and other libraries have it as default) so developers should be advised. The payload expected by the Leaderboards and Tournaments servers is a base64-encoded DER format public key, not just the straight DER binary format (also equivalent to a PEM format key without the headers). The encrypted output is again encoded in base64 for the REST call.
Flow Diagram
