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 SVRdefined 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
Parameter Required Notes iv Yes Initialization vector; 16 characters after Base64 encoding (12 bytes of random data after decoding) data Yes The encrypted request ciphertext, Base64 encoded authtag Yes The 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|)Field Description urlpath The URL path of the current request API, including the URL protocol, excluding URL parameters (URL Query) appid The unique app identifier AppId timestamp The timestamp (in seconds) of the encryption operation; must be exactly the same as the value of the request header X-Sud-Timestampsn The 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:
Parameter Type Required Notes <original API business fields>Original type Yes All parameters required by the original API, flattened to the JSON root by their original field names (not nested), excluding AccessToken _n string Yes Anti-replay random string (Nonce); a 16-32 byte Base64 random string is recommended _appid string Yes The unique app identifier AppId; must match the appid in the AAD _timestamp number Yes The 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
- Request path (urlpath):
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:textbase64_encode(iv) = fmW/zNxXlytUZBgjStrictly concatenate the AAD in the
urlpath|appid|timestamp|snformat:textaad = https://api.sud.com/v1/game/login|app_10010|1710500000|key_v1Assemble 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, andaadto perform AES-256-GCM encryption, then extract the ciphertext and authentication tag respectively and Base64-encode them:textbase64_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 Name Required Description X-Sud-AppId Yes The AppId filled in by the APP server X-Sud-Timestamp Yes The timestamp (in seconds) at signing time; must match the one used during encryption X-Sud-Signature Yes The 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" + dataParameter in the Signature Description urlpath The URL of the current request API, excluding URL parameters (URL Query), and must include the HTTP protocol header. appid The AppId of the current call (i.e., the value of X-Sud-AppId).timestamp The timestamp at signing time (i.e., the value of X-Sud-Timestamp).data The 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.texthttps://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:
textbase64_encode(Signature) = wcSSWHZunjz9VKl9q+If9deiyECXDAELFAJNZ4+5T+NhFr8zfhkwdQtlgQ7nM...Final complete HTTP request sent
httpPOST /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 Name | Required | Notes |
|---|---|---|
| X-Sud-AppId | Yes | The APP server's AppId, matching the X-Sud-AppId in the request header |
| X-Sud-Timestamp | Yes | The timestamp (in seconds) when SUD OP SVR generated the response |
| X-Sud-Serial | Yes | The SUD OpenPaaS certificate serial number |
| X-Sud-Signature | Yes | The response signature result of SUD OP SVR, Base64 encoded |
| X-Sud-Serial-Deprecated | No | The serial number of a soon-to-expire certificate (returned during certificate rotation) |
| X-Sud-Signature-Deprecated | No | The 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 Verification | Description |
|---|---|
| urlpath | The 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. |
| appid | The value of the response header X-Sud-AppId. |
| timestamp | The value of the response header X-Sud-Timestamp. |
| data | The 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 Code | Error Code Value | Solution |
|---|---|---|
| 40231 | API_Missing_Sud_AppId | Missing request header: The X-Sud-AppId field is missing. Check whether the unique app identifier AppId was correctly injected into the HTTP header. |
| 40232 | API_Missing_Sud_Timestamp | Missing 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. |
| 40233 | API_Missing_Sud_Signature | Missing 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. |
| 40234 | API_Invalid_Signature | Signature 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. |
| 40235 | API_Invalid_Encrypt | Encryption/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. |
| 40236 | API_Invalid_Sud_AppId | AppId 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. |
| 40237 | API_Request_Expired | Request 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)
- 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_appidinto 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. - 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.
- 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. - 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-Serialrequest 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.
| Interface | Direction | Encryption and Signing | Key Points |
|---|---|---|---|
auth.getAccessToken | APP server → SUD OP SVR (open API) | Not supported | Plaintext call; the response is plaintext JSON |
game.getSignature | APP server → SUD OP SVR (open API) | Mandatory | Encrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt |
pay.notify | APP server → SUD OP SVR (open API) | Mandatory | Encrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt |
pay.refundNotify | APP server → SUD OP SVR (open API) | Mandatory | Encrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt |
ad.rewardNotify | APP server → SUD OP SVR (open API) | Mandatory | Encrypt the request first, then sign the ciphertext; verify the response signature first, then decrypt |
pay.orderQuery | SUD OP SVR → APP server (callback API) | Mandatory | Verify then decrypt the request before returning the order; encrypt and sign the response |
pay.refund | SUD OP SVR → APP server (callback API) | Mandatory | Verify then decrypt the request before accepting the refund; encrypt and sign the response |
pay.refundQuery | SUD OP SVR → APP server (callback API) | Mandatory | Verify then decrypt the request before returning the refund status; encrypt and sign the response |
ad.rewardQuery | SUD OP SVR → APP server (callback API) | Mandatory | Verify 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.getAccessTokenis neither encrypted nor signed. Request parameters (includingsecret) 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.
