Be a Supporter!

Browse Sections


Newgrounds Wiki: Encryption

The Newgrounds.io API is capable of accepting component calls using RC4 or 128-bit AES encryption ciphers, in tandem with Hexadecimal or Base64 string encoding.

Considerations

Using encryption is 100% optional and there are things to consider when deciding what (if any) encryption is right for you.

Security

If you are working in a non-compiled format like HTML5, any encryption keys you use will be completely visible to anyone that knows where to look. Even some compiled formats, like Flash, can be easily de-compiled to extract your encryption key.

For that reason, you can not rely on client-side encryption for any real security. It is important that no matter what encryption settings you chose, you always post to the Newgrounds.io gateway over SSL. This will ensure your calls are posted in the most secure way possible.

Obfuscation

The primary reason for using encryption is obfuscating calls that can post data to a user account (such as posting high scores).

Even when posting over SSL, a local user can see exactly what data is being posted to the gateway using any network traffic inspector. If a user captures the raw JSON data for posting a high score, it's very easy for them to edit the score value and post it again with an ill-gotten value.

If you have encrypted your call first, the text is no longer something simple to edit. While this makes it harder for users to 'hack' your scoreboards, there is no guaranteed way to stop the most determined users. In these cases, you need to moderate your scoreboards, and delete obvious cheaters.

Cipher/Encoding Libraries

While AES encryption is certainly harder to crack than RC4, and Base64 encoding is much more compact than Hexadecimal, you may be working in a platform that simply can not support them.

Before you select an encryption cipher and string encoder, see what libraries are available for your development platform. Many modern platforms have native cryptography and encoding functions that will most likely be faster than any 3rd party library.

Encrypting a Call

Let's start with a sample input object converted to a JSON string:

{

    "app_id":"123456:AbcXyz",

    "session_id":"abcdefghijklmnopqrstuvwxyz123456",

    "call": {

        "component": "Scoreboard.post",

        "parameters": {

            "id":98765,

            "value":80085

        }

    }

}


In this example, you can see we are posting a high score. To do this with encryption, we need to encrypt the inner 'call' object:

{

    "component": "Scoreboard.post",

    "parameters": {

        "id":98765,

        "value":80085

    }

}


Note: This call object has already been converted to a JSON string. One of the most common problems people have when encrypting calls is that they try encrypting a native object without first encoding it to JSON.

The next step is to encrypt our string with our cipher (you will need your unique encryption key for this part). This will result in some type of binary value (such as a byteArray).

Next, we need to convert these bytes to a string (using whatever string encoding you chose).

In this example, we used Base64, and our encrypted call looks like this:

=jkhDH7ysfkjdh098Ckjlksx8908lksjdf90sdojjLKJDSF79098jkhDH7ysfkjdh098Ckjlksx8908lksjdf90sdojjLKJDSF79098


Note: Some older encryption libraries automatically encode encrypted data to a hex string. If this is the case, you should make sure your encoder is set to hex and you can skip the above step.

Now that we have our encrypted call string, we need to put it back in our 'input' object. We do this by making ANOTHER call object and putting our encrypted string in a 'secure' property rather than using the 'component' and 'parameters' properties:

{

    "app_id":"123456:AbcXyz",

    "session_id":"abcdefghijklmnopqrstuvwxyz123456",

    "call": {

        "secure": "=jkhDH7ysfkjdh098Ckjlksx8908lksjdf90sdojjLKJDSF79098jkhDH7ysfkjdh098Ckjlksx8908lksjdf90sdojjLKJDSF79098"

    }

}

Cipher Notes

AES adds an extra layer of security by using an Initialization Vector (or IV for short). For 128 bit encryption, this IV should be a random, 32-bit binary value.

In order for the server to decrypt your AES string, you will need to prefix your IV bytes to your encrypted binary data before encoding it to a string.

RC4 encryption does not use any kind of IV (wich is why it is less secure). You will not need to modify your encrypted data at all for RC4 strings to be decrypted by the server.