This guide shows you how to encrypt your profile and event data with AES-256-GCM and send it securely to the Netcore CE panel.
Overview
AES-256 (Advanced Encryption Standard with a 256 bit key) protects your data while it travels from your servers to Netcore. It gives you:
- Strong security: highly resistant to brute force attacks.
- Wide adoption: used by governments, financial institutions, and enterprises worldwide.
- Fast performance: optimized for modern systems with minimal overhead.
Netcore supports AES-256 GCM (no padding) encryption for both profile data and event data.
AES-256 encryption is not enabled by defaultThis is a request based feature. To enable it for your account, send a request to the Netcore helpdesk team at [email protected]. Once enabled, continue with the steps below to generate and whitelist your secret key.
Security built into the standard v5 API
Netcore's standard v5 API already applies the following security measures to every request, whether or not encryption is enabled:
- Authenticated source IP whitelisting.
- Input validation, to ensure data is inserted and delivered in the required format.
- HTTPS with TLS v1.2, to keep data safe in transit.
AES-256 encryption adds an extra layer of security on top of this. With encryption enabled, you encrypt the payload on your own server before sending it, and Netcore decrypts it on arrival before processing it further. Use the encryption steps below only after your key has been whitelisted for this purpose.
Step 1: Generate and Share Secret Key
Generate a secret key on your own system, then share it with the Netcore support team so they can whitelist it. Choose the script that matches your stack. There are two options to do so:
- Python: Generate the secret key using the Python program.
- Java: Generate the secret key using the Java program.
Python
Use the Python script to generate the AES-256 encryption key and initialization vector (IV)
Follow the steps below to do so:
- Download the key generator script from below:
import secrets
import base64
def generate_aes_b64_credentials():
# 1. Generate cryptographically secure random bytes
# AES-256 requires a 32-byte key
# AES typically uses a 16-byte IV
raw_key = secrets.token_bytes(32)
raw_iv = secrets.token_bytes(16)
# 2. Encode those bytes into Base64 strings
key_b64 = base64.b64encode(raw_key).decode('utf-8')
iv_b64 = base64.b64encode(raw_iv).decode('utf-8')
return key_b64, iv_b64
# --- Execution ---
key_b64, iv_b64 = generate_aes_b64_credentials()
print(f"=== AES Base64 Credentials ===\n")
print(f'KEY_B64 = "{key_b64}"')
print(f'IV_B64 = "{iv_b64}"')
print("\n# How to use in your main script:")
print("import base64")
print(f"SECRET_KEY = base64.b64decode('{key_b64}')")
print(f"IV = base64.b64decode('{iv_b64}')")- Run the downloaded Python file on the local system to generate the encryption key and IV.
python AES256_KEY_GENERATOR_V5.py- The program generates Base64-encoded credentials. The output looks like below:
=== AES Base64 Credentials ===
KEY_B64 = "Hd374+TUvU2BDYtPL68D6X1r+liBHINOq+kh8dy5ufc="
IV_B64 = "Z/6bDiXn5/t9BaYV5SBHVQ=="
These are example values. The program generates new credentials each time it runs.
- Share the
KEY_B64value with the Netcore helpdesk team at [email protected] for whitelisting. Keep the secret key secure and do not share it publicly.
Java
Use the Java program to generate the AES-256 encryption key and initialization vector (IV)
Follow the steps below to do so:
-
Download the key generator script from below:
import java.security.SecureRandom; import java.util.Base64; public class AES256_KEY_GENERATOR_v5 { public static void main(String[] args) { // 1. Generate cryptographically secure random bytes // AES-256 requires 32 bytes (256 bits) // AES typically uses a 16-byte (128-bit) IV / Nonce byte[] rawKey = new byte[32]; byte[] rawIv = new byte[16]; SecureRandom secureRandom = new SecureRandom(); secureRandom.nextBytes(rawKey); secureRandom.nextBytes(rawIv); // 2. Encode bytes into Base64 strings String keyB64 = Base64.getEncoder().encodeToString(rawKey); String ivB64 = Base64.getEncoder().encodeToString(rawIv); // --- Output --- System.out.println("=== AES Base64 Credentials ===\n"); System.out.println("KEY_B64 = \"" + keyB64 + "\""); System.out.println("IV_B64 = \"" + ivB64 + "\""); System.out.println("\n// How to use in your main Java script:"); System.out.println("import java.util.Base64;"); System.out.println("byte[] secretKey = Base64.getDecoder().decode(\"" + keyB64 + "\");"); System.out.println("byte[] iv = Base64.getDecoder().decode(\"" + ivB64 + "\");"); } } -
Compile the Java program:
javac AES256_KEY_GENERATOR_v5.java -
Run the program to generate the encryption credentials:
java AES256_KEY_GENERATOR_v5 -
The program generates Base64-encoded credentials. The output looks like this:
=== AES Base64 Credentials === KEY_B64 = "hSqLya6QtfGBYPB8kTQqAXDlOK7zigUWjQ2FB5Iihgs=" IV_B64 = "s2d3zIXq+yLffXkx8A2unQ=="These are example values. The program generates new credentials each time it runs. -
Decode the Base64 values in the main Java program when the raw key and IV bytes are required:
import java.util.Base64;byte[] secretKey = Base64.getDecoder().decode("YOUR_KEY_B64");byte[] iv = Base64.getDecoder().decode("YOUR_IV_B64");
Important Point to Remember
- Share the KEY_B64 value with the Netcore helpdesk team at [email protected] for whitelisting. Once the team confirms that the key has been whitelisted in the backend, proceed with encrypting the profile and event data before sending it to Netcore CE.
- Use the generated credentials instead of the example values. Keep the secret key secure and do not share it publicly.
Key Rotation
If your secret key is set to expire or you plan to rotate it, generate the new key in advance and share it with the Netcore helpdesk team at [email protected] before the current key expires. This gives the team time to whitelist the new key, so your data pushes continue without interruption.
Step 2: Data Encryption
Once your key is whitelisted, encrypt your profile data and event data on your own server before sending it to Netcore.
Encrypt Profile Data
Profile data must be encrypted on the source server before it is sent to Netcore CE.
Here is a sample profile data payload:
{
"data": {
"contact_type": "identified",
"contacts": [
{
"attributes": {
"MARITAL_STATUS": "Unmarried",
"LANGUAGE": "Spanish",
"GENDER": "Male",
"OCCUPATION": "Private"
},
"identity": "1010010199",
"mobile": "9611196111",
"email": "[email protected]"
}
]
}
}Python
Use the Python encryption script to encrypt the profile data.
- Download the Python encryption script.
import os
import sys
import base64
from typing import Optional
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
# ==========================================================
# CONFIG (Same key must be used in decrypt.py)
# ==========================================================
#Use your generated encryption key
KEY_B64 = "dABnt8YorIRFJaTinOptEtRA3poBrBrh22tjulHltyg=="
SECRET_KEY = base64.b64decode(KEY_B64)
if len(SECRET_KEY) != 32:
raise ValueError("Key must be 32 bytes for AES-256")
# ==========================================================
# ENCRYPT FUNCTION
# ==========================================================
def encrypt_aes256_gcm(plaintext: str, aad: Optional[bytes] = None) -> str:
aesgcm = AESGCM(SECRET_KEY)
nonce = os.urandom(12) # 12-byte nonce
ciphertext = aesgcm.encrypt(nonce, plaintext.encode("utf-8"), aad)
combined = nonce + ciphertext
return base64.b64encode(combined).decode("ascii")
# ==========================================================
# MAIN
# ==========================================================
if __name__ == "__main__":
if len(sys.argv) != 2:
print("Usage: python3 encrypt.py '<payload>'")
sys.exit(1)
payload = sys.argv[1]
encrypted = encrypt_aes256_gcm(payload)
print(encrypted)- Run the script with the profile JSON payload:
python3 AES256_GCM_ENCRYPTION_SCRIPT.py '<your JSON payload>'Java
Use the Java encryption program to encrypt the profile data.
- Download the Java encryption script:
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class AES256_GCM_ENCRYPTION_SCRIPT {
// ==========================================================
// CONFIG (32-byte key for AES-256)
// ==========================================================
private static final String KEY_B64 = "Vk0xak1MQ2JBKzZzV3crYU1aTmpseERjVkZ1RzFCSno=";
private static final int GCM_TAG_LENGTH_BITS = 128; // Standard 16-byte GCM tag
private static final int NONCE_LENGTH_BYTES = 12; // Standard 12-byte nonce
public static String encryptAes256Gcm(String plaintext, byte[] aad) throws Exception {
// Decode Base64 Key
byte[] keyBytes = Base64.getDecoder().decode(KEY_B64);
if (keyBytes.length != 32) {
throw new IllegalArgumentException("Key must be 32 bytes for AES-256");
}
SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
// Generate 12-byte random nonce
byte[] nonce = new byte[NONCE_LENGTH_BYTES];
SecureRandom random = new SecureRandom();
random.nextBytes(nonce);
// Initialize AES-GCM Cipher
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
GCMParameterSpec gcmSpec = new GCMParameterSpec(GCM_TAG_LENGTH_BITS, nonce);
cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec);
// Add Associated Authenticated Data (AAD) if present
if (aad != null && aad.length > 0) {
cipher.updateAAD(aad);
}
// Encrypt (Ciphertext + 16-byte Auth Tag are generated automatically)
byte[] ciphertext = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
// Combine Nonce (12 bytes) + Ciphertext
byte[] combined = new byte[nonce.length + ciphertext.length];
System.arraycopy(nonce, 0, combined, 0, nonce.length);
System.arraycopy(ciphertext, 0, combined, nonce.length, ciphertext.length);
// Return Base64 encoded string
return Base64.getEncoder().encodeToString(combined);
}
public static void main(String[] args) {
if (args.length != 1) {
System.out.println("Usage: java Encrypt '<payload>'");
System.exit(1);
}
try {
String payload = args[0];
String encrypted = encryptAes256Gcm(payload, null);
System.out.println(encrypted);
} catch (Exception e) {
System.err.println("Encryption failed: " + e.getMessage());
e.printStackTrace();
System.exit(1);
}
}
}- Compile the Java program:
javac AES256_GCM_ENCRYPTION_SCRIPT.javaRun the program with the profile JSON payload:
java AES256_GCM_ENCRYPTION_SCRIPT '<your JSON payload>'
Both scripts return an encrypted string. Use this string, instead of the original JSON payload, when sending the request to the Netcore API in Step three.
Encrypt Event Data
Event data must also be encrypted before it is sent to Netcore.
Here is a sample event data payload:
[
{
"asset_id": "<ASSET ID FROM PANEL>",
"activity_name": "EVENT_NAME",
"timestamp": "2026-09-21T13:57:02Z",
"identity": "10000001",
"mobile": "9999999999",
"email": "[email protected]",
"activity_source": "web",
"activity_params": {
"status": "new",
"name": "Mahesh"
}
}
]Python
Use the Python encryption script to encrypt the profile data.
- Download the Python encryption script.
import os
import sys
import base64
from typing import Optional
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
# ==========================================================
# CONFIG (Same key must be used in decrypt.py)
# ==========================================================
#Use your generated encryption key
KEY_B64 = "dABnt8YorIRFJaTinOptEtRA3poBrBrh22tjulHltyg=="
SECRET_KEY = base64.b64decode(KEY_B64)
if len(SECRET_KEY) != 32:
raise ValueError("Key must be 32 bytes for AES-256")
# ==========================================================
# ENCRYPT FUNCTION
# ==========================================================
def encrypt_aes256_gcm(plaintext: str, aad: Optional[bytes] = None) -> str:
aesgcm = AESGCM(SECRET_KEY)
nonce = os.urandom(12) # 12-byte nonce
ciphertext = aesgcm.encrypt(nonce, plaintext.encode("utf-8"), aad)
combined = nonce + ciphertext
return base64.b64encode(combined).decode("ascii")
# ==========================================================
# MAIN
# ==========================================================
if __name__ == "__main__":
if len(sys.argv) != 2:
print("Usage: python3 encrypt.py '<payload>'")
sys.exit(1)
payload = sys.argv[1]
encrypted = encrypt_aes256_gcm(payload)
print(encrypted)- Run the script with the profile JSON payload:
python3 AES256_GCM_ENCRYPTION_SCRIPT.py '<your JSON payload>'Java
Use the Java encryption program to encrypt the profile data.
- Download the Java encryption script.
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class AES256_GCM_ENCRYPTION_SCRIPT {
// ==========================================================
// CONFIG (32-byte key for AES-256)
// ==========================================================
private static final String KEY_B64 = "Vk0xak1MQ2JBKzZzV3crYU1aTmpseERjVkZ1RzFCSno=";
private static final int GCM_TAG_LENGTH_BITS = 128; // Standard 16-byte GCM tag
private static final int NONCE_LENGTH_BYTES = 12; // Standard 12-byte nonce
public static String encryptAes256Gcm(String plaintext, byte[] aad) throws Exception {
// Decode Base64 Key
byte[] keyBytes = Base64.getDecoder().decode(KEY_B64);
if (keyBytes.length != 32) {
throw new IllegalArgumentException("Key must be 32 bytes for AES-256");
}
SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
// Generate 12-byte random nonce
byte[] nonce = new byte[NONCE_LENGTH_BYTES];
SecureRandom random = new SecureRandom();
random.nextBytes(nonce);
// Initialize AES-GCM Cipher
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
GCMParameterSpec gcmSpec = new GCMParameterSpec(GCM_TAG_LENGTH_BITS, nonce);
cipher.init(Cipher.ENCRYPT_MODE, secretKey, gcmSpec);
// Add Associated Authenticated Data (AAD) if present
if (aad != null && aad.length > 0) {
cipher.updateAAD(aad);
}
// Encrypt (Ciphertext + 16-byte Auth Tag are generated automatically)
byte[] ciphertext = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
// Combine Nonce (12 bytes) + Ciphertext
byte[] combined = new byte[nonce.length + ciphertext.length];
System.arraycopy(nonce, 0, combined, 0, nonce.length);
System.arraycopy(ciphertext, 0, combined, nonce.length, ciphertext.length);
// Return Base64 encoded string
return Base64.getEncoder().encodeToString(combined);
}
public static void main(String[] args) {
if (args.length != 1) {
System.out.println("Usage: java Encrypt '<payload>'");
System.exit(1);
}
try {
String payload = args[0];
String encrypted = encryptAes256Gcm(payload, null);
System.out.println(encrypted);
} catch (Exception e) {
System.err.println("Encryption failed: " + e.getMessage());
e.printStackTrace();
System.exit(1);
}
}
}- Compile the Java program:
javac AES256_GCM_ENCRYPTION_SCRIPT.java- Run the program with the profile JSON payload:
java AES256_GCM_ENCRYPTION_SCRIPT '<your JSON payload>'The program returns an encrypted string. Use this string instead of the original JSON payload when sending the request to the Netcore API.
The above are the same Python or Java encryption script described in the previous section. Pass the event JSON payload to the script to generate the encrypted string.
Key Parameters
Refer to the table below for the key parameters descriptions:
| Parameter | Description |
|---|---|
asset_id | Asset ID obtained from the Netcore panel. |
activity_name | Name of the event being recorded. |
timestamp | Current UTC time or the time when the event occurred, expressed in UTC. |
identity | Primary key configured in the Netcore panel. |
activity_source | Specifies the source of the event. Use web for a web asset or app for an app asset. |
activity_params | Contains the parameters associated with the event. |
Test the Decryption
Verify the encryption process by decrypting the generated string locally using the same secret key. The decrypted output should match the original payload.
Python
Use the Python decryption script to verify the encrypted data.
- Download the Python decryption script.
import sys
import base64
from typing import Optional
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
# ==========================================================
# CONFIG (Same key as encrypt.py)
# ==========================================================
#Use your generated encryption key
KEY_B64 = "dABnt8YorIRFJaTinOptEtRA3poBrBrh22tjulHltyg=="
SECRET_KEY = base64.b64decode(KEY_B64)
if len(SECRET_KEY) != 32:
raise ValueError("Key must be 32 bytes for AES-256")
# ==========================================================
# DECRYPT FUNCTION
# ==========================================================
def decrypt_aes256_gcm(encrypted_b64: str, aad: Optional[bytes] = None) -> str:
aesgcm = AESGCM(SECRET_KEY)
combined = base64.b64decode(encrypted_b64)
nonce = combined[:12]
ciphertext = combined[12:]
plaintext = aesgcm.decrypt(nonce, ciphertext, aad)
return plaintext.decode("utf-8")
# ==========================================================
# MAIN
# ==========================================================
if __name__ == "__main__":
if len(sys.argv) != 2:
print("Usage: python3 decrypt.py '<encrypted_base64>'")
sys.exit(1)
encrypted_input = sys.argv[1]
try:
decrypted = decrypt_aes256_gcm(encrypted_input)
print(decrypted)
except Exception as e:
print("Decryption failed:", str(e))- Run the script with the encrypted string:
python3 AES256_GCM_DECRYPTION_SCRIPT.py '<your encrypted string>'Java
Use the Java decryption program to verify the encrypted data.
- Download the Java decryption script.
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class AES256_GCM_DECRYPTION_SCRIPT {
// ==========================================================
// CONFIG (32-byte key for AES-256 - Replace with your actual Base64 key)
// ==========================================================
private static final String KEY_B64 = "2POm3AlTZ4Ci7Cz8aWfacDPC4wIkDtVAQ2cti0l2S2A=";
private static final int GCM_TAG_LENGTH_BITS = 128; // Standard 16-byte GCM tag
private static final int NONCE_LENGTH_BYTES = 12; // Standard 12-byte nonce
public static String decryptAes256Gcm(String encryptedB64, byte[] aad) throws Exception {
// Decode Base64 Key
byte[] keyBytes = Base64.getDecoder().decode(KEY_B64);
if (keyBytes.length != 32) {
throw new IllegalArgumentException("Key must be 32 bytes for AES-256");
}
SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
// Decode input Base64 string
byte[] combined = Base64.getDecoder().decode(encryptedB64);
if (combined.length < NONCE_LENGTH_BYTES + (GCM_TAG_LENGTH_BITS / 8)) {
throw new IllegalArgumentException("Invalid payload length");
}
// Extract 12-byte Nonce and Ciphertext
byte[] nonce = Arrays.copyOfRange(combined, 0, NONCE_LENGTH_BYTES);
byte[] ciphertext = Arrays.copyOfRange(combined, NONCE_LENGTH_BYTES, combined.length);
// Initialize AES-GCM Cipher for Decryption
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
GCMParameterSpec gcmSpec = new GCMParameterSpec(GCM_TAG_LENGTH_BITS, nonce);
cipher.init(Cipher.DECRYPT_MODE, secretKey, gcmSpec);
// Add Associated Authenticated Data (AAD) if present
if (aad != null && aad.length > 0) {
cipher.updateAAD(aad);
}
// Decrypt (Authenticates the tag and decrypts)
byte[] plaintextBytes = cipher.doFinal(ciphertext);
return new String(plaintextBytes, StandardCharsets.UTF_8);
}
public static void main(String[] args) {
if (args.length != 1) {
System.out.println("Usage: java Decrypt '<encrypted_base64>'");
System.exit(1);
}
String encryptedInput = args[0];
try {
String decrypted = decryptAes256Gcm(encryptedInput, null);
System.out.println(decrypted);
} catch (Exception e) {
System.out.println("Decryption failed: " + e.getMessage());
}
}
}- Compile the Java program:
javac AES256_GCM_DECRYPTION_SCRIPT.java- Run the program with the encrypted string:
java AES256_GCM_DECRYPTION_SCRIPT '<your encrypted string>'If decryption succeeds, the script returns the original, unencrypted data.
Step 3: Send Data to Netcore CE
Send your encrypted string to Netcore with a curl request.
Send Profile Data
curl --location 'https://netcoreapi-main-prod-us.netcorein.com/v5/contact/create' \
--header 'api-key: <API KEY FROM PANEL>' \
--header 'Content-Type: application/json' \
--data '{
"data": "<YOUR ENCRYPTED STRING>"
}'
Use /create to add a new contact, /update to update an existing one, or /upsert to do either in one call.
A successful call returns the encrypted data back along with a request ID:
{"data":"<encrypted string>","request_id":"01a0c48c-4509-7dc3-a93e-035cbc13886f"}Send Event Data
curl --location 'https://apiin2.netcoresmartech.com/v1/activity/upload' \
--header 'x-eCode: 11259' \
--header 'x-asset: <ASSET ID FROM PANEL>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API KEY FROM PANEL>' \
--data '{
"encryptedRequest": "<YOUR ENCRYPTED STRING>"
}'
x-eCode: 11259identifies the AES_256_GCM_BASE64 algorithm. Keep this value as is.x-assetis the same asset ID you used when encrypting the payload.- Pass your panel's API key as the bearer token.
A successful call returns:
{"status": "success"}
Important Point to RememberA
successresponse confirms that Netcore accepted your request. It does not confirm that the data has finished processing, since Netcore processes incoming data asynchronously. To confirm your data landed correctly, check the Netcore CE panel directly.
Troubleshoot & FAQs
Q. Is AES-256 encryption enabled by default for my account?
A. No. This is a request based feature. Send a request to [email protected] to have it enabled for your account before you generate and share a secret key.
Q. Do I still need encryption if the API already has IP whitelisting, input validation, and TLS?
A. Those protections apply to every v5 API call regardless of encryption. AES-256 encryption is an additional layer on top of them. It encrypts the payload itself before it leaves your server, so the data stays encrypted until Netcore decrypts it on arrival.
Q. What should I do if my secret key is about to expire or needs to be rotated?
A. Generate a new key using the same script, then share it with the Netcore helpdesk team at [email protected] in advance of the expiry date. This gives the team time to whitelist the new key before the old one stops working.
Q. Which algorithm and parameters does Netcore expect?
A. Netcore expects AES-256 GCM with no padding, a 12 byte nonce, and a 128 bit GCM authentication tag, combined as nonce followed by ciphertext and base64 encoded, as shown in the sample scripts above.
Q. My request returned a success response. Does that mean my data has been processed?
A. A success response only confirms that Netcore accepted the request. Data is processed asynchronously, so check the Netcore CE panel to confirm it landed correctly.
If you need any assistance at any step, contact our support team at [email protected].
