# File encryption

To encrypt & decrypt files, you can use:

For use of the EncryptionSession#encryptFile and EncryptionSession#decryptFile methods, refer to the dedicated section of the EncryptionSession guide.

# Format of an encrypted file

A file encrypted with Seald consists of two parts:

  • a header containing the identifier of the EncryptionSession;
  • the result of the encryption with the key of the EncryptionSession of a tar (opens new window) containing the file to be encrypted.

Thus the encrypted file is slightly larger than the original file, by about 2 kB.

# Function description

# encryptFile

The encryptFile method has 4 arguments: clearFile, filename, recipients and opts.

It returns a Promise which resolves to the same type as used for clearFile.

# clearFile: the file to encrypt

encryptFile supports several types for clearFile and returns the result with the same type:

Examples of use with these different types are available at the end of this page.

# filename: the name of the file

This is a String which is used to:

  1. be the default metadata of the EncryptionSession that will be created;
  2. be registered as the name of the file to be encrypted in the tar described above.

TIP

The filename is not available at decryption, it will be in a future update.

# recipients: users authorized to decrypt

This is an object with two properties describing the users authorized to decrypt:

  • userIds: an array containing user IDs in your application as declared during the generation of identities;
  • sealdIds: an array containing internal Seald identifiers, this is especially useful to encrypt for a groupId.

TIP

It is possible to encrypt for a userId that has not yet created a Seald identity if opts.allowUnregisteredUsers is set to true.

In this case, it is not end-to-end encryption: the plaintext encryption key is sequestered on the Seald servers until a Seald identity is created and associated to this userId.

# opts: options

This is an object with several optional properties. Three of them are of interest (to see the full list, see the reference):

  • fileSize: size of the file to be encrypted, required for use with the ReadableStream and Readable types.
  • metadata: the metadata of the EncryptionSession that will be created (the default is the value of filename).
  • encryptForSelf: if you are encrypting for a group of which the user is a member, you can set it to false so that you do not encrypt directly for their own identities. The user will still be able to decrypt the data thanks to their group membership. This can allow you to improve the performance of the encryption, and save keys from your quota.

# decryptFile

The decryptFile method has a single argument: encryptedFile, the file to be decrypted.

decryptFile supports the same types for encryptedFile as encryptFile does for clearFile.

It returns a Promise which resolves to an Object with the following properties:

  • data: the decrypted file, is of the same type as used for encryptedFile;
  • type: one of 'string', 'buffer', 'node-stream', 'blob', 'readable-stream';
  • filename: the original file name;
  • size: the file size in bytes;
  • sessionId: the EncryptionSession's identifier.

# Examples

# With String

The simplest signature to encrypt a file is with a String:

In this case, the output type will be a base64 encoded String of the encrypted file. It will then be possible to decrypt it as follows:

info

The content of clearFile is interpreted as utf-8.

TIP

If only text is to be encrypted, it is recommended to use the other encryption format: encryptMessage / decryptMessage which is much lighter.

WARNING

The output of encryptFile used with a String is about 33% heavier than the original file due to the base64 encoding.

# With Buffer

The SDK can use Buffer in the sense of Node.js (which are polyfilled outside of a Node.js environment (opens new window)):

In this case, the output type will be a Buffer. It will then be possible to decrypt it in the following way:

# With Blob

In a browser, the SDK can use Blob:

In this case, the output type will be a Blob. It will then be possible to decrypt it in the following way:

TIP

The files obtained through fields <input type="file"> are of type File which inherits from Blob. They are therefore treated in the same way by the SDK.

The decrypted Blob has no Blob#type set but it can be inferred from the file extension (using the mime-types package for example (opens new window)).

You can also re-create an instance of File using its constructor (opens new window) from the decrypted Blob and the filename (and optionally the inferred mime type).

WARNING

Since React-Native does not implement the Blob#arrayBuffer or Blob#stream methods, even though they are standard, it is not possible to use the Blob type in a React-Native environment. It is necessary to use another type (like Buffer using a polyfill or String).

# With ReadableStream

In a browser, the SDK can use ReadableStream. For example, with the method Blob#stream (opens new window):

WARNING

In this mode, the encryptFile function must be given the size of the plaintext file via the options.fileSize parameter.

In this case, the output type will be a ReadableStream. It will then be possible to decrypt it in the following way:

# Stream a file upload

Except on Chrome since version 95 (opens new window), it is not possible to use fetch with a ReadableStream as a request body.

To work around this, a solution is to split the encrypted file on the client side into chunks of e.g. 5MB, send them individually to the server, and the server will be responsible for reconstructing the different chunks in order.

# With Node.js' Readable streams

The SDK can use Readable streams from Node.js. In a browser, this also works if you use a polyfill (opens new window). For example, to read & encrypt a file then write it:

WARNING

In this mode, the encryptFile function must be given the size of the plaintext file via the options.fileSize parameter.

It will then be possible to decrypt it in the following way: