Encryption API for Unreal SDK

icon

Usage in Blueprints and C++


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:

  1. Cryptors (IPubnubCryptorInterface), which are individual encryption algorithms. The SDK provides UPubnubAesCryptor and UPubnubLegacyCryptor.
  2. 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.
  • UPubnubCryptoModule accepts only UPubnubAesCryptor and UPubnubLegacyCryptor. It rejects custom cryptors.
  • If you leave FPubnubConfig::CryptoModule unset, 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);
required
InDefaultCryptor required#
Type: TScriptInterface<IPubnubCryptorInterface>
The cryptor that encrypts outbound messages. Set its cipher key before you pass it in.
InAdditionalCryptors required#
Type: TArray<TScriptInterface<IPubnubCryptorInterface>>
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​

TypeDescription
booltrue 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:

Actor.h​
1

Actor.cpp​
1

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.

FeatureDescription
Identifier'A', 'C', 'R', 'H' (4-byte header identifier)
Key managementSet the cipher key with SetCipherKey(FString). The SDK hashes it with SHA-256.
IV generationGenerates a random 16-byte IV for each encryption
CompatibilityCompatible 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.

FeatureDescription
Identifier{0, 0, 0, 0} (4-byte legacy identifier)
Key managementSet the cipher key with SetCipherKey(FString)
IV optionsUseRandomIV 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().
CompatibilityCompatible 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);
required
Cryptor required#
Type: UObject*
The cryptor object that implements IPubnubCryptorInterface, for example UPubnubAesCryptor with its cipher key set.
Data required#
Type: FString
The plaintext data to encrypt.

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);
required
Cryptor required#
Type: UObject*
The cryptor object that implements IPubnubCryptorInterface.
Data required#
Type: FPubnubEncryptedData
The encrypted data to decrypt. Put the Base64-encoded ciphertext in EncryptedData and the Base64-encoded metadata in Metadata.

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

Was this page useful?

Last updated on