From 7d7e2234a537b6cd2205fb5cf942d5a9e8a866e3 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Fri, 22 Dec 2023 18:14:11 -0500 Subject: Implement new --encrypt args and completion (fixes #784) Positional arguments are supported in a backward-compatible way, but completion no longer guides users to it. --- manual/cli.rst | 119 ++++++++++++++++++++++++++++++++--------------- manual/release-notes.rst | 10 ++++ 2 files changed, 91 insertions(+), 38 deletions(-) (limited to 'manual') diff --git a/manual/cli.rst b/manual/cli.rst index 943b404e..9f173ed8 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -714,7 +714,7 @@ Related Options important cross-reference information typically appears at the end of the file. -.. qpdf:option:: --encrypt user-password owner-password key-length [options] -- +.. qpdf:option:: --encrypt [options] -- .. help: start encryption options @@ -723,32 +723,6 @@ Related Options This flag starts encryption options, used to create encrypted files. Please see :ref:`encryption-options` for details. -.. qpdf:option:: --user-password=user-password - - .. help: specify user password - - Set the user password. - - Set the user password for the encrypted file. - -.. qpdf:option:: --owner-password=owner-password - - .. help: specify owner password - - Set the owner password. - - Set the owner password for the encrypted file. - -.. qpdf:option:: --bits={48|128|256} - - .. help: specify encryption bit depth - - Set the encrypt bit depth. Use 256. - - Set the bit depth for encrypted files. You should always use - ``--bits=256`` unless you have a strong reason to create a file - with weaker encryption. - .. qpdf:option:: --decrypt .. help: remove encryption from input file @@ -1758,13 +1732,31 @@ Encryption Create encrypted files. Usage: + --encrypt \ + [--user-password=user-password] \ + [--owner-password=owner-password] \ + --bits=key-length [options] -- + + OR + --encrypt user-password owner-password key-length [options] -- - Either or both of user-password and owner-password may be empty - strings, though setting either to the empty string enables the file - to be opened and decrypted without a password. key-length may be - 40, 128, or 256. Encryption options are terminated by "--" by - itself. + The first form, with flags for the passwords and bit length, was + introduced in qpdf 11.7.0. Only the --bits option is is mandatory. + This form allows you to use any text as the password. If passwords + are specified, they must be given before the --bits option. + + The second form has been in qpdf since the beginning and wil + continue to be supported. Either or both of user-password and + owner-password may be empty strings. + + The key-length parameter must be either 40, 128, or 256. The user + and/or owner password may be omitted. Omitting either pasword + enables the PDF file to be opened without a password. Specifying + the same value for the user and owner password and specifying an + empty owner password are both considered insecure. + + Encryption options are terminated by "--" by itself. 40-bit encryption is insecure, as is 128-bit encryption without AES. Use 256-bit encryption unless you have a specific reason to @@ -1823,17 +1815,38 @@ and :qpdf:ref:`--copy-encryption`. For a more in-depth technical discussion of how PDF encryption works internally, see :ref:`pdf-encryption`. -To create an encrypted file, use +To create an encrypted file, use one of + +:: + + --encrypt \ + [--user-password=user-password] \ + [--owner-password=owner-password] \ + --bits=key-length [options] -- + +OR :: --encrypt user-password owner-password key-length [options] -- -Either or both of :samp:`{user-password}` and :samp:`{owner-password}` -may be empty strings, though setting either to the empty string -enables the file to be opened and decrypted without a password.. -:samp:`{key-length}` may be ``40``, ``128``, or ``256``. Encryption -options are terminated by ``--`` by itself. +The first form, with flags for the passwords and bit length, was +introduced in qpdf 11.7.0. Only the :qpdf:ref:`--bits` option is is +mandatory. This form allows you to use any text as the password. If +passwords are specified, they must be given before the +:qpdf:ref:`--bits` option. + +The second form has been in qpdf since the beginning and wil +continue to be supported. Either or both of user-password and +owner-password may be empty strings. + +The ``key-length`` parameter must be either ``40``, ``128``, or +``256``. The user and/or owner password may be omitted. Omitting +either pasword enables the PDF file to be opened without a password. +Specifying the same value for the user and owner password and +specifying an empty owner password are both considered insecure. + +Encryption options are terminated by ``--`` by itself. 40-bit encryption is insecure, as is 128-bit encryption without AES. Use 256-bit encryption unless you have a specific reason to use an @@ -1971,6 +1984,36 @@ help for each option. Related Options ~~~~~~~~~~~~~~~ +.. qpdf:option:: --user-password=user-password + + .. help: specify user password + + Set the user password of the encrypted file. + + Set the user passwrod of the encrypted file. Conforming readers + apply security restrictions to files opened with the user password. + +.. qpdf:option:: --owner-password=owner-password + + .. help: specify owner password + + Set the owner password of the encrypted file. + + Set the owner passwrod of the encrypted file. Conforming readers + apply allow security restrictions to be changed or overridden when + files are opened with the owner password. + +.. qpdf:option:: --bits={48|128|256} + + .. help: specify encryption key length + + Specify the encryption key length. For best security, always use + a key length of 256. + + Set the key length for encrypted files. You should always use + ``--bits=256`` unless you have a strong reason to create a file + with weaker encryption. + .. qpdf:option:: --accessibility=[y|n] .. help: restrict document accessibility diff --git a/manual/release-notes.rst b/manual/release-notes.rst index 7aa625ab..50b0aec3 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -61,6 +61,16 @@ Planned changes for future 12.x (subject to change): Previously, any value other than ``/Yes`` or ``/Off`` was rejected. + - CLI Enhancements: + + - Allow the syntax ``--encrypt --user-password=user-password + --owner-password=owner-password --bits={40,128,256}`` when + encrypting PDF files. This is an alternative to the syntax + ``--encrypt user-password owner-password {40,128,256}``, which + will continue to be supported. The new syntax works better with + shell completion and allows creation of passwords that start + with ``-``. + - Build Enhancements: - The qpdf test suite now passes when qpdf is linked with an -- cgit v1.2.3-70-g09d2