Skip to content

Server API Signature and Encryption ​

Preface ​

This solution provides a complete authentication system for interface communication between the APP server and SUD OP SVR. It uses a dual security mechanism of data encryption + digital signature to effectively prevent interface data from being leaked or tampered with during transmission, while also providing non-repudiation of operations. The APP server can configure and manage keys and public keys on the "API Security Configuration Page" of the SUD OpenPaaS management console, thereby ensuring the security of interface interactions between the server and SUD OP SVR.

In this document, "APP server" corresponds to the APP SVR defined in Server Overview; after "SUD OpenPaaS certificate" first appears, it may also be referred to simply as "platform certificate" in the body text.

1. Core Concepts ​

1.1 Service Signing and Verification ​

When the APP server calls a SUD OpenPaaS API (such as retrieving user information or login authentication), it must generate a request signature using its own app private key (RSASSA-PSS is the signature algorithm); after receiving the request, SUD OP SVR verifies the signature using the app public key configured by the APP server to validate the authenticity and integrity of the request.

When SUD OP SVR initiates a callback to the APP server, the APP server must verify the callback using the public key in the SUD OpenPaaS certificate to validate the authenticity of the platform callback. The callback direction uses exactly the same keys as this document, with the signer and verifier swapped; for request headers, how to derive urlpath, and how to encrypt and sign responses, see Callback Signature and Encryption.

Core Term Definitions ​

  • App public key: Generated online by the APP server via the SUD OpenPaaS management console and stored on the API Security Configuration Page, used by SUD OP SVR to verify interface calls from the APP server.
  • App private key: Generated and downloaded by the APP server via the SUD OpenPaaS management console, kept solely by the APP server, and used to generate the digital signature of interface requests; its security must be strictly guaranteed.
  • SUD OpenPaaS certificate: The official certificate containing SUD OpenPaaS public key information, used by the APP server to verify the signature of SUD OP SVR interface responses/callbacks. It can be downloaded from the API Security Configuration Page after the app public key is configured.

1.2 Interface Content Encryption ​

SUD OP SVR supports encrypting the interface request content and response content using the AES-256-GCM algorithm. After encryption, the interface message is transmitted over the network in ciphertext form, greatly improving data transmission security.

Execution order of encryption and signing: The APP server must first encrypt the request plaintext to obtain the ciphertext, then generate a digital signature over the ciphertext. Signing first and encrypting afterward is prohibited.

2. Key Configuration ​

The APP server must complete the online generation and configuration of the symmetric key and asymmetric key pair in the SUD OpenPaaS management console, and download the SUD OpenPaaS certificate.

2.1 Enter the API Security Configuration Page ​

After the APP server logs into the SUD OpenPaaS management console, enter the "API Security Configuration Page" to perform the operations.

2.2 Configure the Symmetric Key for Interface Content Encryption ​

The symmetric key is used for encrypting and decrypting interface request/response content using the AES-256-GCM algorithm:

  • On the API Security Configuration Page, click to generate a symmetric key; the system will generate a 43-character Base64 string that decodes to 32 bytes;
  • After configuration, you can download the key (it can be downloaded only once) and must store it securely locally.

2.3 Configure the App Asymmetric Key Pair ​

The asymmetric key pair is used for signing and verifying interface requests. RSASSA-PSS is the signature algorithm, so the key pair must be an RSA key pair:

  • On the API Security Configuration Page, generate the app asymmetric key pair online (after generation, the app public key is automatically saved in the management console);
  • After the key pair is generated, you must immediately download the app private key (it can be downloaded only once), and after downloading, you must strictly keep it confidential on the APP server.

2.4 Obtain the SUD OpenPaaS Certificate ​

After the app keys are configured, you can download the SUD OpenPaaS certificate on the API Security Configuration Page, and you can also view the serial number (SN) and basic information of the configured keys.

3. API Request Processing Specification ​

When the APP server calls open APIs, it must process API requests according to the following specification: first encrypt the request plaintext to generate the ciphertext, then generate a signature over the ciphertext, and finally send the encryption parameters, signature information, and standard request headers together to SUD OP SVR. Requests that are not encrypted, not signed, or fail signature verification are rejected by SUD OP SVR.

3.1 Request Plaintext Encryption (AES-256-GCM) ​

3.1.1 Requirements for the Encrypted Request Parameters ​

  • Request parameters

    ParameterRequiredNotes
    ivYesInitialization vector; 16 characters after Base64 encoding (12 bytes of random data after decoding)
    dataYesThe encrypted request ciphertext, Base64 encoded
    authtagYesThe authentication information output by the GCM block mode, used to verify ciphertext integrity, Base64 encoded
  • GCM mode Additional Authenticated Data (AAD)

    You must set the Additional Authenticated Data (AAD) to authenticate the ciphertext. The AAD format is uniformly specified as: urlpath|appid|timestamp|sn (each field separated by a vertical bar |)

    FieldDescription
    urlpathThe URL path of the current request API, including the URL protocol, excluding URL parameters (URL Query)
    appidThe unique app identifier AppId
    timestampThe timestamp (in seconds) of the encryption operation; must be exactly the same as the value of the request header X-Sud-Timestamp
    snThe symmetric key serial number used for this encryption, obtained from the API Security Configuration Page
  • Request plaintext format requirements

    The request plaintext to be encrypted must be in JSON format, containing all parameters of the original API, and must add three security fields:

    ParameterTypeRequiredNotes
    <original API business fields>Original typeYesAll parameters required by the original API, flattened to the JSON root by their original field names (not nested), excluding AccessToken
    _nstringYesAnti-replay random string (Nonce); a 16-32 byte Base64 random string is recommended
    _appidstringYesThe unique app identifier AppId; must match the appid in the AAD
    _timestampnumberYesThe timestamp (in seconds) of the encryption operation; must match the timestamp in the AAD

3.1.2 Calculation Example ​

The following example uses the AES-256-GCM algorithm to demonstrate a complete request encryption process.

  • Prepare the key and context information

    • Request path (urlpath): https://api.sud.com/v1/game/login
    • Symmetric key serial number (sn): key_v1
    • Symmetric key content (key): otUpngOjU+nVQaWJIC3D/yMLV17RKaP6t4Ot9tbnzLY=
    • Current timestamp (timestamp): 1710500000
    • App ID (appid): app_10010
  • Prepare the original business data

    json
    {
        "appid": "app_10010",
        "sud_uid": "user_889900",
        "scene": 0,
        "client_ip": "127.0.0.1"
    }
  • Generate the IV and concatenate the AAD

    Generate 12 bytes of random data and Base64-encode it as the iv:

    text
    base64_encode(iv) = fmW/zNxXlytUZBgj

    Strictly concatenate the AAD in the urlpath|appid|timestamp|sn format:

    text
    aad = https://api.sud.com/v1/game/login|app_10010|1710500000|key_v1
  • Assemble the final plaintext to be encrypted (with security fields added)

    json
    {
        "_appid": "app_10010",
        "_n": "o89QaPVsRu1yppIZzvSZc4",
        "_timestamp": 1710500000,
        "appid": "app_10010",
        "client_ip": "127.0.0.1",
        "scene": 0,
        "sud_uid": "user_889900"
    }
  • Compress the JSON and perform encryption

    Compress the above JSON into a string with no extra spaces or line breaks (as the actual plaintext):

    json
    {"_appid":"app_10010","_n":"o89QaPVsRu1yppIZzvSZc4","_timestamp":1710500000,"appid":"app_10010","client_ip":"127.0.0.1","scene":0,"sud_uid":"user_889900"}

    Note: AES-GCM encrypts a byte stream, so a different JSON field order will produce completely different ciphertext. For ease of cross-language comparison testing, the examples in this document are uniformly ordered by field name in ascending lexicographic order; production implementations are not required to use lexicographic order, but must ensure that the plaintext bytes used for encryption are exactly identical to the bytes of the final HTTP Body sent (i.e., serialize into a string first, then encrypt that same string and send it as the Body).

    Pass plaintext, key, iv, and aad to perform AES-256-GCM encryption, then extract the ciphertext and authentication tag respectively and Base64-encode them:

    text
    base64_encode(enc_data) = OIDVdrPtSPF/0e2CTXCV2vVNPbVJdJlP2WaTMQnoYLh5iCrrSNfQFh25EnStDMf0hLlVNBCZQtf9NaV0m4aRA4AAYIO7oR/Ge+4yY4EmZp5EVPB42xjScgMx5X3D4VdLCfynXIUKUtZHZvk1zmLVE3RauzJgiM1BB1C  // Example truncated; actual length depends on plaintext length
    base64_encode(authtag) = 5qeM/2vZv+6KtScN94IpMg==
  • Final request ciphertext used as the HTTP Body

    json
    {
        "iv": "fmW/zNxXlytUZBgj",
        "data": "OIDVdrPtSPF/0e2CTXCV2vVNPbVJdJlP2WaTMQnoYLh5iCrrSNfQFh25EnStDMf0hLlVNBCZQtf9NaV0m4aRA4AAYIO7oR/Ge+4yY4EmZp5EVPB42xjScgMx5X3D4VdLCfynXIUKUtZHZvk1zmLVE3RauzJgiM1BB1C",
        "authtag": "5qeM/2vZv+6KtScN94IpMg=="
    }

3.2 Digital Signature of the Encrypted Request ​

3.2.1 Parameters ​

  • Request parameters

    In an API request, the APP server must sign the request content using its own private key and pass the signature to SUD OP SVR via HTTP headers.

    Header NameRequiredDescription
    X-Sud-AppIdYesThe AppId filled in by the APP server
    X-Sud-TimestampYesThe timestamp (in seconds) at signing time; must match the one used during encryption
    X-Sud-SignatureYesThe signature string (Base64 encoded)
  • String-to-Sign concatenation specification

    To completely eliminate line-break ambiguity during verification, the string-to-sign strictly follows the concatenation formula below: String-to-Sign = urlpath + "\n" + appid + "\n" + timestamp + "\n" + data

    Parameter in the SignatureDescription
    urlpathThe URL of the current request API, excluding URL parameters (URL Query), and must include the HTTP protocol header.
    appidThe AppId of the current call (i.e., the value of X-Sud-AppId).
    timestampThe timestamp at signing time (i.e., the value of X-Sud-Timestamp).
    dataThe raw string of the HTTP request Body, i.e., the final JSON string generated in 3.1.2 (if the request has no Body, this item is empty).

    Note: RSASSA-PSS is the signature algorithm. The parameters must be SHA-256 / MGF1-SHA-256 / salt length = 32 to match the platform.

3.2.2 Calculation Example ​

Continuing from the encryption result of 3.1.2, we sign the request data of the login authentication interface.

  • Private key information (RSASSA-PSS, SHA-256 / MGF1-SHA-256 / salt=32)

    Note: A PSS signature includes a random factor (salt length=32), so even with the same original text, each computed signature result will differ. This is secure and normal.

    json
    {
        "Sn": "rsa_key_v1",
        "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA3F0Q0m015/CF...\n-----END RSA PRIVATE KEY-----"
    }
  • Concatenate the string-to-sign M

    Following the specification, join the parts with \n.

    text
    https://api.sud.com/v1/game/login
    app_10010
    1710500000
    {"iv":"fmW/zNxXlytUZBgj","data":"OIDVdrPtSPF/0e2CTXCV2vVNPbVJdJlP2WaTMQnoYLh5iCrrSNfQFh25EnStDMf0hLlVNBCZQtf9NaV0m4aRA4AAYIO7oR/Ge+4yY4EmZp5EVPB42xjScgMx5X3D4VdLCfynXIUKUtZHZvk1zmLVE3RauzJgiM1BB1C","authtag":"5qeM/2vZv+6KtScN94IpMg=="}
  • Compute the signature and encode it

    Sign the above string M with the app private key:

    text
    base64_encode(Signature) = wcSSWHZunjz9VKl9q+If9deiyECXDAELFAJNZ4+5T+NhFr8zfhkwdQtlgQ7nM...
  • Final complete HTTP request sent

    http
    POST /v1/game/login HTTP/1.1
    Host: api.sud.com
    Content-Type: application/json; charset=utf-8
    X-Sud-AppId: app_10010
    X-Sud-Timestamp: 1710500000
    X-Sud-Signature: wcSSWHZunjz9VKl9q+If9deiyECXDAELFAJNZ4+5T+NhFr8zfhkwdQtlgQ7nM...
    
    {"iv":"fmW/zNxXlytUZBgj","data":"OIDVdrPtSPF/0e2CTXCV2vVNPbVJdJlP2WaTMQnoYLh5iCrrSNfQFh25EnStDMf0hLlVNBCZQtf9NaV0m4aRA4AAYIO7oR/Ge+4yY4EmZp5EVPB42xjScgMx5X3D4VdLCfynXIUKUtZHZvk1zmLVE3RauzJgiM1BB1C","authtag":"5qeM/2vZv+6KtScN94IpMg=="}

4. API Response Processing Specification ​

The response data returned by SUD OP SVR is always in the form of ciphertext + signature. The APP server must process the response data in the order of verify first, then decrypt.

4.1 Response Data Verification ​

4.1.1 Response Header Requirements for Verification ​

Response Header NameRequiredNotes
X-Sud-AppIdYesThe APP server's AppId, matching the X-Sud-AppId in the request header
X-Sud-TimestampYesThe timestamp (in seconds) when SUD OP SVR generated the response
X-Sud-SerialYesThe SUD OpenPaaS certificate serial number
X-Sud-SignatureYesThe response signature result of SUD OP SVR, Base64 encoded
X-Sud-Serial-DeprecatedNoThe serial number of a soon-to-expire certificate (returned during certificate rotation)
X-Sud-Signature-DeprecatedNoThe signature data of a soon-to-expire SUD OpenPaaS certificate, Base64 encoded (returned during certificate rotation)

4.1.2 String-to-Verify Concatenation Rule ​

To ensure consistency of the signature framework, the string-to-verify of the SUD OP SVR response follows exactly the same rule as the request signature: String-to-Verify = urlpath + "\n" + appid + "\n" + timestamp + "\n" + data

Parameter in the VerificationDescription
urlpathThe URL of the current request API, excluding URL parameters (URL Query), and must include the HTTP protocol header. When handling callback responses, use the callback address itself configured by the APP server; see Callback Signature and Encryption.
appidThe value of the response header X-Sud-AppId.
timestampThe value of the response header X-Sud-Timestamp.
dataThe raw ciphertext string of the HTTP response Body.

4.2 Response Ciphertext Decryption ​

The symmetric key and key serial number used for decryption are the same as those used by the APP server in the request. The AAD concatenation format is urlpath|appid|timestamp|sn. After decryption, you must also strictly validate the _appid and _timestamp in the plaintext.

5. Common Error Codes and Solutions ​

Error CodeError Code ValueSolution
40231API_Missing_Sud_AppIdMissing request header: The X-Sud-AppId field is missing. Check whether the unique app identifier AppId was correctly injected into the HTTP header.
40232API_Missing_Sud_TimestampMissing request header: The X-Sud-Timestamp field is missing. Add the second-level timestamp and ensure it is exactly the same as the _timestamp inside the encrypted message.
40233API_Missing_Sud_SignatureMissing request header: The X-Sud-Signature field is missing. Check the private key signing logic, and Base64-encode the generated signature before placing it into this header.
40234API_Invalid_SignatureSignature verification failed (frequent): 1. Check whether the app private key is paired with the app public key stored in the SUD OpenPaaS management console (verify the key serial number SN); 2. Check that the string-to-sign concatenation strictly follows the urlpath\nappid\ntimestamp\ndata format, with the separator being LF (\n), not CRLF; 3. Check whether urlpath includes the HTTP protocol header and excludes the URL Query; 4. Check whether data is the raw string of the HTTP Body (byte-for-byte identical; re-serializing the JSON is not allowed); 5. Check whether the signature result was Base64-encoded before being placed into X-Sud-Signature; 6. For the RSASSA-PSS algorithm, confirm that the MGF1 digest and salt length=32 match the platform.
40235API_Invalid_EncryptEncryption/decryption failed: 1. Check whether the AES-256-GCM AAD concatenation format (urlpath|appid|timestamp|sn) is correct. 2. Confirm whether the passed Cipher ciphertext is complete. In some languages' underlying libraries, the encryption output CipherText and AuthTag need to be concatenated before being passed; if output separately, ensure the authtag field in the JSON message is correct.
40236API_Invalid_Sud_AppIdAppId invalid or not active: The platform cannot recognize X-Sud-AppId. Verify the AppId spelling, or confirm whether the app's status in the SUD OpenPaaS backend is normally enabled.
40237API_Request_ExpiredRequest expired (anti-replay interception): The difference between the X-Sud-Timestamp in the request header and the server's current time exceeds the allowed threshold (300 seconds, i.e., 5 minutes), or the _n (Nonce) inside the message has already been used. Ensure that the business server has NTP time synchronization enabled.

6. Production Environment Security Architecture Best Practices (Must Read) ​

  1. Strong Replay Attack Protection: After receiving any request, the server must strictly validate the timestamp timestamp; if the difference from the current system time exceeds 300 seconds (5 minutes), reject it directly. For requests within 300 seconds, you must store the decrypted _n (Nonce) combined with _appid into a distributed cache such as Redis (with a TTL of 300 seconds). Before processing any new request, if the same Nonce is hit in Redis, treat it as a replay attack and block it directly.
  2. Absolute Private Key Isolation and Backup: The app private key and symmetric key are the highest-level credentials and must never be hardcoded in code or configuration files. Since the private key generated by the management console can be downloaded only once, the R&D team must establish a secure internal KMS system or encrypted configuration center for hosting and backup.
  3. Smooth SUD OpenPaaS Certificate Rotation: When the response header is detected to contain X-Sud-Serial-Deprecated, it indicates that the SUD OpenPaaS platform is performing a SUD OpenPaaS certificate rotation. The app system should trigger an alert or an automated script to promptly fetch the latest SUD OpenPaaS certificate.
  4. Seamless App Key Switching (planned specification): If the APP side suspects a private key leak and needs to replace the key, to avoid business interruption, it is recommended to carry the X-Sud-App-Serial request header in the request to specify the key version (subject to the specific SUD platform version support), in order to achieve a smooth grayscale switchover.

7. Sample Code ​

8. Applicable Interface Scope ​

This mechanism is a mandatory requirement. The table below lists the encryption and signing requirements for each interface in the Server Interfaces: interfaces marked Mandatory must be encrypted and signed, while interfaces marked "Not supported" are called as standard HTTPS plaintext requests.

InterfaceDirectionEncryption and SigningKey Points
auth.getAccessTokenAPP server → SUD OP SVR (open API)Not supportedPlaintext call; the response is plaintext JSON
game.getSignatureAPP server → SUD OP SVR (open API)MandatoryEncrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt
pay.notifyAPP server → SUD OP SVR (open API)MandatoryEncrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt
pay.refundNotifyAPP server → SUD OP SVR (open API)MandatoryEncrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt
ad.rewardNotifyAPP server → SUD OP SVR (open API)MandatoryEncrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt
pay.orderQuerySUD OP SVR → APP server (callback API)MandatoryVerify then decrypt the request before returning the order; encrypt and sign the response
pay.refundSUD OP SVR → APP server (callback API)MandatoryVerify then decrypt the request before accepting the refund; encrypt and sign the response
pay.refundQuerySUD OP SVR → APP server (callback API)MandatoryVerify then decrypt the request before returning the refund status; encrypt and sign the response
ad.rewardQuerySUD OP SVR → APP server (callback API)MandatoryVerify then decrypt the request before returning the completion status; encrypt and sign the response

Notes:

  • Mandatory: Both directions must be encrypted and signed. For open APIs the APP server encrypts and signs the request, then verifies and decrypts the response; for callback APIs the APP server verifies and decrypts the request, then encrypts and signs the response. Messages that are not encrypted, not signed, or fail verification are rejected.
  • Not supported: auth.getAccessToken is neither encrypted nor signed. Request parameters (including secret) are sent in plaintext and responses are plaintext JSON, so no encrypted payload, signature headers, or response verification and decryption are needed.
  • Newly added open interfaces and callback interfaces apply this mechanism by default. To call any of them in plaintext, follow the explicit statement in the corresponding interface document.

This mechanism handles encryption and signing at the HTTP message level; it is a separate mechanism from the symmetric encryption/decryption of business payload fields (such as gameSignature, encrypted_session_key, userSignature) and the data signature key pair verification. For the latter, see Data Security Key Description. Do not mix them.