---
source_url: https://www.pubnub.com/docs/security/encryption/use-custom-encryption
title: Use custom encryption
description: Implement a custom cryptor and register it with the CryptoModule to encrypt messages and files with your own algorithm.
updated_at: 2026-11-04T10:18:23.000Z
---

# Use custom encryption

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

PubNub SDKs expose an interface for custom cryptors. Encryption and decryption logic is decoupled from the SDK, so you can plug in any algorithm alongside the built-in ones.

When the SDK decrypts a message or file, it reads a header in the payload and selects the matching cryptor automatically. This means a client can handle messages encrypted by different cryptors without extra logic in your app code.

## Before you start

Confirm you have:

* A PubNub keyset with publish and subscribe keys from [Admin Portal](https://admin.pubnub.com/).
* Familiarity with your SDK's cryptor interface. See [Cryptor interfaces by SDK](#cryptor-interfaces-by-sdk) for links.

## Steps

### Implement the cryptor interface

Each SDK defines a cryptor interface. Implement it with your custom algorithm. The method names vary by SDK, but every implementation must include an `id` that uniquely identifies the cryptor. In most SDKs this must be a value of **exactly 4 bytes**.

The example below uses Kotlin. The pattern is the same across all supported SDKs.

```kotlin
fun myCustomCryptor() = object : Cryptor {
    override fun id(): ByteArray {
        // Should return a ByteArray of exactly 4 bytes.
        return byteArrayOf('C'.code.toByte(), 'U'.code.toByte(), 'S'.code.toByte(), 'T'.code.toByte())
    }

    override fun encrypt(data: ByteArray): EncryptedData {
        // implement your crypto logic
        return EncryptedData(metadata = null, data = data)
    }

    override fun decrypt(encryptedData: EncryptedData): ByteArray {
        // implement your crypto logic
        return encryptedData.data
    }

    override fun encryptStream(stream: InputStream): EncryptedStreamData {
        // implement your crypto logic
        return EncryptedStreamData(metadata = null, stream = stream)
    }

    override fun decryptStream(encryptedData: EncryptedStreamData): InputStream {
        // implement your crypto logic
        return encryptedData.stream
    }
}
```

### Create a CryptoModule with the custom cryptor

Pass your cryptor as the default when creating the CryptoModule, then pass the module to PubNub configuration.

```kotlin
val customCryptor = myCustomCryptor()
val cryptoModule = CryptoModule.createNewCryptoModule(defaultCryptor = customCryptor)
```

Pass `cryptoModule` to the PubNub configuration in the same way as the built-in AES-CBC module. See [Encrypt and decrypt all messages and files](https://www.pubnub.com/docs/security/encryption/encrypt-all-messages-and-files.md) for the initialization pattern.

## Cryptor interfaces by SDK

Each SDK exposes the cryptor interface at a different location. Implement the interface listed for your SDK:

| SDK | Interface |
| --- | --- |
| C-Core (legacy) | [`pbcc_crypto.h`](https://github.com/pubnub/c-core/blob/master/core/pbcc_crypto.h#L73-L108) |
| C# / Unity | [`ICryptor.cs`](https://github.com/pubnub/c-sharp/blob/master/src/Api/PubnubApi/Security/Crypto/ICryptor.cs) |
| Dart | [`ICryptor.dart`](https://github.com/pubnub/dart/blob/master/pubnub/lib/src/core/crypto/crypto.dart#L28) |
| Go | [`cryptor.go`](https://github.com/pubnub/go/blob/master/crypto/cryptor.go) |
| Java | [`Cryptor.kt`](https://github.com/pubnub/kotlin/blob/master/pubnub-kotlin/pubnub-kotlin-core-api/src/jvmMain/kotlin/com/pubnub/api/crypto/cryptor/Cryptor.kt) |
| JavaScript | [`ICryptor.ts`](https://github.com/pubnub/javascript/blob/master/src/crypto/modules/NodeCryptoModule/ICryptor.ts) |
| Kotlin | [`Cryptor.kt`](https://github.com/pubnub/kotlin/blob/master/pubnub-kotlin/pubnub-kotlin-core-api/src/jvmMain/kotlin/com/pubnub/api/crypto/cryptor/Cryptor.kt) |
| Objective-C | [`PNCryptor.h`](https://github.com/pubnub/objective-c/blob/master/PubNub/Misc/Protocols/PNCryptor.h) |
| PHP | [`Cryptor.php`](https://github.com/pubnub/php/blob/master/src/PubNub/Crypto/Cryptor.php) |
| Python | [`crypto_core.py`](https://github.com/pubnub/python/blob/master/pubnub/crypto_core.py#L38-L47) |
| Ruby | [`cryptor.rb`](https://github.com/pubnub/ruby/blob/master/lib/pubnub/modules/crypto/cryptor.rb) |
| Rust | [`cryptor.rs`](https://github.com/pubnub/rust/blob/master/src/core/cryptor.rs) |
| Swift | [`Cryptor.swift`](https://github.com/pubnub/swift/blob/master/Sources/PubNub/Helpers/Crypto/Cryptors/Cryptor.swift#L36) |

The Unreal Engine SDK doesn't support custom cryptors. Its crypto module accepts only the built-in `UPubnubAesCryptor` and `UPubnubLegacyCryptor`. For details, refer to [Unreal Engine encryption](https://www.pubnub.com/docs/sdks/unreal/api-reference/encryption.md#custom-cryptors).

For SDK-specific configuration details, see the [Crypto module](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration.md#cryptomodule) section in each SDK's configuration reference.

Last updated at: 2026-11-04T10:18:23.000Z