Mark weak encryption with API changes (fixes #576)

2 files changed, 25 insertions, 11 deletions

diff --git a/include/qpdf/QPDFWriter.hh b/include/qpdf/QPDFWriter.hh
index f30a9986..e44839d4 100644
--- a/include/qpdf/QPDFWriter.hh
+++ b/include/qpdf/QPDFWriter.hh
@@ -366,10 +366,12 @@ class QPDFWriter
     // functions that could be useful to you, most notably
     // utf8_to_pdf_doc.
 
-    // R3 uses RC4, which is a weak cryptographic algorithm. Don't use
-    // it unless you have to.
+    // R2 uses RC4, which is a weak cryptographic algorithm. Don't use
+    // it unless you have to. See "Weak Cryptography" in the manual.
+    // This encryption format is deprecated in the PDF 2.0
+    // specification.
     QPDF_DLL
-    void setR2EncryptionParameters(
+    void setR2EncryptionParametersInsecure(
         char const* user_password,
         char const* owner_password,
         bool allow_print,
@@ -377,9 +379,11 @@ class QPDFWriter
         bool allow_extract,
         bool allow_annotate);
     // R3 uses RC4, which is a weak cryptographic algorithm. Don't use
-    // it unless you have to.
+    // it unless you have to. See "Weak Cryptography" in the manual.
+    // This encryption format is deprecated in the PDF 2.0
+    // specification.
     QPDF_DLL
-    void setR3EncryptionParameters(
+    void setR3EncryptionParametersInsecure(
         char const* user_password,
         char const* owner_password,
         bool allow_accessibility,
@@ -389,10 +393,13 @@ class QPDFWriter
         bool allow_form_filling,
         bool allow_modify_other,
         qpdf_r3_print_e print);
-    // R4 uses RC4, which is a weak cryptographic algorithm, when
-    // use_aes=false. Don't use it unless you have to.
+    // When use_aes=false, this call enables R4 with RC4, which is a
+    // weak cryptographic algorithm. Even with use_aes=true, the
+    // overall encryption scheme is weak. Don't use it unless you have
+    // to. See "Weak Cryptography" in the manual. This encryption
+    // format is deprecated in the PDF 2.0 specification.
     QPDF_DLL
-    void setR4EncryptionParameters(
+    void setR4EncryptionParametersInsecure(
         char const* user_password,
         char const* owner_password,
         bool allow_accessibility,
@@ -419,6 +426,8 @@ class QPDFWriter
         bool allow_modify_other,
         qpdf_r3_print_e print,
         bool encrypt_metadata);
+    // This is the only password-based encryption format supported by
+    // the PDF specification.
     QPDF_DLL
     void setR6EncryptionParameters(
         char const* user_password,
diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h
index 1a81b899..4b40f068 100644
--- a/include/qpdf/qpdf-c.h
+++ b/include/qpdf/qpdf-c.h
@@ -458,8 +458,13 @@ extern "C" {
     QPDF_DLL
     void qpdf_set_preserve_encryption(qpdf_data qpdf, QPDF_BOOL value);
 
+    /* The *_insecure functions are identical to the old versions but
+     * have been renamed as a an alert to the caller that they are
+     * insecure. See "Weak Cryptographic" in the manual for
+     * details.
+     */
     QPDF_DLL
-    void qpdf_set_r2_encryption_parameters(
+    void qpdf_set_r2_encryption_parameters_insecure(
         qpdf_data qpdf,
         char const* user_password,
         char const* owner_password,
@@ -469,7 +474,7 @@ extern "C" {
         QPDF_BOOL allow_annotate);
 
     QPDF_DLL
-    void qpdf_set_r3_encryption_parameters2(
+    void qpdf_set_r3_encryption_parameters_insecure(
         qpdf_data qpdf,
         char const* user_password,
         char const* owner_password,
@@ -482,7 +487,7 @@ extern "C" {
         enum qpdf_r3_print_e print);
 
     QPDF_DLL
-    void qpdf_set_r4_encryption_parameters2(
+    void qpdf_set_r4_encryption_parameters_insecure(
         qpdf_data qpdf,
         char const* user_password,
         char const* owner_password,