Derby
  1. Derby
  2. DERBY-5805

Database encryption topics in Reference Manual need more information

    Details

      Description

      The Developer's Guide and Reference Manual information on the bootPassword and encryptionKey attributes doesn't state (not prominently, anyway) that these properties are mutually exclusive, as Rick Hillegas points out in his 6/8/2012 comment on DERBY-5622. This information should be included in the documentation for these properties.

      In general, the topics on database encryption attributes need additional information, corrections, and examples.

      1. DERBY-5805.diff
        15 kB
        Kim Haase
      2. DERBY-5805.stat
        0.3 kB
        Kim Haase
      3. DERBY-5805.zip
        15 kB
        Kim Haase
      4. DERBY-5805-2.diff
        20 kB
        Kim Haase
      5. DERBY-5805-2.stat
        0.3 kB
        Kim Haase
      6. DERBY-5805-2.zip
        17 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          I've been looking at the Reference Manual documentation on the encryption-related attributes for both this issue and the anticipated documentation for DERBY-5792 (decryption). (See (http://db.apache.org/derby/docs/dev/ref/.)

          It appears that you can specify the encryptionProvider and encryptionAlgorithm attributes with either bootPassword or encryptionKey, according to the topic on the dataEncryption attribute. However, the topics on encryptionProvider and encryptionAlgorithm do not mention the encryptionKey attribute, implying that they only work with bootPassword. Should those topics be corrected?

          Also, in the encryptionKey topic, the only example of an encryptionAlgorithm uses the default algorithm. Seems as if it would be more realistic to change this to a nondefault one.

          Show
          Kim Haase added a comment - I've been looking at the Reference Manual documentation on the encryption-related attributes for both this issue and the anticipated documentation for DERBY-5792 (decryption). (See ( http://db.apache.org/derby/docs/dev/ref/ .) It appears that you can specify the encryptionProvider and encryptionAlgorithm attributes with either bootPassword or encryptionKey, according to the topic on the dataEncryption attribute. However, the topics on encryptionProvider and encryptionAlgorithm do not mention the encryptionKey attribute, implying that they only work with bootPassword. Should those topics be corrected? Also, in the encryptionKey topic, the only example of an encryptionAlgorithm uses the default algorithm. Seems as if it would be more realistic to change this to a nondefault one.
          Hide
          Dag H. Wanvik added a comment - - edited

          > However, the topics on encryptionProvider and encryptionAlgorithm do not mention the encryptionKey attribute, implying that they only work with bootPassword.

          I see an example in the tests (in "encryptionKey_jar.sql") that combines algorithm and key:

          connect 'jdbc:derby:jar:(ina.jar)db1;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKey=6162636465666768' AS DB1;

          I believe encryptionKey can be used instead of bootPassword always.

          Update: the code in JCECipherFactory#init indicates this holds. -Dag

          Show
          Dag H. Wanvik added a comment - - edited > However, the topics on encryptionProvider and encryptionAlgorithm do not mention the encryptionKey attribute, implying that they only work with bootPassword. I see an example in the tests (in "encryptionKey_jar.sql") that combines algorithm and key: connect 'jdbc:derby:jar:(ina.jar)db1;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKey=6162636465666768' AS DB1; I believe encryptionKey can be used instead of bootPassword always. Update: the code in JCECipherFactory#init indicates this holds. -Dag
          Hide
          Kim Haase added a comment -

          Thanks, Dag. Indeed, the topic on encryptionKey has an example that uses exactly those attributes. So I think what is needed is to update the encryptionProvider and encryptionAlgorithm topics to mention that they work with either bootPassword or encryptionKey and to provide an example for each that uses encryptionKey.

          Do you have some tests that use a non-default encryptionAlgorithm? DES/CBC/NoPadding is the default, so there is really no need to specify it. I was thinking of changing the encryptionKey example to use AES, or something.

          Show
          Kim Haase added a comment - Thanks, Dag. Indeed, the topic on encryptionKey has an example that uses exactly those attributes. So I think what is needed is to update the encryptionProvider and encryptionAlgorithm topics to mention that they work with either bootPassword or encryptionKey and to provide an example for each that uses encryptionKey. Do you have some tests that use a non-default encryptionAlgorithm? DES/CBC/NoPadding is the default, so there is really no need to specify it. I was thinking of changing the encryptionKey example to use AES, or something.
          Hide
          Kristian Waagan added a comment -

          We have do have EncryptionKeyBlowfishTest.
          Here's an ij example using a 128-bit AES encryption key:
          ij> connect 'jdbc:derby:mydb;create=true;dataEncryption=true;encryptionKey=B54C0BDB303E0584695E4090E8FCDE1E;encryptionAlgorithm=AES/CBC/NoPadding';

          I noticed that we don't document the encryptionKeyLength attribute in the Reference Manual, although we have mentioned it in the Developers Guide (see DERBY-4229). From what I can see, it only applies to the bootPassword attribute.

          Show
          Kristian Waagan added a comment - We have do have EncryptionKeyBlowfishTest. Here's an ij example using a 128-bit AES encryption key: ij> connect 'jdbc:derby:mydb;create=true;dataEncryption=true;encryptionKey=B54C0BDB303E0584695E4090E8FCDE1E;encryptionAlgorithm=AES/CBC/NoPadding'; I noticed that we don't document the encryptionKeyLength attribute in the Reference Manual, although we have mentioned it in the Developers Guide (see DERBY-4229 ). From what I can see, it only applies to the bootPassword attribute.
          Hide
          Kim Haase added a comment -

          Thanks, Kristian, for that example. I've reopened DERBY-4229 to add a topic on the encryptionKeyLength attribute to the Reference Manual.

          Show
          Kim Haase added a comment - Thanks, Kristian, for that example. I've reopened DERBY-4229 to add a topic on the encryptionKeyLength attribute to the Reference Manual.
          Hide
          Kim Haase added a comment -

          The Developer's Guide section on DB encryption has a topic called "Creating the boot password" that doesn't discuss the possibility of using the encryptionKey attribute instead of the bootPassword attribute, although encryptionKey is mentioned in some other topics. The topic should be retitled and rewritten. Perhaps "Specifying a boot password or encryption key" would be better.

          Show
          Kim Haase added a comment - The Developer's Guide section on DB encryption has a topic called "Creating the boot password" that doesn't discuss the possibility of using the encryptionKey attribute instead of the bootPassword attribute, although encryptionKey is mentioned in some other topics. The topic should be retitled and rewritten. Perhaps "Specifying a boot password or encryption key" would be better.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5805.diff, DERBY-5805.stat, and DERBY-5805.zip, with revisions to the encryption-related Reference Manual topics for completeness, consistency, and formatting. The following files are changed:

          M src/ref/rrefattrib88843.dita
          M src/ref/rrefattribencryptkey.dita
          M src/ref/rrefattribencryptkeylength.dita
          M src/ref/rrefattribnewencryptkey.dita
          M src/ref/rrefattrib15290.dita
          M src/ref/rrefattrib42100.dita
          M src/ref/refderby.ditamap
          M src/ref/rrefattrib60346.dita

          The only change in the map file was to correct the alphabetical order of a couple of topics.

          I hope no technical errors have been introduced. I don't know if the comments I made in DERBY-4229 about the interaction of some of the attributes should have any effect.

          I will use DERBY-1721 to make fixes to Developer's Guide encryption topics. Once these are all completed, I can add the decryption information as needed.

          Show
          Kim Haase added a comment - Attaching DERBY-5805 .diff, DERBY-5805 .stat, and DERBY-5805 .zip, with revisions to the encryption-related Reference Manual topics for completeness, consistency, and formatting. The following files are changed: M src/ref/rrefattrib88843.dita M src/ref/rrefattribencryptkey.dita M src/ref/rrefattribencryptkeylength.dita M src/ref/rrefattribnewencryptkey.dita M src/ref/rrefattrib15290.dita M src/ref/rrefattrib42100.dita M src/ref/refderby.ditamap M src/ref/rrefattrib60346.dita The only change in the map file was to correct the alphabetical order of a couple of topics. I hope no technical errors have been introduced. I don't know if the comments I made in DERBY-4229 about the interaction of some of the attributes should have any effect. I will use DERBY-1721 to make fixes to Developer's Guide encryption topics. Once these are all completed, I can add the decryption information as needed.
          Hide
          Kim Haase added a comment -

          I plan to commit this patch on October 8 and backport it to 10.5. I will be glad to provide a revised or additional patch in response to any comments.

          Show
          Kim Haase added a comment - I plan to commit this patch on October 8 and backport it to 10.5. I will be glad to provide a revised or additional patch in response to any comments.
          Hide
          Kim Haase added a comment -

          I'm filing a revised patch to correct some technical errors in the previous patch (the use of the encryptionAlgorithm attribute with an already encrypted database, for example) as well as some typos and inconsistencies.

          Attaching DERBY-5805-2.diff, DERBY-5805-2.stat, and DERBY-5805-2.zip, with changes to one more file, src/ref/rrefattribnewbootpw.dita, in addition to those in the previous patch:

          M src/ref/rrefattrib60346.dita
          M src/ref/rrefattrib88843.dita
          M src/ref/rrefattribencryptkey.dita
          M src/ref/refderby.ditamap
          M src/ref/rrefattribnewbootpw.dita
          M src/ref/rrefattrib15290.dita
          M src/ref/rrefattribencryptkeylength.dita
          M src/ref/rrefattrib42100.dita
          M src/ref/rrefattribnewencryptkey.dita

          I plan to commit this patch tomorrow unless I hear of additional corrections.

          Show
          Kim Haase added a comment - I'm filing a revised patch to correct some technical errors in the previous patch (the use of the encryptionAlgorithm attribute with an already encrypted database, for example) as well as some typos and inconsistencies. Attaching DERBY-5805 -2.diff, DERBY-5805 -2.stat, and DERBY-5805 -2.zip, with changes to one more file, src/ref/rrefattribnewbootpw.dita, in addition to those in the previous patch: M src/ref/rrefattrib60346.dita M src/ref/rrefattrib88843.dita M src/ref/rrefattribencryptkey.dita M src/ref/refderby.ditamap M src/ref/rrefattribnewbootpw.dita M src/ref/rrefattrib15290.dita M src/ref/rrefattribencryptkeylength.dita M src/ref/rrefattrib42100.dita M src/ref/rrefattribnewencryptkey.dita I plan to commit this patch tomorrow unless I hear of additional corrections.
          Hide
          Knut Anders Hatlen added a comment -

          I've read through the patch, and all the changes looked consistent with the findings documented in the earlier comments on this issue. +1

          Show
          Knut Anders Hatlen added a comment - I've read through the patch, and all the changes looked consistent with the findings documented in the earlier comments on this issue. +1
          Hide
          Kim Haase added a comment -

          Thanks very much, Knut.

          Committed patch DERBY-5805-2.diff to documentation trunk at revision 1396068.
          Merged to 10.9 doc branch at revision 1396078.
          Merged to 10.8 doc branch at revision 1396141.
          Merged to 10.7 doc branch at revision 1396146.
          Merged to 10.6 doc branch at revision 1396154.
          Merged to 10.5 doc branch at revision 1396175.

          Show
          Kim Haase added a comment - Thanks very much, Knut. Committed patch DERBY-5805 -2.diff to documentation trunk at revision 1396068. Merged to 10.9 doc branch at revision 1396078. Merged to 10.8 doc branch at revision 1396141. Merged to 10.7 doc branch at revision 1396146. Merged to 10.6 doc branch at revision 1396154. Merged to 10.5 doc branch at revision 1396175.
          Hide
          Kim Haase added a comment -

          Closing, since trunk changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Closing, since trunk changes have appeared in Latest Alpha Manuals.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development