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 with 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:

{
    "result": [
        {
            "documentID": string,
            "documentName": string | null,
            //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

Parameter Name Value Description
documentID string ID of the document.

Response

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

{
    "result": [
        {
            "documentID": string,
            "documentName": string | null,
            //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

Parameter Name Value Description
encryptedDocument Buffer Byte content of encrypted document from which to retrieve ID.

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

Parameter Name Value Description
inputStream ReadableStream A Node Readable Stream.

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

Parameter Name Value Description
documentData Buffer Data to encrypt; should be formatted as bytes.
[options.documentID] string Optional unique ID used to identify the document being encrypted; should be unique across the entire Segment if it's provided. If a Document ID is not provided a unique ID will be generated for you and used to identify the document in later operations.
[options.documentName] string Optional name to provide for the document. This data is stored unencrypted.
[options.accessList.users] Array<{}> List of users to grant decryption access to upon creation. List items are in the form {'id': string}. Users can decrypt and update the document content.
[options.accessList.groups] Array<{}> List of groups to grant decryption access to upon creation. List items are in the form {'id': string}. Users who are members of the provided groups can decrypt and update the document content.

Response

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

{
    "documentID": string,
    "documentName": string | null,
    //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

Parameter Name Value Description
inputStream ReadableStream A Node Readable Stream.
outputStream WritableStream A Node Writable Stream.
[options.documentID] string Optional unique ID used to identify the document to encrypt; should be unique across the entire Segment if it's provided. If a Document ID is not provided a unique ID will be provided for you and used to identify the document in later operations.
[options.documentName] string Optional name to provide for the document. This data is stored unencrypted.
[options.accessList.users] Array<{}> List of users to grant decryption access to upon creation. List items are in the form {'id': string}. Users can decrypt and update the document content.
[options.accessList.groups] Array<{}> List of groups to grant decryption access to upon creation. List items are in the form {'id': string}. Users who are members of the provided groups can decrypt and update the document content.

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.

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

Example

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

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

Parameter Name Value Description
documentID string ID of the document.
encryptedDocument Buffer Byte content of the document to decrypt.

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.

{
    "documentID": string,
    "documentName": string | null,
    //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

Parameter Name Value Description
documentID string ID of the document.
newDocumentData Buffer Updated document byte content to encrypt.

Response

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

{
    "documentID": string,
    "documentName": string | null,
    //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

Parameter Name Value Description
documentID string ID of the document.
inputStream ReadableStream A Node Readable Stream.
outputStream WritableStream A Node Writable Stream.

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.

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

document.updateName()

SDK.document.updateName(documentID, documentName)

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

Parameters

Parameter Name Value Description
documentID string ID of the document.
documentName string|null Updated name of the document. Send in `null` to clear a stored name from a document. Document names are stored unencrypted.

Response

Returns a Promise which resolves with updated document metadata.

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

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

Parameter Name Value Description
documentID string ID of the document.
users.grantList Array<{}> List of users to grant decryption access. List items are in the form {'id': string}. Users who are granted decryption access to the document can also update the document content.
groups.grantList Array<{}> List of groups to grant decryption access. List items are in the form {'id': string}. Users who are members of the provided groups will be able to decrypt and update the document content. Document access can only be granted to groups where the calling user is a member.

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.

{
    "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

Parameter Name Value Description
documentID string ID of the document.
users.revokeList Array<{}> List of users to revoke decryption access. List items are in the form {'id': string}.
groups.revokeList Array<{}> List of groups to revoke decryption access. List items are in the form {'id': string}.

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:

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