org.freedesktop.UDisks2.Encrypted: UDisks Reference Manual

## org.freedesktop.UDisks2.Encrypted org.freedesktop.UDisks2.Encrypted — Block device containing encrypted data |

## Methods

    Unlock           (IN  s     passphrase,
                      IN  a{sv} options,
                      OUT o     cleartext_device);
    Lock             (IN  a{sv} options);
    ChangePassphrase (IN  s     passphrase,
                      IN  s     new_passphrase,
                      IN  a{sv} options);
    Resize           (IN  t     size,
                      IN  a{sv} options);
    Convert          (IN  s     target_version,
                      IN  a{sv} options);
    HeaderBackup     (IN  s     backup_file,
                      IN  a{sv} options);

## Properties

    ChildConfiguration  readable   a(sa{sv})
    HintEncryptionType  readable   s
    MetadataSize        readable   t
    CleartextDevice     readable   o

## Description

This interface is used for org.freedesktop.UDisks2.Block devices that contain encrypted data.

## Method Details

### The Unlock() method

    Unlock (IN  s     passphrase,
            IN  a{sv} options,
            OUT o     cleartext_device);

Tries to unlock the encrypted device using `passphrase`.

If the device in question is referenced in a system-wide configuration file (such as the `/etc/crypttab` file), then name, options and passphrase (if available) is used from that file after requesting additional authorization.

If an empty passphrase should be used to unlock the device, it has to be passed using the `keyfile_contents` parameter. Empty string passed as `passphrase` means "Use the passphrase from the configuration file".

If the device is removed without being locked (e.g. the user yanking the device or pulling the media out) the cleartext device will be cleaned up.

`IN s `passphrase``: | The passphrase to use.
`IN a{sv} `options``: | Options - known options (in addition to standard options) includes `keyfile_contents` (of type 'ay') which is preferred over `passphrase` if specified and `read-only` (of type 'b').
`OUT o `cleartext_device``: | An object path to the unlocked object implementing the org.freedesktop.UDisks2.Block interface.

### The Lock() method

    Lock (IN  a{sv} options);

Locks the encrypted device.

`IN a{sv} `options``: | Options (currently unused except for standard options).

### The ChangePassphrase() method

    ChangePassphrase (IN  s     passphrase,
                      IN  s     new_passphrase,
                      IN  a{sv} options);

Changes the passphrase to `new_passphrase`. An existing passphrase is required.

If `old_keyfile_contents` or `new_keyfile_contents` are given, they take precedence over the corresponding passphrase parameters individually.

If the device in question is referenced in a system-wide configuration file (such as the `/etc/crypttab` file) and this configuration references the passphrase, it is not automatically updated.

`IN s `passphrase``: | The existing passphrase.
`IN s `new_passphrase``: | The new passphrase to use.
`IN a{sv} `options``: | Options - known options (in addition to standard options) includes `old_keyfile_contents` and `new_keyfile_contents` (of type 's' or 'ay').

### The Resize() method

    Resize (IN  t     size,
            IN  a{sv} options);

Resizes the encrypted device. The device must be unlocked. The given size is the target size for the cleartext device.

You need to specify either `passphrase` or `keyfile_contents` for LUKS 2 devices that don't have verified key loaded in kernel keyring.

`IN t `size``: | The target cleartext size in bytes, 0 for maximum.
`IN a{sv} `options``: | Options - known options (in addition to standard options) includes `passphrase` (of type 's') and `keyfile_contents` (of type 'ay') which is preferred over `passphrase` if specified.

Since 2.8.0

### The Convert() method

    Convert (IN  s     target_version,
             IN  a{sv} options);

Converts the encrypted device to a different version of LUKS. Other encryption formats are not supported. The device must be locked.

`IN s `target_version``: | The LUKS version to convert to. Either 'luks1' or 'luks2'.
`IN a{sv} `options``: | Options (currently unused except for standard options).

Since 2.11.0

### The HeaderBackup() method

    HeaderBackup (IN  s     backup_file,
                  IN  a{sv} options);

Saves header and keyslots to the specified file. The target file is not overwritten if exists, and an error is returned.

`IN s `backup_file``: | Path where to backup header and keyslots to.
`IN a{sv} `options``: | Options (currently unused except for standard options).

Since 2.11.0

## Property Details

### The "ChildConfiguration" property

    ChildConfiguration  readable   a(sa{sv})

Configuration items belonging to the

clear text device of this encrypted block device and its children. This is also valid when this block device is currently locked and there is no clear text device for it. It works via the 'track-parents' options of AddConfigurationItem(), which see.

### The "HintEncryptionType" property

    HintEncryptionType  readable   s

If not blank, the type of the encryption used to encrypt this device.

This is set during successful unlocking of an encrypted device. It is required for encryption types which can only be determined by decrypting the device (for example TCRYPT), but is used for all encryption types for consistency reasons.

### The "MetadataSize" property

    MetadataSize  readable   t

Size of the metadata on the encrypted device in bytes

### The "CleartextDevice" property

    CleartextDevice  readable   o

For an unlocked device, the object path of its cleartext device.