# pool.dataset.encryption_summary

Retrieve summary of all encrypted roots under id.

Keys/passphrase can be supplied to check if the keys are valid.

Example output: [
  { “name”: “vol”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: true, “locked”: true, “unlock_error”: null, “unlock_successful”: true }, {

    “name”: “vol/c1/d1”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Provided key is invalid”, “unlock_successful”: false }, { “name”: “vol/c”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Key not provided”, “unlock_successful”: false }, { “name”: “vol/c/d2”, “key_format”: “PASSPHRASE”, “key_present_in_database”: false, “valid_key”: false, “locked”: true, “unlock_error”: “Child cannot be unlocked when parent “vol/c” is locked and provided key is invalid”, “unlock_successful”: false }

]

This method is a job.

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: id

#### id

Type: string

The dataset ID (full path) to generate an encryption summary for.

##### Parameter 2: options

#### options

Type: object

Options for generating the encryption summary including force settings and datasets.

No Additional Properties

##

#### Key File

Type: boolean Default: false

Whether keys are provided via key files rather than directly.

##

#### Force

Type: boolean Default: false

Force unlock operations even if mount paths already exist.

##

#### Datasets

Type: array of object Default: []

Array of dataset-specific unlock options and credentials.

No Additional Items

##### Each item of this array must be:

#### PoolDatasetEncryptionSummaryOptionsDataset

Type: object
No Additional Properties

##

#### Force

Type: boolean Default: false

Force unlock even if the mount path already exists and is not empty.

##

#### Name

Type: string

The dataset name to unlock.

Must be at least `1` characters long

##

#### Key

Type: string

Raw hex-encoded encryption key for this dataset.

Must be at least `64` characters long

Must be at most `64` characters long

##

#### Passphrase

Type: string

Passphrase for this dataset if using passphrase-based encryption.

Must be at least `1` characters long

##

#### Result

Type: array of object

Array of encryption status information for datasets that would be affected by an unlock operation.

No Additional Items

##### Each item of this array must be:

#### PoolDatasetEncryptionSummary

Type: object

There are 2 keys which show if a recursive unlock operation is done for `id`, which dataset will be unlocked and if not why it won't be unlocked. The keys namely are `unlock_successful` and `unlock_error`. The former is a boolean value showing if unlock would succeed/fail. The latter is description why it failed if it failed.

In some cases it's possible that the provided key/passphrase is valid but the path where the dataset is supposed to be mounted after being unlocked already exists and is not empty. In this case, unlock operation would fail and `unlock_error` will reflect this error appropriately. This can be overridden by setting `options.datasets.X.force` boolean flag or by setting `options.force` flag. In practice, when the dataset is going to be unlocked and these flags have been provided to `pool.dataset.unlock`, system will rename the directory/file path where the dataset should be mounted resulting in successful unlock of the dataset.

If a dataset is already unlocked, it will show up as true for "unlocksuccessful" regardless of what key user provided as the unlock keys in the output are to reflect what a real unlock operation would behave. If user is interested in seeing if a provided key is valid or not, then the key to look out for in the output is "validkey" which based on what system has in database or if a user provided one, validates the key and sets a boolean value for the dataset.

No Additional Properties

##

#### Name

Type: string

The dataset name.

##

#### Key Format

Type: string

The format of the encryption key (hex, raw, or passphrase).

##

#### Key Present In Database

Type: boolean

Whether an encryption key for this dataset exists in the system database.

##

#### Valid Key

Type: boolean

Whether the provided key is valid for this dataset.

##

#### Locked

Type: boolean

Whether the dataset is currently locked.

##

#### Unlock Error

Error message if unlock would fail, or `null` if unlock would succeed.

## Any of

Type: string
Type: null

##

#### Unlock Successful

Type: boolean

Whether an unlock operation would be successful.

Required roles: DATASET_READ