---
source_url: https://www.pubnub.com/docs/sdks/c-sharp/api-reference/encryption
title: Encryption API for C# SDK
updated_at: 2026-06-19T11:36:50.145Z
sdk_name: PubNub C# SDK
sdk_version: 8.3.0
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Encryption API for C# SDK

PubNub C# SDK, use the latest version: 8.3.0

Install:

```bash
dotnet add package PubNub@8.3.0
```

PubNub C# SDK includes message and file encryption. This page explains how to configure the `CryptoModule` and how to encrypt and decrypt data. The SDK supports 128-bit Advanced Encryption Standard (AES) and 256-bit AES in Cipher Block Chaining (CBC) mode (AES-CBC).

For general SDK configuration and initialization, refer to the [Configuration](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration) page.

## Configuration

### CryptoModule configuration

To configure the `CryptoModule` to encrypt all messages/files, you can use the following methods in the C# SDK:

```csharp
using PubnubApi;

PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"));
// encrypts using 256-bit AES-CBC cipher (recommended)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
pnConfiguration.CryptoModule = new CryptoModule(new AesCbcCryptor("enigma"),
    new List<ICryptor> { new LegacyCryptor("enigma") });

// encrypts with 128-bit cipher key entropy (legacy)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
pnConfiguration.CryptoModule = new CryptoModule(new LegacyCryptor("enigma"),
    new List<ICryptor> { new AesCbcCryptor("enigma") });
```

Your client can decrypt content produced by either `CryptoModule` or legacy `cipherKey`-based encryption. This allows the client to read historical messages and messages from older clients while you encrypt new messages with the stronger AES-256-CBC cipher.

:::warning Older SDK versions
Apps built using the SDK versions lower than 6.18.0 will not be able to decrypt data encrypted using the 256-bit AES-CBC cipher. Update your clients or encrypt data using the legacy algorithm.
:::

:::note SDK initialization required
Before you use encryption methods, ensure your PubNub client is configured with publish/subscribe keys and a user ID. See the [Configuration guide](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#initialization) for setup instructions.
:::

### Relationship between CryptoModule and cipherKey

The `CryptoModule` supersedes the `cipherKey` parameter, providing stronger security and more flexibility. If you pass `cipherKey` to an API call while `CryptoModule` is configured, the call uses legacy AES-128 encryption and ignores `CryptoModule` for that operation. For partial encryption, create a separate `CryptoModule` instance and use it only where needed.

## Encryption methods

### Encrypt

Use this function to encrypt data.

:::warning Deprecated
The `cipherKey` parameter in this method is deprecated. We recommend that you configure a separate instance of the [CryptoModule](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule) and use it for partial encryption. If you pass `cipherKey` as an argument, it overrides the `CryptoModule` configuration and the legacy encryption with 128-bit cipher key entropy is used.
:::

#### Method(s)

To `encrypt` the data you can use the following method(s) in C# SDK.

```csharp
pubnub.Encrypt(inputString, cipherKey)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| inputString | String | Yes |  | The `data` to `encrypt`. |
| cipherKey | String | Optional |  | Cipher key to use for encryption. |

#### Sample code

##### Encrypt part of message

```csharp
using PubnubApi;

// Configuration
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"))
{
    SubscribeKey = "demo",
    PublishKey = "demo",
    Secure = true
};

// Initialize PubNub
Pubnub pubnub = new Pubnub(pnConfiguration);
        
string stringToEncrypt = "hello world";
var crypto = PubnubApi.Security.Crypto.CryptoModule.CreateAesCbcCryptor("test");
crypto.Encrypt(stringToEncrypt);
```

### Encrypt file

Use this function to encrypt file content.

:::warning Deprecated
The `cipherKey` parameter in this method is deprecated. We recommend that you configure a separate instance of the [CryptoModule](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule) and use it for partial encryption. If you pass `cipherKey` as an argument, it overrides the `CryptoModule` configuration and the legacy encryption with 128-bit cipher key entropy is used.
:::

#### Method(s)

To `encrypt` the file you can use the following method(s) in C# SDK.

```csharp
pubnub.EncryptFile(sourceFile, destinationFile) 
pubnub.EncryptFile(sourceFile, destinationFile, cipherKey)
```

| Parameter | Description |
| --- | --- |
| `sourceFile` *Type: String | File to be encrypted. |
| `destinationFile` *Type: String | Path of the encrypted file to be saved. |
| cipherKeyType: String | Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the CryptoModule from PubNub config will be used. For more information, refer to Crypto module configuration. This parameter is deprecated and will be removed in a future version. Please use the `CryptoModule` from PubNub config instead. |

```csharp
byte[] outputBytes = pubnub.EncryptFile(sourceBytes) byte[] outputBytes = pubnub.EncryptFile(sourceBytes, cipherKey)
```

| Parameter | Description |
| --- | --- |
| `sourceBytes` *Type: byte[] | byte array of the file. |
| `cipherKey`Type: String | Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `CryptoModule` from PubNub config will be used. For more information, refer to [Crypto module configuration](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule). |

#### Sample code

```csharp
using PubnubApi;

// Configuration
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"))
{
    SubscribeKey = "demo",
    PublishKey = "demo",
    Secure = true
};

// Initialize PubNub
Pubnub pubnub = new Pubnub(pnConfiguration);
        
string source_file = "cat_picture.jpg"; // checks bin folder if no path is provided
string destination_file = "destination_cat_pic.jpg"; // checks bin folder if no path is provided
var crypto = PubnubApi.Security.Crypto.CryptoModule.CreateAesCbcCryptor("test");
crypto.EncryptFile(source_file, destination_file);
```

## Decryption methods

### Decrypt

Use this function to decrypt data.

:::warning Deprecated
The `cipherKey` parameter in this method is deprecated. We recommend that you configure a separate instance of the [CryptoModule](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule) and use it for partial encryption. If you pass `cipherKey` as an argument, it overrides the `CryptoModule` configuration and the legacy encryption with 128-bit cipher key entropy is used.
:::

#### Method(s)

To `decrypt` the data you can use the following method(s) in C# SDK.

```csharp
pubnub.Decrypt(inputString, cipherKey)
```

| Parameter | Description |
| --- | --- |
| `inputString` *Type: String | The `data` to `decrypt`. |
| cipherKeyType: String | Cipher key to use for encryption. This parameter is deprecated and will be removed in a future version. Please use the `CryptoModule` from PubNub config instead. |

#### Sample code

##### Decrypt part of message

```csharp
using PubnubApi;

// Configuration
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"))
{
    SubscribeKey = "demo",
    PublishKey = "demo",
    Secure = true
};

// Initialize PubNub
Pubnub pubnub = new Pubnub(pnConfiguration);
        
var crypto = PubnubApi.Security.Crypto.CryptoModule.CreateAesCbcCryptor("test");
crypto.Decrypt("encryptedString");
```

### Decrypt file

Use this function to decrypt file content.

#### Method(s)

To `decrypt` the file you can use the following method(s) in C# SDK.

```csharp
pubnub.DecryptFile(sourceFile, destinationFile); pubnub.DecryptFile(sourceFile, destinationFile, cipherKey);
```

| Parameter | Description |
| --- | --- |
| `sourceFile` *Type: String | File to be decrypted. |
| `destinationFile` *Type: String | Path of the decrypted file to be saved. |
| `cipherKey`Type: String | Cipher key to use for decryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `CryptoModule` from PubNub config will be used. For more information, refer to [Crypto module configuration](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule). |

```csharp
byte[] outputBytes = pubnub.DecryptFile(sourceBytes) byte[] outputBytes = pubnub.DecryptFile(sourceBytes, cipherKey)
```

| Parameter | Description |
| --- | --- |
| `sourceBytes` *Type: byte[] | byte array of the file. |
| `cipherKey`Type: String | Cipher key to use for decryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `CryptoModule` from PubNub config will be used. For more information, refer to [Crypto module configuration](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/configuration#cryptomodule). |

#### Sample code

```csharp
using PubnubApi;

// Configuration
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"))
{
    SubscribeKey = "demo",
    PublishKey = "demo",
    Secure = true
};

// Initialize PubNub
Pubnub pubnub = new Pubnub(pnConfiguration);
        
string source_file = "encrypted_cat_pic.jpg"; // checks bin folder if no path is provided
string destination_file = "cat_pic_original.jpg"; // checks bin folder if no path is provided
var crypto = PubnubApi.Security.Crypto.CryptoModule.CreateAesCbcCryptor("test");
crypto.DecryptFile(source_file, destination_file);
```

## Terms in this document

* **Publish Key** - A unique identifier that allows your application to send messages to PubNub channels. It's part of your app's credentials and should be kept secure.
* **Subscribe Key** - A unique identifier that allows your application to receive messages from PubNub channels. It's part of your app's credentials and should be kept secure.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.