Data Encryption

Module overview

This section is an overview of the encryption system with the REST API encryption module. To implement the encryption API, use the module based on the following specifications.

The encryption module provides the encryption/decryption functions for secure communication.

• This system encrypts and decrypts string format parameters which need to be secretly communicated with the standard 2048/1024-bit RSA RFC 3447 external link and 128-bit AES-CBC algorithm RFC 3602 external link.
• This system DOES NOT encrypt the entire communication, only the specific parameters. This means the communication takes place in the same way as any normal communication about JSON protocols.
• This system exists to prevent the interception of the communication. It is not a countermeasure for illegal access or impersonation.

Encryption flow

The encryption flow is shown in the following figure.

This encryption system is hybrid, with a public key and a common key. Secret data is encrypted by the AES common key, and the RSA public key is used to share the common key safely between the client and the server. During initialization, the server generates the RSA public/private keys. The client receives the RSA public key, and generates the AES common key and encrypts it with the RSA public key. After initializing, the client can send and receive the encrypted data using both keys.

The client should generate a distinct Initialization Vector (IV) for each message.

APIs which use encryption have the parameters of encrypted data and encrypted keys. When an encrypted API is called by the client, the server decrypts the common key with the RSA private key which was generated by the server, and decrypts the data with the common key.

The procedure to receive secret data from the server is shown in the following figure.

The initializing process is the same. In both cases, even with the public key, the encrypted data and encrypted key are communicated. Even if they are intercepted, a third party cannot get the original data.

API definition

getPubicKey API in encryption service is a common API for this encryption system.

Other APIs which send or get encrypted parameters have an “encKey” element and at least one encrypted data element. Even if an API has multiple encrypted elements, “encKey” is common and must be included in params.

JSON Example: send

{
    "method":"sendSecretData",
    "params":[
        {
            "secretData1":"G9KgQDustrxplKFcy9fnVQ==",
            "secretData2":"At2gQDgst6xplKFcy9fnVQ==",
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[],
    "id":1
}

JSON Example: get

{
    "method":"getSecretData",
    "params":[
        {
            "encKey":"hCkxUu4WydqDwrlq+PsSSxBaIVbPFNeCU7XYgBC9bVmXvcTORXMdY5FeSr3LYu9WywFbh1WwTBW/S+xTPHZQXhQMUsWEFQwUSldm5xK8vhOcdzGe8kdrixAL6zL9qx6rioR95gF50FO1RRVS7jdsabPvHK5gXZHM9B2h24QKON1FeTkYVGKcf8J3JJp9gEWeNYG2bfMSvnS9qrn2bLXgAX71vwEz7Btm/+qmX7/nsrL5QGBdbgxUlK7q5JzZxOdDuh592lfdEoMIgFR144XAnhfqyCcuZLJ/60VjOpREQ17vTj6+NNVrSOIq4eHnBlB7SfFWM/CBa+rCFmYAzmm3VQ=="
        }
    ],
    "id":1,
    "version":"1.0"
}
{
    "result":[
        {
           "secretData":"G9KgQDustrxplKFcy9fnVQ=="
        }
    ],
    "id":1
}

Implementation guide

During initialization, the server generates an RSA public/private key pair. Since it takes a long time to generate a large key, define the bit size and management way of the RSA key based on the policy of each system. During initialization, the client gets the server public key by calling getPublicKey and creates a common key which it encrypts to “encKey”. After that, the client calls encryption APIs with these keys.

To maintain consistency between the server’s private key and the client’s public key, the server should not change the key after initialization. The client can use the same common key on different API calls. Also, if necessary, the client can recreate the common key and “encKey” to improve security.

When the encryption module fails to encrypt or decrypt because of an illegal state such as key inconsistency, the server returns the 40002 Encryption Failed error. If the client receives this error, the client goes back to initialization procedure.

The size of encryption keys can be defined in each system. You should use a key that is large enough for security.

Informative Reference

1. IETF RFC 3447, Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1
   http://www.ietf.org/rfc/rfc3447.txt
2. IETF RFC 3602, The AES-CBC Cipher Algorithm and Its Use with IPsec
   http://www.ietf.org/rfc/rfc3602.txt