Changeset 94201 in vbox

Timestamp:

Mar 12, 2022 7:29:49 PM (3 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

150457

Message:

doc/manual,FE/VBoxManage: Convert encryptmedium command to refentry documentation, ​bugref:9186

Location:

trunk

Files:

• doc/manual/Config.kmk (modified) (1 diff)
• doc/manual/en_US/man_VBoxManage-encryptmedium.xml (modified) (2 diffs)
• doc/manual/en_US/user_VBoxManage.xml (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.h (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp (modified) (2 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)

trunk/doc/manual/Config.kmk

@@ -70 +70 @@
         man_VBoxManage-createmedium.xml \
         man_VBoxManage-clonemedium.xml \
-        man_VBoxManage-mediumproperty.xml
+        man_VBoxManage-mediumproperty.xml \
+        man_VBoxManage-encryptmedium.xml
 
 ## List of user manual XML files.

trunk/doc/manual/en_US/man_VBoxManage-encryptmedium.xml

@@ -20 +20 @@
 <refentry id="vboxmanage-encryptmedium" lang="en">
   <refentryinfo>
-    <pubdate>August 2019</pubdate>
+    <pubdate>$Date$</pubdate>
     <title>VBoxManage encryptmedium</title>
   </refentryinfo>
@@ -32 +32 @@
     <refname>VBoxManage-encryptmedium</refname>
     <refpurpose>manage a DEK-encrypted medium or image</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -1093 +1093 @@
   <xi:include href="user_man_VBoxManage-mediumproperty.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <sect1 id="vboxmanage-encryptmedium">
-
-    <title>VBoxManage encryptmedium</title>
-
-    <para>
-      This command is used to create a DEK encrypted medium or image.
-      See <xref linkend="diskencryption-encryption" />.
-    </para>
-
-    <para>
-      The syntax is as follows:
-    </para>
-
-<screen>VBoxManage encryptmedium &lt;uuid|filename&gt;
-                         [--newpassword &lt;file|-&gt;]
-                         [--oldpassword &lt;file|-&gt;]
-                         [--cipher &lt;cipher id&gt;]
-                         [--newpasswordid &lt;password id&gt;]</screen>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
-          supply the UUID or absolute path of the medium or image to be
-          encrypted.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Use <computeroutput>--newpassword
-          &lt;file|-&gt;</computeroutput> to supply a new encryption
-          password. Either specify the absolute pathname of a password
-          file on the host operating system, or
-          <computeroutput>-</computeroutput> to prompt you for the
-          password on the command line. Always use the
-          <computeroutput>--newpasswordid</computeroutput> option with
-          this option.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Use <computeroutput>--oldpassword
-          &lt;file|-&gt;</computeroutput> to supply any old encryption
-          password. Either specify the absolute pathname of a password
-          file on the host operating system, or
-          <computeroutput>-</computeroutput> to prompt you for the old
-          password on the command line.
-        </para>
-
-        <para>
-          Use this option to gain access to an encrypted medium or image
-          to either change its password using
-          <computeroutput>--newpassword</computeroutput> or change its
-          encryption using <computeroutput>--cipher</computeroutput>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Use <computeroutput>--cipher &lt;cipher&gt;</computeroutput>
-          to specify the cipher to use for encryption. This can be
-          either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
-          <computeroutput>AES-XTS256-PLAIN64</computeroutput>.
-        </para>
-
-        <para>
-          Use this option to change any existing encryption on the
-          medium or image, or to set up new encryption on it for the
-          first time.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Use <computeroutput>--newpasswordid &lt;password
-          id&gt;</computeroutput> to supply the new password identifier.
-          This can be chosen by the user, and is used for correct
-          identification when supplying multiple passwords during VM
-          startup.
-        </para>
-
-        <para>
-          If the user uses the same password when encrypting multiple
-          images and also the same password identifier, the user needs
-          to supply the password only once during VM startup.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-  </sect1>
+  <xi:include href="user_man_VBoxManage-encryptmedium.xml"  xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <sect1 id="vboxmanage-checkmediumpwd">

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

@@ -209 +209 @@
     { "clonehd",            USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 }, /* backward compatibility */
     { "clonevdi",           USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 }, /* backward compatibility */
-    { "encryptmedium",      USAGE_ENCRYPTMEDIUM,    VBMG_CMD_TODO, handleEncryptMedium,        0 },
+    { "encryptmedium",      USAGE_S_NEWCMD,HELP_CMD_ENCRYPTMEDIUM, handleEncryptMedium,        0 },
     { "checkmediumpwd",     USAGE_MEDIUMENCCHKPWD,  VBMG_CMD_TODO, handleCheckMediumPassword,  0 },
     { "createvm",           USAGE_S_NEWCMD,     HELP_CMD_CREATEVM, handleCreateVM,             0 },

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h

@@ -132 +132 @@
     USAGE_I_REPAIRHD,
     USAGE_NATNETWORK,
-    USAGE_ENCRYPTMEDIUM,
     USAGE_MEDIUMENCCHKPWD,
     USAGE_USBDEVSOURCE,

trunk/src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp

@@ -2008 +2008 @@
                     pszFilenameOrUuid = ValueUnion.psz;
                 else
-                    return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
                 break;
 
@@ -2015 +2015 @@
                 {
                     if (RT_C_IS_PRINT(c))
-                        return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("Invalid option -%c"), c);
+                        return errorSyntax(Disk::tr("Invalid option -%c"), c);
                     else
-                        return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("Invalid option case %i"), c);
+                        return errorSyntax(Disk::tr("Invalid option case %i"), c);
                 }
                 else if (c == VERR_GETOPT_UNKNOWN_OPTION)
-                    return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("unknown option: %s\n"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("unknown option: %s\n"), ValueUnion.psz);
                 else if (ValueUnion.pDef)
-                    return errorSyntax(USAGE_ENCRYPTMEDIUM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
+                    return errorSyntax("%s: %Rrs", ValueUnion.pDef->pszLong, c);
                 else
-                    return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("error: %Rrs"), c);
+                    return errorSyntax(Disk::tr("error: %Rrs"), c);
         }
     }
 
     if (!pszFilenameOrUuid)
-        return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("Disk name or UUID required"));
+        return errorSyntax(Disk::tr("Disk name or UUID required"));
 
     if (!pszPasswordNew && !pszPasswordOld)
-        return errorSyntax(USAGE_ENCRYPTMEDIUM, Disk::tr("No password specified"));
+        return errorSyntax(Disk::tr("No password specified"));
 
     if (   (pszPasswordNew && !pszNewPasswordId)
         || (!pszPasswordNew && pszNewPasswordId))
-        return errorSyntax(USAGE_ENCRYPTMEDIUM,
-                           Disk::tr("A new password must always have a valid identifier set at the same time"));
+        return errorSyntax(Disk::tr("A new password must always have a valid identifier set at the same time"));
 
     if (pszPasswordNew)

trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp

@@ -639 +639 @@
                      "\n", SEP);
 
-    if (enmCommand == USAGE_ENCRYPTMEDIUM || enmCommand == USAGE_S_ALL)
-        RTStrmPrintf(pStrm,
-                           "%s encryptmedium %s   <uuid|filename>\n"
-                     "                            [--newpassword <file>|-]\n"
-                     "                            [--oldpassword <file>|-]\n"
-                     "                            [--cipher <cipher identifier>]\n"
-                     "                            [--newpasswordid <password identifier>]\n"
-                     "\n", SEP);
-
     if (enmCommand == USAGE_MEDIUMENCCHKPWD || enmCommand == USAGE_S_ALL)
         RTStrmPrintf(pStrm,