Document

Encrypted documents give your application the ability to keep information secure no matter where it lives. Your users data is encrypted end-to-end until it gets to your user's device. Manage all of the encrypted content in your application with the document namespace.

Note: The SDK must be initialized before these methods can be called.

document.list()

IronWeb.document.list()

Retrieve a list of documents that the logged in user has access to decrypt. The method lists all documents no matter where those documents are stored.

Parameters

None

Response

Returns a Promise that resolves with the list of documents the authenticated 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()

IronWeb.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()

IronWeb.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 string Content of encrypted document from which to retrieve ID. Should be the value returned from calling the encrypt() operation.

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.encrypt()

IronWeb.document.encrypt(documentData, [options])

Encrypt the provided document content as bytes and return the encrypted content to be stored by the consuming application. 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 Uint8Array Data to encrypt; should be formatted as bytes. See [codec.utf8.toBytes](./codec) function for more details.
[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 Base64 string form as well as metadata about the newly created document.

{
    "documentID": string,
    "documentName": string | null,
    //Encrypted document content in Base64 string form
    "document": string
}

document.encryptToStore()

IronWeb.document.encryptToStore(documentData, [options])

Encrypt the provided bytes and store them within the IronCore secure store. 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 Uint8Array Bytes of data to encrypt.
[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 who are granted access to the document 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 when the encrypted document content is successfully stored. Resolves with metadata information about the new document.

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

document.decrypt()

IronWeb.document.decrypt(documentID, encryptedDocument)

Decrypt the provided document given its ID and the encrypted content that was returned from the encrypt operation. The decrypted content is returned in byte form.

Parameters

Parameter Name Value Description
documentID string ID of the document.
encryptedDocument string Content of the document to decrypt. Should be the value of the encrypted content that was returned after calling the encrypt operation.

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": Uint8Array,
    //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.decryptFromStore()

IronWeb.document.decryptFromStore(documentID)

Decrypt the document provided by the document ID where the encrypted document data is stored within the secure IronCore store.

Parameters

Parameter Name Value Description
documentID string ID of the document.

Response

Returns a Promise which resolves with the decrypted content of the document in byte form as well as various other metadata fields.

{
    "documentID": string,
    "documentName": string | null,
    //Decrypted document byte content
    "data": Uint8Array,
    //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.updateEncryptedData()

IronWeb.document.updateEncryptedData(documentID, newDocumentData)

Update the encrypted content of an existing document where the encrypted data is stored by the consuming application. 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 Uint8Array Updated document byte content to encrypt.

Response

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

{
    "documentID": string,
    "documentName": string | null,
    //Updated encrypted document content in Base64 string form
    "document": string
}

document.updateEncryptedDataInStore()

IronWeb.document.updateEncryptedDataInStore(documentID, newDocumentData)

Update the encrypted content of an existing document that is stored within the IronCore secure store. The document will still be able to be decrypted by all users and groups who have access.

Parameters

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

Response

Returns a Promise that resolves when the updated encrypted document content is successfully stored. Returns metadata information about the updated document.

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

document.updateName()

IronWeb.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()

IronWeb.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. Granting access works the same regardless of where the document data is stored.

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()

IronWeb.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. Revoking access works the same regardless of where the document data is stored.

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
        }
    ]
}