Debian Codegraph @

doc/html/gdbus-org.freedesktop.UDisks2.Encrypted.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>org.freedesktop.UDisks2.Encrypted: UDisks Reference Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="UDisks Reference Manual">
8 <link rel="up" href="ch03.html" title="D-Bus Interfaces">
9 <link rel="prev" href="gdbus-org.freedesktop.UDisks2.Swapspace.html" title="org.freedesktop.UDisks2.Swapspace">
10 <link rel="next" href="gdbus-org.freedesktop.UDisks2.Loop.html" title="org.freedesktop.UDisks2.Loop">
11 <meta name="generator" content="GTK-Doc V1.35.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts">
17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
18 <a href="#gdbus-org.freedesktop.UDisks2.Encrypted.description" class="shortcut">Description</a></span><span id="nav_properties">  <span class="dim">|</span> 
19 <a href="#gdbus-org.freedesktop.UDisks2.Encrypted.properties" class="shortcut">Properties</a></span>
20 </td>
21 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
22 <td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
23 <td><a accesskey="p" href="gdbus-org.freedesktop.UDisks2.Swapspace.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
24 <td><a accesskey="n" href="gdbus-org.freedesktop.UDisks2.Loop.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
25 </tr></table>
26 <div class="refentry">
27 <a name="gdbus-org.freedesktop.UDisks2.Encrypted"></a><div class="titlepage"></div>
28 <div class="refnamediv"><table width="100%"><tr>
29 <td valign="top">
30 <h2><span class="refentrytitle"><a name="gdbus-interface-org-freedesktop-UDisks2-Encrypted.top_of_page"></a>org.freedesktop.UDisks2.Encrypted</span></h2>
31 <p>org.freedesktop.UDisks2.Encrypted — Block device containing encrypted data</p>
32 </td>
33 <td class="gallery_image" valign="top" align="right"></td>
34 </tr></table></div>
35 <div class="refsynopsisdiv">
36 <h2>Methods</h2>
37 <pre class="synopsis">
38 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.Unlock" title="The Unlock() method">Unlock</a> (IN s passphrase,
39 IN a{sv} options,
40 OUT o cleartext_device);
41 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.Lock" title="The Lock() method">Lock</a> (IN a{sv} options);
42 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.ChangePassphrase" title="The ChangePassphrase() method">ChangePassphrase</a> (IN s passphrase,
43 IN s new_passphrase,
44 IN a{sv} options);
45 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.Resize" title="The Resize() method">Resize</a> (IN t size,
46 IN a{sv} options);
47 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.Convert" title="The Convert() method">Convert</a> (IN s target_version,
48 IN a{sv} options);
49 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-method-org-freedesktop-UDisks2-Encrypted.HeaderBackup" title="The HeaderBackup() method">HeaderBackup</a> (IN s backup_file,
50 IN a{sv} options);
51 </pre>
52 </div>
53 <div class="refsect1">
54 <a name="id-1.3.3.11.4"></a><h2>Properties</h2>
55 <pre class="synopsis">
56 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-property-org-freedesktop-UDisks2-Encrypted.ChildConfiguration" title='The "ChildConfiguration" property'>ChildConfiguration</a> readable a(sa{sv})
57 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-property-org-freedesktop-UDisks2-Encrypted.HintEncryptionType" title='The "HintEncryptionType" property'>HintEncryptionType</a> readable s
58 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-property-org-freedesktop-UDisks2-Encrypted.MetadataSize" title='The "MetadataSize" property'>MetadataSize</a> readable t
59 <a class="link" href="gdbus-org.freedesktop.UDisks2.Encrypted.html#gdbus-property-org-freedesktop-UDisks2-Encrypted.CleartextDevice" title='The "CleartextDevice" property'>CleartextDevice</a> readable o
60 </pre>
61 </div>
62 <div class="refsect1">
63 <a name="gdbus-interface-org-freedesktop-UDisks2-Encrypted"></a><h2>Description</h2>
64 <p>
65 This interface is used for <a class="link" href="gdbus-org.freedesktop.UDisks2.Block.html#gdbus-interface-org-freedesktop-UDisks2-Block.top_of_page">org.freedesktop.UDisks2.Block</a>
66 devices that contain encrypted data.
67 </p>
68 </div>
69 <div class="refsect1">
70 <a name="gdbus-methods-org.freedesktop.UDisks2.Encrypted"></a><h2>Method Details</h2>
71 <div class="refsect2">
72 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.Unlock"></a><h3>The Unlock() method</h3>
73 <pre class="programlisting">
74 Unlock (IN s passphrase,
75 IN a{sv} options,
76 OUT o cleartext_device);
77 </pre>
78 <p>
79 Tries to unlock the encrypted device using <em class="parameter"><code>passphrase</code></em>.
80 </p>
81 <p>
82 If the device in question is referenced in a system-wide
83 configuration file (such as the <code class="filename">/etc/crypttab</code> file),
84 then name, options and passphrase (if available) is used from that
85 file after requesting additional authorization.
86 </p>
87 <p>
88 If an empty passphrase should be used to unlock the device, it has to be
89 passed using the <em class="parameter"><code>keyfile_contents</code></em> parameter. Empty string passed as
90 <em class="parameter"><code>passphrase</code></em> means "Use the passphrase from the configuration file".
91 </p>
92 <p>
93 If the device is removed without being locked (e.g. the user
94 yanking the device or pulling the media out) the cleartext
95 device will be cleaned up.
96 </p>
97 <div class="variablelist"><table border="0" class="variablelist">
98 <colgroup>
99 <col align="left" valign="top">
100 <col>
101 </colgroup>
102 <tbody>
103 <tr>
104 <td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>passphrase</code></em></code>:</span></p></td>
105 <td><p>
106 The passphrase to use.
107 </p></td>
108 </tr>
109 <tr>
110 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
111 <td><p>
112 Options - known options (in addition to <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>) includes <em class="parameter"><code>keyfile_contents</code></em> (of type 'ay') which is preferred over <em class="parameter"><code>passphrase</code></em> if specified and <em class="parameter"><code>read-only</code></em> (of type 'b').
113 </p></td>
114 </tr>
115 <tr>
116 <td><p><span class="term"><code class="literal">OUT o <em class="parameter"><code>cleartext_device</code></em></code>:</span></p></td>
117 <td><p>
118 An object path to the unlocked object implementing the <a class="link" href="gdbus-org.freedesktop.UDisks2.Block.html#gdbus-interface-org-freedesktop-UDisks2-Block.top_of_page">org.freedesktop.UDisks2.Block</a> interface.
119 </p></td>
120 </tr>
121 </tbody>
122 </table></div>
123 </div>
124 <hr>
125 <div class="refsect2">
126 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.Lock"></a><h3>The Lock() method</h3>
127 <pre class="programlisting">
128 Lock (IN a{sv} options);
129 </pre>
130 <p>
131 Locks the encrypted device.
132 </p>
133 <div class="variablelist"><table border="0" class="variablelist">
134 <colgroup>
135 <col align="left" valign="top">
136 <col>
137 </colgroup>
138 <tbody><tr>
139 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
140 <td><p>
141 Options (currently unused except for <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>).
142 </p></td>
143 </tr></tbody>
144 </table></div>
145 </div>
146 <hr>
147 <div class="refsect2">
148 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.ChangePassphrase"></a><h3>The ChangePassphrase() method</h3>
149 <pre class="programlisting">
150 ChangePassphrase (IN s passphrase,
151 IN s new_passphrase,
152 IN a{sv} options);
153 </pre>
154 <p>
155 Changes the passphrase to <em class="parameter"><code>new_passphrase</code></em>. An existing passphrase is required.
156 </p>
157 <p>
158 If <em class="parameter"><code>old_keyfile_contents</code></em> or
159 <em class="parameter"><code>new_keyfile_contents</code></em> are given, they take
160 precedence over the corresponding passphrase parameters individually.
161 </p>
162 <p>
163 If the device in question is referenced in a system-wide
164 configuration file (such as the
165 <code class="filename">/etc/crypttab</code> file) and this
166 configuration references the passphrase, it is not
167 automatically updated.
168 </p>
169 <div class="variablelist"><table border="0" class="variablelist">
170 <colgroup>
171 <col align="left" valign="top">
172 <col>
173 </colgroup>
174 <tbody>
175 <tr>
176 <td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>passphrase</code></em></code>:</span></p></td>
177 <td><p>
178 The existing passphrase.
179 </p></td>
180 </tr>
181 <tr>
182 <td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>new_passphrase</code></em></code>:</span></p></td>
183 <td><p>
184 The new passphrase to use.
185 </p></td>
186 </tr>
187 <tr>
188 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
189 <td><p>
190 Options - known options (in addition to <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>) includes <em class="parameter"><code>old_keyfile_contents</code></em> and <em class="parameter"><code>new_keyfile_contents</code></em> (of type 's' or 'ay').
191 </p></td>
192 </tr>
193 </tbody>
194 </table></div>
195 </div>
196 <hr>
197 <div class="refsect2">
198 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.Resize"></a><h3>The Resize() method</h3>
199 <pre class="programlisting">
200 Resize (IN t size,
201 IN a{sv} options);
202 </pre>
203 <p>
204 Resizes the encrypted device. The device must be unlocked.
205 The given size is the target size for the cleartext device.
206 </p>
207 <p>
208 You need to specify either <em class="parameter"><code>passphrase</code></em> or <em class="parameter"><code>keyfile_contents</code></em> for LUKS 2
209 devices that don't have verified key loaded in kernel keyring.
210 </p>
211 <div class="variablelist"><table border="0" class="variablelist">
212 <colgroup>
213 <col align="left" valign="top">
214 <col>
215 </colgroup>
216 <tbody>
217 <tr>
218 <td><p><span class="term"><code class="literal">IN t <em class="parameter"><code>size</code></em></code>:</span></p></td>
219 <td><p>
220 The target cleartext size in bytes, 0 for maximum.
221 </p></td>
222 </tr>
223 <tr>
224 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
225 <td><p>
226 Options - known options (in addition to <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>) includes <em class="parameter"><code>passphrase</code></em> (of type 's') and <em class="parameter"><code>keyfile_contents</code></em> (of type 'ay') which is preferred over <em class="parameter"><code>passphrase</code></em> if specified.
227 </p></td>
228 </tr>
229 </tbody>
230 </table></div>
231 <p class="since">Since 2.8.0</p>
232 </div>
233 <hr>
234 <div class="refsect2">
235 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.Convert"></a><h3>The Convert() method</h3>
236 <pre class="programlisting">
237 Convert (IN s target_version,
238 IN a{sv} options);
239 </pre>
240 <p>
241 Converts the encrypted device to a different version of LUKS. Other encryption formats are not supported.
242 The device must be locked.
243 </p>
244 <div class="variablelist"><table border="0" class="variablelist">
245 <colgroup>
246 <col align="left" valign="top">
247 <col>
248 </colgroup>
249 <tbody>
250 <tr>
251 <td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>target_version</code></em></code>:</span></p></td>
252 <td><p>
253 The LUKS version to convert to. Either 'luks1' or 'luks2'.
254 </p></td>
255 </tr>
256 <tr>
257 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
258 <td><p>
259 Options (currently unused except for <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>).
260 </p></td>
261 </tr>
262 </tbody>
263 </table></div>
264 <p class="since">Since 2.11.0</p>
265 </div>
266 <hr>
267 <div class="refsect2">
268 <a name="gdbus-method-org-freedesktop-UDisks2-Encrypted.HeaderBackup"></a><h3>The HeaderBackup() method</h3>
269 <pre class="programlisting">
270 HeaderBackup (IN s backup_file,
271 IN a{sv} options);
272 </pre>
273 <p>
274 Saves header and keyslots to the specified file.
275 The target file is not overwritten if exists, and an error is returned.
276 </p>
277 <div class="variablelist"><table border="0" class="variablelist">
278 <colgroup>
279 <col align="left" valign="top">
280 <col>
281 </colgroup>
282 <tbody>
283 <tr>
284 <td><p><span class="term"><code class="literal">IN s <em class="parameter"><code>backup_file</code></em></code>:</span></p></td>
285 <td><p>
286 Path where to backup header and keyslots to.
287 </p></td>
288 </tr>
289 <tr>
290 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
291 <td><p>
292 Options (currently unused except for <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>).
293 </p></td>
294 </tr>
295 </tbody>
296 </table></div>
297 <p class="since">Since 2.11.0</p>
298 </div>
299 </div>
300 <div class="refsect1">
301 <a name="gdbus-properties-org.freedesktop.UDisks2.Encrypted"></a><h2>Property Details</h2>
302 <div class="refsect2">
303 <a name="gdbus-property-org-freedesktop-UDisks2-Encrypted.ChildConfiguration"></a><h3>The "ChildConfiguration" property</h3>
304 <pre class="programlisting">
305 ChildConfiguration readable a(sa{sv})
306 </pre>
307 <p>
308 Configuration items belonging to the
309 </p>
310 <p>
311 clear text device of this encrypted block device and its
312 children. This is also valid when this block device is
313 currently locked and there is no clear text device for it.
314 It works via the 'track-parents' options of
315 <a class="link" href="gdbus-org.freedesktop.UDisks2.Block.html#gdbus-method-org-freedesktop-UDisks2-Block.AddConfigurationItem" title="The AddConfigurationItem() method">AddConfigurationItem()</a>, which
316 see.
317 </p>
318 </div>
319 <hr>
320 <div class="refsect2">
321 <a name="gdbus-property-org-freedesktop-UDisks2-Encrypted.HintEncryptionType"></a><h3>The "HintEncryptionType" property</h3>
322 <pre class="programlisting">
323 HintEncryptionType readable s
324 </pre>
325 <p>
326 </p>
327 <p>
328 If not blank, the type of the encryption used to encrypt this device.
329 </p>
330 <p>
331 This is set during successful unlocking of an encrypted device.
332 It is required for encryption types which can only be determined
333 by decrypting the device (for example TCRYPT), but is used for all
334 encryption types for consistency reasons.
335 </p>
336 </div>
337 <hr>
338 <div class="refsect2">
339 <a name="gdbus-property-org-freedesktop-UDisks2-Encrypted.MetadataSize"></a><h3>The "MetadataSize" property</h3>
340 <pre class="programlisting">
341 MetadataSize readable t
342 </pre>
343 <p>
344 Size of the metadata on the encrypted device in bytes
345 </p>
346 </div>
347 <hr>
348 <div class="refsect2">
349 <a name="gdbus-property-org-freedesktop-UDisks2-Encrypted.CleartextDevice"></a><h3>The "CleartextDevice" property</h3>
350 <pre class="programlisting">
351 CleartextDevice readable o
352 </pre>
353 <p>
354 </p>
355 <p>
356 For an unlocked device, the object path of its cleartext device.
357 </p>
358 </div>
359 </div>
360 </div>
361 <div class="footer">
362 <hr>Generated by GTK-Doc V1.35.1</div>
363 </body>
364 </html>