VirtualBox

source: vbox/trunk/doc/manual/en_US/man_VBoxManage-encryptmedium.xml@ 87075

Last change on this file since 87075 was 87075, checked in by vboxsync, 4 years ago

doc/manual: whitespace fixing in man pages

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 manpage, user manual, usage: VBoxManage encryptmedium
4
5 Copyright (C) 2006-2020 Oracle Corporation
6
7 This file is part of VirtualBox Open Source Edition (OSE), as
8 available from http://www.virtualbox.org. This file is free software;
9 you can redistribute it and/or modify it under the terms of the GNU
10 General Public License (GPL) as published by the Free Software
11 Foundation, in version 2 as it comes in the "COPYING" file of the
12 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
14 -->
15<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
16 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
17<!ENTITY % all.entities SYSTEM "all-entities.ent">
18%all.entities;
19]>
20<refentry id="vboxmanage-encryptmedium" lang="en">
21 <refentryinfo>
22 <pubdate>August 2019</pubdate>
23 <title>VBoxManage encryptmedium</title>
24 </refentryinfo>
25
26 <refmeta>
27 <refentrytitle>VBoxManage-encryptmedium</refentrytitle>
28 <manvolnum>1</manvolnum>
29 </refmeta>
30
31 <refnamediv>
32 <refname>VBoxManage-encryptmedium</refname>
33 <refpurpose>manage a DEK-encrypted medium or image</refpurpose>
34 <refclass>Oracle VM VirtualBox</refclass>
35 </refnamediv>
36
37 <refsynopsisdiv>
38 <cmdsynopsis id="synopsis-vboxmanage-encryptmedium">
39<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
40 <command>VBoxManage encryptmedium</command>
41 <group choice="req">
42 <arg choice="plain"><replaceable>uuid</replaceable></arg>
43 <arg choice="plain"><replaceable>filename</replaceable></arg>
44 </group>
45 <arg>--cipher=<replaceable>cipher-ID</replaceable></arg>
46 <arg>--newpassword=<replaceable>password</replaceable></arg>
47 <arg>--newpasswordid=<replaceable>password-ID</replaceable></arg>
48 <arg>--oldpassword=<replaceable>password</replaceable></arg>
49 </cmdsynopsis>
50 </refsynopsisdiv>
51
52 <refsect1>
53 <title>Description</title>
54 <para>
55 The <command>VBoxManage encryptmedium</command> command enables
56 you to create and manage a DEK-encrypted medium or image. You can
57 encrypt an image, decrypt an image, and change the encryption
58 password of an image. See
59 <xref linkend="diskencryption-encryption" />.
60 </para>
61 <variablelist>
62 <varlistentry>
63 <term><replaceable>uuid</replaceable> | <replaceable>filename</replaceable></term>
64 <listitem><para>
65 Specifies the Universally Unique Identifier (UUID) or the
66 absolute path name of the medium or image to encrypt.
67 </para></listitem>
68 </varlistentry>
69 <varlistentry>
70 <term><option>--newpassword=<replaceable>password</replaceable></option></term>
71 <listitem><para>
72 Specifies the new encryption password.
73 <replaceable>password</replaceable> is either the absolute
74 path name of a password file on the host operating system or
75 <literal>-</literal>, which prompts you for the password.
76 </para><para>
77 You must use the <option>--newpasswordid</option> option
78 with this <option>--newpassword</option> option.
79 </para></listitem>
80 </varlistentry>
81 <varlistentry>
82 <term><option>--oldpassword=<replaceable>password</replaceable></option></term>
83 <listitem><para>
84 Specifies the original encryption password.
85 <replaceable>password</replaceable> is either the absolute
86 path name of a password file on the host operating system or
87 <literal>-</literal>, which prompts you for the original
88 password.
89 </para><para>
90 This option enables you to gain access to an encrypted
91 medium or image to do the following:
92 </para><itemizedlist>
93 <listitem><para>
94 Decrypt an encrypted image by using this option by
95 itself.
96 </para></listitem>
97 <listitem><para>
98 Change the password of the encrypted image by using the
99 <option>--newpassword</option> option.
100 </para></listitem>
101 <listitem><para>
102 Change the encryption cipher of the image by using the
103 <option>--cipher</option> option.
104 </para></listitem>
105 </itemizedlist></listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><option>--cipher=<replaceable>cipher-ID</replaceable></option></term>
109 <listitem><para>
110 Specifies the cipher to use for encryption. Valid values are
111 <literal>AES-XTS128-PLAIN64</literal> or
112 <literal>AES-XTS256-PLAIN64</literal>.
113 </para><para>
114 This option enables you to set up or change encryption on
115 the medium or image.
116 </para></listitem>
117 </varlistentry>
118 <varlistentry>
119 <term><option>--newpasswordid=<replaceable>password-ID</replaceable></option></term>
120 <listitem><para>
121 Specifies a new password identifier that is used for correct
122 identification when supplying multiple passwords during VM
123 startup.
124 </para><para>
125 If you use the same password and password identifier when
126 encrypting multiple images, you need to supply the password
127 only one time during VM startup.
128 </para></listitem>
129 </varlistentry>
130 </variablelist>
131 </refsect1>
132
133 <refsect1>
134 <title>Examples</title>
135 <remark role="help-scope" condition="GLOBAL"/>
136 <para>
137 The following example shows how to encrypt the
138 <filename>ol7u4-1.vdi</filename> image by using the
139 <literal>AES-XTS128-PLAIN64</literal> cipher, specifying a
140 password identifier of <literal>1001</literal>, and using the
141 <filename>$HOME/pwfile</filename> password file:
142 </para>
143<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-1.vdi" \
144 --cipher="AES-XTS128-PLAIN64" --newpasswordid="1001" --newpassword=$HOME/pwfile</screen>
145 <para>
146 The following example shows how to decrypt an encrypted image
147 called <filename>ol7u4-2.vdi</filename>:
148 </para>
149<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-2.vdi" \
150 --oldpassword=-
151 Password: <replaceable>original-password</replaceable></screen>
152 <para>
153 The following example shows how to change the password for an
154 encrypted image called <filename>ol7u4-3.vdi</filename>. The
155 command reads the original password from the
156 <filename>$HOME/pwfile.orig</filename> file, reads the new
157 password from the <filename>$HOME/pwfile</filename> file, and
158 assigns a password identifier of <literal>1001</literal>.
159 </para>
160<screen>$ VBoxManage encryptmedium "$HOME/VirtualBox VMs/ol7u4/ol7u4-3.vdi" \
161 --oldpassword=$HOME/pwfile.orig --newpassword=$HOME/pwfile --newpasswordid="1001"</screen>
162 </refsect1>
163</refentry>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette