Document

Encrypted documents give your application the ability to keep information secure no matter where it lives. Manage all of the encrypted content in your application using methods found in the document namespace. The SDK object in the examples below refers to the object that is returned once the initialization Promise has been resolved.

document.list()

SDK.document.list()

Retrieve a list of documents that the user has access to decrypt.

Parameters

None

Response

Returns a Promise that resolves with the list of documents the user is able to decrypt:

JSON

{
    "result": [
        {
            "documentID": string,
            "documentName": string | null,
            "created": string,
            "updated": string,
            //Denotes how the user has access to the document.
            "association": "owner" | "fromUser" | "fromGroup"
        }
    ]
}

document.getMetadata()

SDK.document.getMetadata(documentID)

Retrieves metadata about the provided document ID. Does not return or decrypt any of the document data. However, the requesting user must have the ability to decrypt the document before they are allowed to retrieve its metadata.

Parameters

Response

Returns a Promise that will resolve with metadata about the requested document.

JSON

{
    "result": [
        {
            "documentID": string,
            "documentName": string | null,
            "created": string,
            "updated": string,
            //Denotes how the user has access to the document.
            "association": "owner" | "fromUser" | "fromGroup",
            //List of users and groups who have access to decrypt this document
            "visibleTo": [
                {
                    "users": [{"id": string}],
                    "groups": [{"id": string, "name": string | undefined}]
                }
            ]
        }
    ]
}

document.getDocumentIDFromBytes()

SDK.document.getDocumentIDFromBytes(encryptedDocument)

Attempts to retrieve and return the document ID from the encrypted document metadata. Not all versions of encrypted documents have the ID embedded within the metadata, so if the provided document is an older version then null will be returned.

Parameters

Response

Returns a Promise that will resolve with either the string document ID or null if the encrypted document is from a prior version where the ID isn’t embedded within the document.

document.getDocumentIDFromStream()

SDK.document.getDocumentIDFromStream(inputStream)

Attempts to retrieve and return the document ID from the encrypted document metadata. Not all versions of encrypted documents have the ID embedded within the metadata, so if the provided document is an older version then null will be returned. Only the minimum amount of bytes will be read from this stream to retrieve the ID.

Parameters

Response

Returns a Promise that will resolve with either the string document ID or null if the encrypted document is from a prior version where the ID isn’t embedded within the document.

document.encryptBytes()

SDK.document.encryptBytes(documentData, [options])

Encrypt the provided document content as bytes and return the encrypted content. This method should only be called when encrypting a new document and not when updating an existing document. Also allows granting access to decrypt the document to other users and groups.

Parameters

Response

Returns a Promise which resolves with the encrypted document content in a Buffer as well as metadata about the newly created document.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string,
    //Encrypted document bytes
    "document": Buffer
}

document.encryptStream()

SDK.document.encryptStream(inputStream, outputStream, [options])

Encrypt the provided ReadableStream and write the results to the provided WritableStream. Streaming encryption is useful for when the document that you’re encrypting is large enough that fitting it into memory via the encryptBytes function isn’t feasible.

This method should only be called when encrypting a new document and not when updating an existing document. Also allows granting access to decrypt the document to other users and groups.

Parameters

Response

Returns a Promise which resolves with the details about the newly created document. The Promise will resolve once all encrypted data has successfully been written to the provided WritableStream.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string
}

Example

The following example shows how to use the IronNode SDK to encrypt a file and write it out to another file location.

JavaScript

const IronNode = require("@ironcorelabs/ironnode");
const fs = require("fs");

IronNode.initialize(...)
    .then((SDK) => {
        return SDK.document.encryptStream(
            fs.createReadStream("./path/to/file"),
            fs.createWriteStream("./path/to/file.enc"),
            {
                documentName: "Encrypted File"
            }
        );
    })
    .then((documentDetails) => {
        //Encrypted document content successfully written to output file (./path/to/file.enc)
    });

document.decryptBytes()

SDK.document.decryptBytes(documentID, encryptedDocument)

Decrypt the provided document given its ID and the encrypted content. The decrypted content is returned in byte form.

Parameters

Response

Returns a Promise that resolves with the decrypted content of the document in byte form as well as document details in the metadata fields.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string,
    //Decrypted document byte content
    "data": Buffer,
    //Denotes how the user has access to the document.
    "association": "owner" | "fromUser" | "fromGroup",
    //List of users and groups who have access to decrypt this document
    "visibleTo": [
        {
            "users": [{"id": string}],
            "groups": [{"id": string, "name": string | undefined}]
        }
    ]
}

document.updateEncryptedBytes()

SDK.document.updateEncryptedBytes(documentID, newDocumentData)

Update the encrypted content of an existing document. The document will still be able to be decrypted by all users and groups who have been granted access.

Parameters

Response

Returns a Promise which resolves with the updated encrypted document as well as metadata about the existing document.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string,
    //Updated encrypted document content
    "document": Buffer
}

document.updateEncryptedStream()

SDK.document.updateEncryptedStream(documentID, inputStream, outputStream)

Update the encrypted content of an existing document by encrypting the provided stream and writing the results to the provided output stream. The document will still be able to be decrypted by all users and groups who have been granted access.

Parameters

Response

Returns a Promise which resolves with metadata about the existing document. The Promise will resolve once all encrypted data has successfully been written to the provided WritableStream.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string
}

document.updateName()

SDK.document.updateName(documentID, documentName)

Update the name of a document or clear its existing value.

Parameters

Response

Returns a Promise which resolves with updated document metadata.

JSON

{
    "documentID": string,
    "documentName": string | null,
    "created": string,
    "updated": string
}

document.grantAccess()

SDK.document.grantAccess(documentID, {users: grantList, groups: grantList})

Grant other users and/or groups access to decrypt the provided document given its ID. Users will also be able to update document content. Document access can only be granted to a group that the calling user is a member of.

Parameters

Response

Returns a Promise that resolves with the list of users and groups who were successfully granted access and the users and groups whose access failed to be granted.

JSON

{
    "succeeded": [
        {
            "id": string,
            "type": "user" | "group"
        }
    ],
    "failed": [
        {
            "id": string,
            "type": "user" | "group",
            "error": string
        }
    ]
}

document.revokeAccess()

SDK.document.revokeAccess(documentID, {users: revokeList, groups: revokeList})

Revoke decryption access to the provided document from the provided list of users and/or groups. Document access can only be revoked from any user or group if the calling user is the document author. If the calling user is not the document author, they can only revoke access from users or groups where they were responsible for granting access in the first place.

Parameters

Response

If successful, this method returns a Promise that resolves with the list of users and groups whose access was successfully revoked or failed with the following structure:

JSON

{
    "succeeded": [
        {
            "id": string,
            "type": "user" | "group"
        }
    ],
    "failed": [
        {
            "id": string,
            "type": "user" | "group",
            "error": string
        }
    ]
}