Sqlite.rekey Action

Format

CS.Sqlite.rekey(dbId := ..., encryptionKey := ...ʃ, encryptionKeyFormat := ...ʅ)

Argument	Description	Types / Required
dbId	The resource ID returned by Sqlite.open.	number not required
encryptionKey	The new encryption key, or a blank string to remove the encryption.	string required
encryptionKeyFormat	The format of encryptionKey. The default value is "autodetect".	string not required

Description

The Sqlite.rekey action changes, removes, or adds an encryption key to a SQLite database previously opened by Sqlite.open. Only databases opened using the path argument can be rekeyed. The dbId resource ID must be specified explicitly when using multiple databases in a single execution environment.

The encryptionKey argument specifies the new key, with the optional encryptionKeyFormat argument indicating how to process the encryptionKey argument. If rekeying a database to make it openable as an Encrypted CSPro DB data source, you can use the Hash.createHash action to convert a password into the encryption key necessary to rekey the database. If encryptionKey is a blank string, any encryption on the database is removed.

Further information about rekeying databases is available on the SQLite website: sqlite3_rekey.

Return Value

The action returns undefined.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form, or if:

The database ID is not valid.
The database was opened using name, meaning that it is a data source or paradata log.
The database could not be rekeyed.

Example (JavaScript)

This example shows how you can take an Encrypted CSPro DB data source and remove the encryption to turn it into a CSPro DB data source.

let dbId;

try {
const inputPath = "Popstan Census (encrypted).csdbe";
const outputPath = "Popstan Census (no encryption).csdb";
const password = "my-password";

// create a copy of the data source
const inputBytes = CS.File.copy({
source: inputPath,
destination: outputPath
});

// hash the password to get the encryption key used for Encrypted CSPro DB data sources
const passwordHash = CS.Hash.createHash({
text: password,
type: "EncryptedCSProDB"
});

// open the database with the encryption key, which is returned in hexadecimal format by Hash.createHash
const dbId = CS.Sqlite.open({
path: outputPath,
openFlags: "readWrite",
encryptionKey: passwordHash,
encryptionKeyFormat: "hex"
});

// remove the encryption
CS.Sqlite.rekey({
dbId: dbId,
encryptionKey: ""
});

print("Success!");
}
catch(error) {
print("Error removing encryption from Encrypted CSPro DB: " + error);
}
finally {
// close the database, suppressing any errors
try {
CS.Sqlite.close({
dbId: dbId
});
}
catch {
}
}