Get Started
Usage API
More information

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.

  1. 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}"
    },
    ...
}));

  2. 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"
}
    Parameters
    Name Description Type Example
    Defines the cloud name and the cloud entry point. string "https://exampledomain.com"
    Defines the user email entered on the login page. string "john@example.com"
    Defines the password entered on the login page. string "123456"
    Example
    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.

  3. 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"
}
    Parameters
    Name Description Type Example
    Defines the Encryption plugin ID. string "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}"
    Defines the encrypted private key. string "xxx"
    Defines the public key. string "yyy"
    Example
    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"
        },
        ...
    },
    ...
});

  4. 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);
    ...
}

  5. 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);

  6. Send the generated keys to the cloud through the cloudCryptoCommand method with the encryptionKeys type:

    window.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)
Parameters
Name Description Type

Defines the command type:

  • encryptionKeys - to save private and public keys to the params,
  • updateEncryptionKeys - to save private and public keys to the params forcely updating the existing keys with them,
  • 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
Defines the parameters that are passed to the method. string
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:

Parameters
Name Description Type Example
Defines the Encryption plugin ID. string "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}"
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.
Example
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:

Parameters
Name Description Type Example
Defines the Encryption plugin ID. string "{FFF0E1EB-13DB-4678-B67D-FF0A41DBBCEF}"
Defines the absolute url to the document. string "https://example.com/url-to-example-document.docx"
Defines the pairs of user ids and associated public keys. array [{"userId":"78e1e841","publicKey":"yyy"}, ...]
Example
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\
© Ascensio System SIA 2021. All rights reserved