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, from the point where the data was initially generated until it gets to your user’s device to be used. The methods to manage all of the encrypted content in your application are found in 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:

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

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

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

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

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

Response

Returns a Promise which resolves with the encrypted document content in a Uint8Array as well as metadata about the newly created document. See codec.base64.fromBytes if you need a stringy byte representation.

JSON

{
	"documentID": string,
	"documentName": string | null,
	"created": string,
	"updated": string,
	//Encrypted document content in a Uint8Array
	"document": Uint8Array
}

document.encryptToStore()

DEPRECATED 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

Response

Returns a Promise which resolves when the encrypted document content is successfully stored. Resolves with metadata information about the new document.

JSON

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

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

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

DEPRECATED 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

Response

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

JSON

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

Response

Returns a Promise which resolves with the updated encrypted document in a Uint8Array as well as metadata about the existing document. See codec.base64.fromBytes if you need a stringy byte representation.

JSON

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

document.updateEncryptedDataInStore()

DEPRECATED 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

Response

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

JSON

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

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.

JSON

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

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.

JSON

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

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

Document Advanced

The document.advanced namespace contains methods that allow for more advanced use cases of the IronWeb SDK. Most users won’t have need for these methods but they are provided for more complex scenarios that require extra work from the caller.

The main purpose of the document.advanced namespace is for methods that allow callers to manage their own encrypted document encryption keys (EDEKs). With all the other IronWeb methods, the EDEKs are generated and hosted within the IronCore service. These methods, however, require the caller to store and retrieve the EDEKs whenever they create a new document or update access information for a document.

document.advanced.encryptUnmanaged()

IronWeb.document.advanced.encryptUnmanaged(plaintext, options)

Encrypt the provided plaintext document bytes with various document create options. Does not store any part of the document within IronCore and instead returns the encrypted DEKs to the caller. These encrypted DEKs must be then be provided as input in order to decrypt the document.

Parameters

Response

If successful, this method returns a Promise that resolves with the encrypted document bytes as well as the list of EDEKs for the document. Both of these values must be provided when performing unmanaged decryption of this document.

JSON

{
	"documentID": string,
	"document": Uint8Array,
	"edeks": Uint8Array,
}

document.advanced.decryptUnmanaged()

IronWeb.document.advanced.decryptUnmanaged(ciphertext, edeks)

Decrypt the provided ciphertext document using the provided edeks list. The decrypted content is returned in byte form.

Parameters

Response

If successful, this method returns a Promise that resolves with information about the decrypted document along with the decrypted document bytes.

JSON

{
	"documentID": string,
	"data": Uint8Array,
	"accessVia": {
	  "type": "user" | "group",
	  "id": string,
	}
}