Encryption
Starting from version 5.6, ONLYOFFICE Desktop Editors offers support for Private Rooms, secure workspace where every symbol you type is encrypted end-to-end even
if you co-edit documents in real time. Using ONLYOFFICE Desktop Editors makes it possible to encrypt and decrypt the data on the client, ensuring endpoint security.
To check if the desktop app supports encryption, call the following command:
typeof window.AscDesktopEditor.cloudCryptoCommand === "function"
How it works
The steps below explain the process of document encryption in ONLYOFFICE.
-
Log in to the cloud and pass the Encryption plugin ID:
window.AscDesktopEditor.execCommand("portal:login", JSON.stringify({
"encryptionKeys": {
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}"
},
...
}));
-
To monitor the password from the login page, send the desktop editors the portal:checkpwd command through the execCommand method.
Parameters are specified in the format of a string with the serialized json as follows:
{
"domain": "domain name",
"emailInput": "user@email.addr",
"pwdInput": "pwd"
}
Name |
Description |
Type |
Example |
domain |
Defines the cloud name and the cloud entry point.
|
string |
"https://exampledomain.com" |
emailInput |
Defines the user email entered on the login page.
|
string |
"john@example.com" |
pwdInput |
Defines the password entered on the login page.
|
string |
"123456" |
window.AscDesktopEditor.execCommand("portal:checkpwd", JSON.stringify({
"domain": "https://exampledomain.com",
"emailInput": "john@example.com",
"pwdInput": "123456"
}));
When the command is sent, the DMS provider transfers the information about the password from the login page to the desktop app.
ONLYOFFICE Desktop Editors remembers the password and uses it for the key encryption and decryption.
-
Pass the encrypted private and public keys with the login from the DMS provider to the desktop application with the following parameters:
"encryptionKeys": {
"cryptoEngineId": "guid",
"privateKeyEnc": "private key",
"publicKey": "public key"
}
Name |
Description |
Type |
Example |
cryptoEngineId |
Defines the Encryption plugin ID.
|
string |
"{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}" |
privateKeyEnc |
Defines the encrypted private key.
|
string |
"xxx" |
publicKey |
Defines the public key.
|
string |
"yyy" |
window.AscDesktopEditor.execCommand("portal:login", JSON.stringify({
"encryptionKeys": {
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}",
"privateKeyEnc": "xxx",
"publicKey": "yyy"
},
...
}));
You can also do it in the editor initialization config:
new DocsAPI.DocEditor("placeholder", {
"editorConfig": {
"encryptionKeys": {
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}",
"privateKeyEnc": "xxx",
"publicKey": "yyy"
},
...
},
...
});
-
If there are no keys in the DMS, then the desktop application generates them with the Encryption plugin.
To generate the RSA keys, the NSOpenSSL::RSA_GenerateKeys method is used:
if (info.PrivateKeyEnc.empty() && info.PublicKey.empty())
{
unsigned char* publicKey = NULL;
unsigned char* privateKey = NULL;
NSOpenSSL::RSA_GenerateKeys(publicKey, privateKey);
...
}
-
To encrypt the private key before saving it to the database, ONLYOFFICE uses the NSOpenSSL::AES_Encrypt_desktop algorithm based on AES 256 Cipher Block Chaining:
std::string privateEnc;
NSOpenSSL::AES_Encrypt_desktop(U_TO_UTF8(tmpInfo->m_sPassword), sPrivate, privateEnc, CAscRendererProcessParams::getInstance().GetProperty("user"));
info.PrivateKeyEnc = NSFile::CUtf8Converter::GetUnicodeFromCharPtr(privateEnc);
-
Send the generated keys to the cloud through the cloudCryptoCommand method with the encryptionKeys type:
window.AscDesktopEditor.cloudCryptoCommand(
"encryptionKeys",
{
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}",
"privateKeyEnc": "xxx",
"publicKey": "yyy"
},
callback)
Processing desktop editors commands
Declare the cloudCryptoCommand function to process messages from the desktop app:
window.cloudCryptoCommand = function (type, params, callback)
Name |
Description |
Type |
type |
Defines the command type:
- encryptionKeys - to save private and public keys to the params,
- relogin - to re-enter the portal after unsuccessful keys decryption,
- getsharingkeys - to request for the public keys of all the users who have access to the file. The keys will be transferred via callback:
callback({"keys":[{"userId":"78e1e841","publicKey":"yyy"}, ...]})
|
string |
params |
Defines the parameters that are passed to the method.
|
string |
callback |
Defines the result that the method returns.
|
string |
Operations with encrypted files
To perform operations with encrypted files, including file encryption, decryption, creation, editing and sharing, ONLYOFFICE uses the individual credentials of users
(RSA key pair) and a document password (document encryption key).
The encrypted files, besides the ciphertext itself, contain the arrays of public keys of all users and the document passwords encrypted with these keys.
This makes it possible to establish collective access to the file, and therefore enable sharing and collaboration on the encrypted documents.
Uploading encrypted documents
To upload encrypted files in the desktop app, replace the standard input type = file call with the cloudCryptoCommand function with the upload type.
The params object has the following values:
Name |
Description |
Type |
Example |
cryptoEngineId |
Defines the Encryption plugin ID.
|
string |
"{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}" |
filter |
Defines the document types that can be encrypted.
|
string |
"*.docx *.xlsx *.pptx" |
Currently, it is possible to encrypt only OOXML formats, which are DOCX, XLSX, and PPTX.
|
window.AscDesktopEditor.cloudCryptoCommand("upload", {
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}",
"filter": "*.docx *.xlsx *.pptx"
},
callback)
After the user chooses the files, they will be encrypted in a loop and transferred to callback:
callback({
"bytes": [...],
"name": "Example Document Title.docx",
"isCrypto": true
})
Sharing encrypted documents
To share the encrypted document, call the cloudCryptoCommand function with the share type. The params object has the following values:
Name |
Description |
Type |
Example |
cryptoEngineId |
Defines the Encryption plugin ID.
|
string |
"{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}" |
file |
Defines the absolute url to the document.
|
string |
"https://example.com/url-to-example-document.docx" |
keys |
Defines the pairs of user ids and associated public keys.
|
array |
[{"userId":"78e1e841","publicKey":"yyy"}, ...] |
window.AscDesktopEditor.cloudCryptoCommand("share",
{
"cryptoEngineId": "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}",
"file": ["https://example.com/url-to-example-document.docx" ],
"keys":[{"userId":"78e1e841","publicKey":"yyy"}, ...]
},
callback)
The file is uploaded by the desktop app and encrypted. The access rights to the file are transferred to it with keys. After that, it is transmitted to callback:
callback({
"bytes": [...],
"isCrypto": true
})
Data location
ONLYOFFICE leverages data storage for documents and the encrypted data between the cloud storage and the user’s local storage to maintain the applied scheme.
The distribution of data looks as follows:
Item |
Location within the instance |
Location on device |
Private key |
Encrypted, in the Database |
- |
Public key |
Database and within encrypted files (in the file system) |
- |
File encryption key |
Encrypted, within the encrypted files (in the file system) |
- |
User password |
- |
- |
Encrypted files at rest |
On the server |
- |
Encrypted files when editing |
- |
On machine, in temporary folder |
Removing keys
The desktop application stores all the read keys. To reset them and add new ones, please do the following:
- delete keys in the DMS database;
- delete the cloud_crypto.xml file from the sdkjs-plugins directory. The path to the folder depends on the operating system you use:
- For Linux - /opt/onlyoffice/desktopeditors/editors/sdkjs-plugins/
- For Windows - %ProgramFiles%\ONLYOFFICE\DesktopEditors\sdkjs-plugins\