On May 8, we released a security update to Amazon GameOn, a set of REST APIs that help you build cross-platform competitions into your games. One of the developer requests we addressed in this update is to provide both a standard and an advanced security model.  

Standard vs. advanced security model

The new standard security model authenticates players using a simple exchange of a player token. The network traffic between the device and the Amazon servers is protected with Transport Layer Security (TLS).

The advanced security model adds data encryption for sensitive data in the exchange between the client and server. The advanced security model uses public/private key encryption to help secure player registration, authentication, and prize claim information.

For both models, you will need to supply your API key whenever you make a call, and you’ll need to have your GameID to identify your game.

Why have two security models? Some developers have told us that standard security is their preferred method for accessing GameOn. Others have told us that they want to use standard security while in development, but they want to launch with advanced security.

Here are the differences between the standard and advanced models to help you choose which is right for you.

Standard security:

• Advanced Setup – Not required
• Player Registration and Authentication – Communication secured with TLS
• PrizeInfo – Communication secured with TLS

Advanced security:

• Advanced Setup – Creation of a public/private key pair required
• Player Registration and Authentication – Communication secured with TLS and content is encrypted
• Prizeinfo  – Communication secured with TLS and prize info is encrypted

The standard GameOn security model

Using the standard security model looks like this:

1. Register your player: Register your player by providing the Game API key in the header of the Register Player method. The Register Player response will include a playerToken that you store for long term use, sending it in all Authenticate Player requests for that player.

2. Authenticate your player: You call Authenticate Player and send the playerToken to create a session for your player. You will get a session API key and a session ID in the response. Hang on to these, you’ll need these for future API requests.

3. Flow through competition takes as per the listed workflows using sessionApi and sessionId in the API calls.

Here is a sample of the Authenticate Player request body:

{

  "advertisingId" : "54d8fd8d-e349-49d8-902c-0558365ac22b",

  "payload" : "<player token>",

  "playerName" : "hunkdory",

  "devicePushNotificationToken" : "392340e57e4a7c646326b1cf96931d97f22ab163f23b3d3605fc5698d3788xx9",

  "deviceOSType" : "iOS",

  "appBuildType" : "development"

}

The GameOn advanced security model

Advanced security registers and authenticates players with additional security for player authorization (in addition to the API key) by using an encrypted player token in the exchange between the client and server. Here is how that works:

1. Generate encryption key pair: Step one is to generate the public/private key pair that will be used to pass encrypted player information to GameOn, and to receive encrypted information back from the GameOn service. We’ll call these the client keys and suggest each player have their own unique set. To create these keys, it’s probably best to use a tool like Bouncy Castle to help make this easy.

2. Prepare to send GameOn the client public key: You’ll need to send the client public key to GameOn, so GameOn can use it to encrypt sensitive information sent in response to future API requests.

3. Encrypt the client public key: GameOn provides you with a public key which is used to encrypt the client public key before sending it. This GameOn public key can be found in the GameOn admin console, and is provided during registration. It is unique to each registered game.

4. Send the encrypted client public key: Every time a player needs to register with GameOn, Register Player will conduct the key exchange, taking the client public key and using that to encrypt and send an encrypted Player Token in the response. For a diagram showing the workflow in more detail, click here.

5. Decrypt the Encrypted Player Token: This token is encrypted with the client public key and should be decrypted with the client private key (which is only known to you).

6. Now you have a Player Token: When you send the Player Token back to GameOn (e.g. for authentication), you’ll encrypt it with the GameOn public key.

In the advanced model, the only other time (besides Player Registration and Authentication) where you’ll need to use your key pair is when you get Prize Info from claiming or fulfilling a prize. That will come encrypted with the client public key provided to GameOn when the player was registered.

Choose your model when you register your game

You make the choice between standard and advanced security when you register your game in the GameOn console and it is not possible to switch security modes for your game once registered. To develop with one model and release with another, you will need to create two games in the GameOn console; one with standard and one with advanced security. Here is how that works.
 

Developing in standard security and releasing with advanced security

If you have developed the game using standard security, and you wish to release with advanced security, use the GameOn console to register a new game with the same name and select the advanced security model option. A new entry will be created in your GameOn console with new keys that you must use in your code for the new security mode. Because this is a new game entry in GameOn, user data from the first game will not be available in the new game. Quick tip: remember to switch all the keys to match the new game.

More help

For more details about the API parameters and responses, please see the GameOn API reference. We also have some cryptography code samples you can download. If you still want more help, you can check out our Knowledge Base or ping our GameOn support forum.

Remember, GameOn is free until June 1! Some developers have been able to set up competitions in their game with GameOn in as little as one day. Integrate today to take full advantage of our launch offer. You can also learn more about how to integrate competitive play into your game by watching this webinar now.

• @MikeFHines
• Facebook/MikeFHines