Encryption API for Unreal SDK
PubNub Unreal SDK includes message encryption. This page covers crypto module configuration and how to encrypt and decrypt data with the AES-CBC and legacy cryptors.
For general SDK configuration and initialization, refer to the Configuration page.
If you are upgrading from an earlier SDK version, refer to the Unreal v3 migration guide.
Configuration
The crypto system in Unreal SDK consists of two main components:
- Cryptors (
IPubnubCryptorInterface), which are individual encryption algorithms. The SDK providesUPubnubAesCryptorandUPubnubLegacyCryptor. - Crypto module (
UPubnubCryptoModule), which holds one default cryptor and up to 4 additional cryptors, and selects the algorithm automatically.
Configure encryption before you create the client. Initialize a UPubnubCryptoModule with InitCryptoModule(). Assign it to FPubnubConfig::CryptoModule and pass the config to CreatePubnubClient(). With multiple clients, assign a crypto module to the config of each client that should use encryption.
Automatic message encryption/decryption
Once configured, the crypto module automatically handles encryption and decryption:
- The default cryptor encrypts all published messages.
- The module decrypts received and fetched history messages with the cryptor that matches the 4-byte identifier in the message header.
- Additional cryptors are used only for decryption.
Configuration rules
- The client holds the crypto module for as long as it exists, so keep the module alive for the life of the client.
InitCryptoModule()fails while a live client still holds the module.UPubnubCryptoModuleaccepts onlyUPubnubAesCryptorandUPubnubLegacyCryptor. It rejects custom cryptors.- If you leave
FPubnubConfig::CryptoModuleunset, the client sends and receives messages without payload encryption.
Initialize crypto module
Registers the cryptors and prepares the module for client creation.
1bool UPubnubCryptoModule::InitCryptoModule(
2 const TScriptInterface<IPubnubCryptorInterface>& InDefaultCryptor,
3 const TArray<TScriptInterface<IPubnubCryptorInterface>>& InAdditionalCryptors
4);
InDefaultCryptorrequired#- The cryptor that encrypts outbound messages. Set its cipher key before you pass it in.
InAdditionalCryptorsrequired#- Extra cryptors used only to decrypt messages with a matching identifier. Pass an empty array if you don't need any. Maximum is 4. Set the cipher key on each one before you pass it in.
Returns
| Type | Description |
|---|---|
bool | true when the module is ready. false when the default cryptor is missing or isn't a built-in cryptor with a cipher key, an additional cryptor is invalid, you pass more than 4 additional cryptors, or a live client still holds the module. |
Sample code
To create a crypto module with AES encryption and assign it to the client config:
Available cryptors
The Unreal SDK provides two built-in cryptor implementations:
AES cryptor (UPubnubAesCryptor)
Uses 256-bit AES-CBC encryption. This is the recommended cryptor for new applications.
| Feature | Description |
|---|---|
| Identifier | 'A', 'C', 'R', 'H' (4-byte header identifier) |
| Key management | Set the cipher key with SetCipherKey(FString). The SDK hashes it with SHA-256. |
| IV generation | Generates a random 16-byte IV for each encryption |
| Compatibility | Compatible with PubNub AES encryption across all SDKs |
Legacy cryptor (UPubnubLegacyCryptor)
Provides compatibility with older PubNub encryption implementations. Use the AES cryptor as the default cryptor and add the legacy cryptor as an additional cryptor if you need to decrypt legacy messages.
Legacy cryptor usage
Useful when your Unreal SDK must be able to decrypt messages encrypted with the legacy PubNub encryption from other SDKs.
| Feature | Description |
|---|---|
| Identifier | {0, 0, 0, 0} (4-byte legacy identifier) |
| Key management | Set the cipher key with SetCipherKey(FString) |
| IV options | UseRandomIV is true by default and prefixes a random 16-byte IV to the ciphertext. Set it to false for the static IV 0123456789012345, which exists for compatibility only. Set it before you call InitCryptoModule(). |
| Compatibility | Compatible with legacy PubNub encryption |
Both cryptors lock after a crypto module takes them, so you can't change the cipher key or IV mode afterward.
Legacy configuration
To configure legacy decryption for all messages:
Actor.h
1
Actor.cpp
1
Custom cryptors
UPubnubCryptoModule rejects custom cryptors, so you can't register your own implementation of IPubnubCryptorInterface. For more information about custom encryption in other SDKs, refer to the Data security section.
Encrypt
Use this function to encrypt data manually with a cryptor.
Method(s)
To encrypt data you can use the following method in the Unreal SDK:
FPubnubEncryptedData IPubnubCryptorInterface::Execute_Encrypt(UObject* Cryptor, const FString& Data);
Sample code
Actor.h
1
Actor.cpp
1
Returns
Returns an FPubnubEncryptedData struct. EncryptedData holds the Base64-encoded ciphertext and Metadata holds the Base64-encoded metadata. For AES-CBC, the metadata is the 16-byte IV. For the legacy cryptor, Metadata is empty. If encryption fails, EncryptedData is an empty string.
Decrypt
Use this function to decrypt data manually with a cryptor.
Method(s)
To decrypt data you can use the following method in the Unreal SDK:
FString IPubnubCryptorInterface::Execute_Decrypt(UObject* Cryptor, const FPubnubEncryptedData& Data);
Sample code
Actor.h
1
Actor.cpp
1
Returns
Returns the decrypted message as a plaintext FString or an empty string if decryption fails.
Complete example
ASample_CryptoFull.h
1
ASample_CryptoFull.cpp
1