Encryption API: deprecated encrypt() and decrypt() methods and cipher key arguments for JavaScript SDK
This page documents the deprecated pubnub.encrypt() and pubnub.decrypt() methods of the PubNub JavaScript SDK. It also documents the customCipherKey and key arguments of encrypt(), decrypt(), encryptFile(), and decryptFile(). Encryption is a current API. The two methods log a deprecation warning on every call, and the cipher key arguments are an older way to call it. All of them still work.
New apps configure the cryptoModule. To protect only part of a message, call encrypt() and decrypt() on a separate CryptoModule instance. See Encryption and Configuration.
Relationship between cryptoModule and cipher keys
A cipher key that you pass to a method overrides the configured crypto module for that operation and uses the legacy encryption with 128-bit cipher-key entropy. If SDK configuration sets a cipherKey without an explicit CryptoModule, the SDK defaults to legacy 128-bit encryption. To encrypt only part of your data, create a separate cryptoModule instance and use it where needed, as shown in Encrypt part of a message.
Encrypt
encrypt() encrypts data with a crypto module in the PubNub SDK for JavaScript.
pubnub.encrypt() is deprecated. Each call logs the warning 'encrypt' is deprecated. Use cryptoModule instead. To encrypt part of a message, see Encrypt part of a message.
Method(s)
1pubnub.encrypt(data: string): string;
datarequired#- Data to encrypt. The configured
cryptoModuleencrypts strings. An object throws aTypeError, so callJSON.stringify()on it first.
Returns
Returns the encrypted data as a string.
Encrypt with a cipher key
encrypt() accepts customCipherKey as the second argument. With customCipherKey, the SDK uses the legacy encryption and ignores cryptoModule.
1pubnub.encrypt(data: string, customCipherKey?: string): string;
If no customCipherKey and no configured cipherKey apply, encrypt() returns data unchanged.
Decrypt
decrypt() decrypts data with a crypto module in the PubNub SDK for JavaScript.
pubnub.decrypt() is deprecated. Each call logs the warning 'decrypt' is deprecated. Use cryptoModule instead. To decrypt data that you encrypted with a separate crypto module instance, call decrypt() on the same instance. See Encrypt and decrypt a single item.
Method(s)
1pubnub.decrypt(data: string): Payload | null;
datarequired#- Encrypted data to decrypt. The SDK uses the
cryptoModulefrom the PubNub configuration. SeecryptoModule.
Sample code
1
Returns
Returns the decrypted data, parsed from JSON, as a Payload: a string, number, boolean, array, or object.
Error responses
If the cryptoModule cannot decrypt the data, decrypt() throws an Error that describes the reason, for example Decryption error: empty content.
Decrypt with a cipher key
decrypt() accepts customCipherKey as the second argument. With customCipherKey, the SDK uses the legacy encryption and ignores cryptoModule.
1pubnub.decrypt(data: string, customCipherKey?: string): Payload | null;
With the legacy encryption, a failed decryption does not throw. decrypt() logs the error and returns null. If no customCipherKey and no configured cipherKey apply, decrypt() returns data unchanged.
Encrypt file with a cipher key
encryptFile() accepts key as the first argument. With key, the SDK uses the legacy encryption and ignores cryptoModule.
1pubnub.encryptFile(key: string, file: PubNubFile): Promise<PubNubFile>;
The promise rejects with File encryption error. File encryption not available if the client has no legacy file encryption.
Decrypt file with a cipher key
decryptFile() accepts key as the first argument. With key, the SDK uses the legacy encryption and ignores cryptoModule.
1pubnub.decryptFile(key: string, file: PubNubFile): Promise<PubNubFile>;
The promise rejects with File decryption error. Crypto module not configured. if the client has no cryptoModule, even though the legacy decryption does not use it.