Note: This document refers to the encryption process used by the version 2 API. For version 3 see Newgrounds.io

Prerequisites

In order to help prevent abuse, several of the Newgrounds API functions allow the use of encryption.

Our encryption process uses a combination of JSON, RC4, MD5 and BaseN encoding. These methods were chosen because they allowed us to use the barest character set, and therefor be widely compatible across different platforms.

Every game project gets a unique encryption key. If one game is compromised, any problems will be contained to that game.

Every secure packet will also contain a randomly generated seed/salt. This can be any random string of alphanumeric text, and should be randomly generated for ever individual secure packet.

Test Data

For the sake of this tutorial we will be simulating an unlockMedal command for a made-up game. The command we want to send will have the following data:

• command_id = "unlockMedal"
• medal_id = 321
• session_id = "R4ndOmSe551onStR1nGzz"
• publisher_id = 1
• seed = "s0m3r4ND0mSe3d"

And we will be using the following encryption key: "a5up3RS3cR3tK3y"

Encoding Steps

Step 1: Hash the seed

Before we encrypt our data we need to get a 32-character MD5 hash of our seed so the server can validate it.

The hash of our sample seed should be:

c63bd6829516b6d7cbaded7da1afe7e4

Step 2: JSON Encoding

Now we can convert our data to a JSON encoded string. We use JSON because it is widely supported, and is significantly smaller, byte-wise, than XML.

Our encoded object should look like this:

{"publisher_id":1,"session_id":"R4ndOmSe551onStR1nGzz","command_id":"unlockMedal","medal_id":321,"seed":"s0m3r4ND0mSe3d"}

Note: The order in which JSON encodes object properties may vary between development environments. When testing your encryption, it would be wise to copy the above JSON string directly!

Step 3: Encrypt the packet

Now that our data is a single string, we can encrypt it with our RC4 key. If your RC4 library encrypts as binary, you will need to convert the result to hex.

Our sample data should now look like this:

2b44fdf6627735684a2a95ef8dcb6c5a43a6befefd665a8823bc09f6d0c2a2dff7beb87b60e45e415d540a19e4bab51f8a8a77c9025a7755443c8d590cd660c599cfd2a21a3f5709d052316a14883e5688f0e4c2ce22f3888d6bfc417418fe3a77be8337b36e4a4dbf32f395a2a3d9c12eb5884f8e0af0667d

Step 4: Concat the MD5 and RC4 strings

In this step we simply do MD5_hash + RC4_string. The result should be:

c63bd6829516b6d7cbaded7da1afe7e42b44fdf6627735684a2a95ef8dcb6c5a43a6befefd665a8823bc09f6d0c2a2dff7beb87b60e45e415d540a19e4bab51f8a8a77c9025a7755443c8d590cd660c599cfd2a21a3f5709d052316a14883e5688f0e4c2ce22f3888d6bfc417418fe3a77be8337b36e4a4dbf32f395a2a3d9c12eb5884f8e0af0667d

Later in this tutorial I will refer to this string as "the encrypted string".

Step 5: Compress the string with a custom BaseN radix

This is where the encryption process gets a little complicated. To support old platforms, we have to keep all these packets as strings, and we have to work with a limited character set. In order to compress our final data, we use a custom radix with a BaseN algorithm.

BaseN is simply a way to use a custom base to encode base 10 numbers. We could use the following 16-character radix to encode numbers to Base16, aka hexadecimal: "0123456789ABCDEF". Most programming languages have some kind of convert-to-base library available.

We will be using the following 79 character radix:

/g8236klvBQ#&|;Zb*7CEA59%s`Oue1wziFp$rDVY@TKxUPWytSaGHJ>dmoMR^<0~4qNLhc(I+fjn)X

This radix contains 79 characters that have proven to be multi-platform-friendly. They are in a random order to add additional obfuscation to the compressed packets we will be working with.

If we use our radix to convert the number 123456 to a string, the result would be:

C^o

Because we are working with a very long encryption string, we will actually be converting it in chunks. Essentially we will be taking 6 hex characters, converting them to an integer value, and converting that to a BaseN string. Because we need to be able to decode these chunks, they will each have to be 4 characters long.

In the previous example, 123456 only produced 3 characters. To convert it to 4 characters we simply add the very first character from our radix (which represents zero), to the beginning of our BaseN string. The four-character version of 123456 would be:

/C^o

As mentioned above, we are going to crunch our encrypted string 6 characters at a time. The first 6 characters of our string are "c63bd6". We need to convert this to a base10 number first. In this case, the number is 12991446.

When we convert 12991446 to a BaseN string we end up with:

`OtJ

We will do this for every 6 chars until we get to the end of our encrypted string. The final, compressed result will be:

`OtJ*u7|%%/j9BwQADNm1s)kiM4@Zq<NBN~#wq@t;w0g5&)riHI<7lPAgst+sLN9z+TmbwP2&@Ru#|DU1wN(3ZbWZIN&&gnnB6Tj#qv9&LZ/Otsr2Dt6g%3ZkxcG7vHr7b/ksctDze%I;Of1ZFQ6lRn6*F(B;G#FszM(Cc9(ufyy%QC~7hU`3bB

Step 6: Record the length of tail characters

When our compressed string gets decoded on our servers, it will convert our 4-character chunks back into 6-character hex values. To deal with these, we will add a single integer from 0-5 at the start of our new, compressed string.

The value of this integer should be calculated something like this:

tail_length = encrypted_string.length % 6

In this example, our overflow length is 4. So, our final encoded string will be:

4`OtJ*u7|%%/j9BwQADNm1s)kiM4@Zq<NBN~#wq@t;w0g5&)riHI<7lPAgst+sLN9z+TmbwP2&@Ru#|DU1wN(3ZbWZIN&&gnnB6Tj#qv9&LZ/Otsr2Dt6g%3ZkxcG7vHr7b/ksctDze%I;Of1ZFQ6lRn6*F(B;G#FszM(Cc9(ufyy%QC~7hU`3bB

This value is what you will send to our servers.