Derby
  1. Derby
  2. DERBY-4229

encryptionKeyLength connection attribute should be documented

    Details

      Description

      The developer guide says:

      The length of the encryption key depends on the algorithm used:
      AES (128, 192, and 256 bits)
      DES (the default) (56 bits)
      DESede (168 bits)
      All other algorithms (128 bits)
      Note: The boot password should have at least as many characters as number of bytes in the encryption key (56 bits=8 bytes, 168 bits=24 bytes, 128 bits=16 bytes). The minimum number of characters for the boot password allowed by Derby is eight.

      For AES, however, it does not tell how to change the default key length of 128. This can be changed with the encryptionKeyLength connection attribute. The documentation should also specify that special policy files for the JRE may be necessary to accomodate the longer length.

      Also note that there is an outstanding issue DERBY-3710 regarding length of 192 for AES.

      1. DERBY-4229-3.diff
        5 kB
        Kim Haase
      2. rrefattribencryptkeylength.html
        5 kB
        Kim Haase
      3. rrefattribencryptkeylength.html
        5 kB
        Kim Haase
      4. DERBY-4229-2.stat
        0.1 kB
        Kim Haase
      5. DERBY-4229-2.diff
        4 kB
        Kim Haase
      6. cdevcsecure67151.html
        6 kB
        Kim Haase
      7. DERBY-4229.diff
        2 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Attaching DERBY-4229.diff and cdevcsecure67151.html, which I hope provide the information needed here. The topic where the information seems to belong is "Specifying an alternate encryption algorithm."

          I've added one sentence that I hope also fixes DERBY-2821, an issue filed a long time ago.

          Show
          Kim Haase added a comment - Attaching DERBY-4229 .diff and cdevcsecure67151.html, which I hope provide the information needed here. The topic where the information seems to belong is "Specifying an alternate encryption algorithm." I've added one sentence that I hope also fixes DERBY-2821 , an issue filed a long time ago.
          Hide
          Kim Haase added a comment -

          DERBY-4229 and DERBY-2821 both require fixes to the same topic.

          Show
          Kim Haase added a comment - DERBY-4229 and DERBY-2821 both require fixes to the same topic.
          Hide
          Myrna van Lunteren added a comment -

          These changes look good to me.

          Show
          Myrna van Lunteren added a comment - These changes look good to me.
          Hide
          Kim Haase added a comment -

          Thanks very much, Myrna.

          Committed patch DERBY-4229.diff to documentation trunk at revision 777141.
          Merged to 10.5 branch at revision 777148.

          Show
          Kim Haase added a comment - Thanks very much, Myrna. Committed patch DERBY-4229 .diff to documentation trunk at revision 777141. Merged to 10.5 branch at revision 777148.
          Hide
          Kim Haase added a comment -

          Fix now appears in Latest Alpha Manuals, so closing issue.

          Show
          Kim Haase added a comment - Fix now appears in Latest Alpha Manuals, so closing issue.
          Hide
          Kim Haase added a comment -

          In a comment on DERBY-5805, Kristian Waagan pointed out that the encryptionKeyLength attribute wasn't documented in the Reference Manual (the only fix was to correct the Developer's Guide). I'll create a new topic for this attribute.

          Show
          Kim Haase added a comment - In a comment on DERBY-5805 , Kristian Waagan pointed out that the encryptionKeyLength attribute wasn't documented in the Reference Manual (the only fix was to correct the Developer's Guide). I'll create a new topic for this attribute.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-4229-2.diff, DERBY-4229-2.stat, and rrefattribencryptkeylength.html, with the following changes:

          A src/ref/rrefattribencryptkeylength.dita
          M src/ref/refderby.ditamap

          I'm guessing on a few things, so please check the new topic carefully!

          In particular, is the note at the end true? Seems as if it should be (I extrapolated from the note at the end of the encryptionAlgorithm topic).

          Also, what happens if you use encryptionKeyLength with the encryptionKey attribute instead of with bootPassword? Is it ignored, is there an error, or is there an error only if the specified length is different from the actual length?

          Thanks in advance.

          Show
          Kim Haase added a comment - Attaching DERBY-4229 -2.diff, DERBY-4229 -2.stat, and rrefattribencryptkeylength.html, with the following changes: A src/ref/rrefattribencryptkeylength.dita M src/ref/refderby.ditamap I'm guessing on a few things, so please check the new topic carefully! In particular, is the note at the end true? Seems as if it should be (I extrapolated from the note at the end of the encryptionAlgorithm topic). Also, what happens if you use encryptionKeyLength with the encryptionKey attribute instead of with bootPassword? Is it ignored, is there an error, or is there an error only if the specified length is different from the actual length? Thanks in advance.
          Hide
          Dag H. Wanvik added a comment - - edited

          > The encryptionKeyLength=length attribute may also be combined with the encryptionProvider=providerName
          > and/or encryptionAlgorithm=algorithm attributes. You may wish to use encryptionKeyLength=length when
          > you specify a non-default encryption algorithm.

          If seems you'd want to use eKL only iff a) one wants a non default algorithm (default is DES) and b) the algorithm allows for more than one key length (AES is mentioned above) and c) one wants a key length that is not default (AES 192 or 256 above).

          We should investigate your other questions, Kim, good ones!

          Show
          Dag H. Wanvik added a comment - - edited > The encryptionKeyLength=length attribute may also be combined with the encryptionProvider=providerName > and/or encryptionAlgorithm=algorithm attributes. You may wish to use encryptionKeyLength=length when > you specify a non-default encryption algorithm. If seems you'd want to use eKL only iff a) one wants a non default algorithm (default is DES) and b) the algorithm allows for more than one key length (AES is mentioned above) and c) one wants a key length that is not default (AES 192 or 256 above). We should investigate your other questions, Kim, good ones!
          Hide
          Dag H. Wanvik added a comment - - edited

          It seems encryptionKeyLength can be used with both bootPassword and encryptionKey, cf this code comment in JCECipherFactory.java:

          490 // note: Attribute.CRYPTO_KEY_LENGTH is set during creation time to a supported
          491 // key length in the connection url. Internally , two values are stored in this property
          492 // if encryptionKey is used, this property will have only the encoded key length
          493 // if boot password mechanism is used, this property will have the following
          494 // keylengthBits-EncodedKeyLength

          Using both bootPassword and encryptionKey throws an exception, cf. this code:

          // incorrect to specify external key and boot password
          563 if (properties.getProperty((newAttrs ?
          564 Attribute.NEW_BOOT_PASSWORD :
          565 Attribute.BOOT_PASSWORD)) != null)
          566 throw StandardException.newException(SQLState.SERVICE_WRONG_BOOT_PASSWORD);

          SERVICE_WRONG_BOOT_PASSWORD is SQL state "XBM06", btw, but I don't think we document that..

          • Your question as to the final statement in the docs: Now, if the keylength specified is wrong, the code call

          > keyGen.init(keyLengthBits);

          will throw InvalidParameterException in JCECipherFactory#generateUniqueBytes. IPE is not a checked exception, so presumably it would get caught somewhere, and converted to an SQLException, new test in order!!

          Show
          Dag H. Wanvik added a comment - - edited It seems encryptionKeyLength can be used with both bootPassword and encryptionKey, cf this code comment in JCECipherFactory.java: 490 // note: Attribute.CRYPTO_KEY_LENGTH is set during creation time to a supported 491 // key length in the connection url. Internally , two values are stored in this property 492 // if encryptionKey is used, this property will have only the encoded key length 493 // if boot password mechanism is used, this property will have the following 494 // keylengthBits-EncodedKeyLength Using both bootPassword and encryptionKey throws an exception, cf. this code: // incorrect to specify external key and boot password 563 if (properties.getProperty((newAttrs ? 564 Attribute.NEW_BOOT_PASSWORD : 565 Attribute.BOOT_PASSWORD)) != null) 566 throw StandardException.newException(SQLState.SERVICE_WRONG_BOOT_PASSWORD); SERVICE_WRONG_BOOT_PASSWORD is SQL state "XBM06", btw, but I don't think we document that.. Your question as to the final statement in the docs: Now, if the keylength specified is wrong, the code call > keyGen.init(keyLengthBits); will throw InvalidParameterException in JCECipherFactory#generateUniqueBytes. IPE is not a checked exception, so presumably it would get caught somewhere, and converted to an SQLException, new test in order!!
          Hide
          Kim Haase added a comment -

          Thanks, Dag, for that information! I'm attaching DERBY-4229-3.diff and rrefattribencryptkeylength.html, which I hope make appropriate changes.

          I'm guessing that you would get an error if you specified an encryption key that was inconsistent with the specified encryption key length?

          Show
          Kim Haase added a comment - Thanks, Dag, for that information! I'm attaching DERBY-4229 -3.diff and rrefattribencryptkeylength.html, which I hope make appropriate changes. I'm guessing that you would get an error if you specified an encryption key that was inconsistent with the specified encryption key length?
          Hide
          Kim Haase added a comment -

          I'll commit this tomorrow morning (9/26) unless I hear otherwise, since I need to get this topic in before filing a patch for DERBY-5805.

          Show
          Kim Haase added a comment - I'll commit this tomorrow morning (9/26) unless I hear otherwise, since I need to get this topic in before filing a patch for DERBY-5805 .
          Hide
          Dag H. Wanvik added a comment -

          Yes, KeyGenerator.init called with the wrong key size throws java.security.InvalidParameterException. I tested and saw:

          SQLException XJ001
          java.sql.SQLException: Exception from Cryptography provider. See next exception for details.
          Caused by: java.sql.SQLException: Exception from Cryptography provider. See next exception for details.
          Caused by: java.security.InvalidKeyException: Illegal key size

          Show
          Dag H. Wanvik added a comment - Yes, KeyGenerator.init called with the wrong key size throws java.security.InvalidParameterException. I tested and saw: SQLException XJ001 java.sql.SQLException: Exception from Cryptography provider. See next exception for details. Caused by: java.sql.SQLException: Exception from Cryptography provider. See next exception for details. Caused by: java.security.InvalidKeyException: Illegal key size
          Hide
          Dag H. Wanvik added a comment -

          Otherwise, +1.

          Show
          Dag H. Wanvik added a comment - Otherwise, +1.
          Hide
          Kim Haase added a comment -

          Thanks, Dag! I will commit this and backport it to 10.5, since that's when the issue was first filed.

          Show
          Kim Haase added a comment - Thanks, Dag! I will commit this and backport it to 10.5, since that's when the issue was first filed.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-4229-3.diff to documentation trunk at revision 1390488.
          Merged to 10.9 doc branch at revision 1390508.

          Show
          Kim Haase added a comment - Committed patch DERBY-4229 -3.diff to documentation trunk at revision 1390488. Merged to 10.9 doc branch at revision 1390508.
          Hide
          Kim Haase added a comment -

          Merged patch DERBY-4229-3.diff to 10.8 doc branch at revision 1390515.
          Merged to 10.7 doc branch at revision 1390533.
          Merged to 10.6 doc branch at revision 1390543.
          Merged to 10.5 doc branch at revision 1390554.

          Show
          Kim Haase added a comment - Merged patch DERBY-4229 -3.diff to 10.8 doc branch at revision 1390515. Merged to 10.7 doc branch at revision 1390533. Merged to 10.6 doc branch at revision 1390543. Merged to 10.5 doc branch at revision 1390554.
          Hide
          Kim Haase added a comment -

          Hm. If I specify encryptionKey and an invalid encryptionKeyLength without specifying an encryptionAlgorithm, there's no error:

          jdench 49 =>java -jar $DERBY_HOME/jars/insane/derbyrun.jar ij
          ij version 10.10
          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionKeyLength=5';
          ij>

          Derby seems to ignore the length if the key is specified.

          The following URLs also succeed with no error – specifying the default algorithm, and either the default key length or an incorrect key length:

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding';

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKeyLength=128';

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKeyLength=5';

          On the other hand, if I specify an encryptionKey of the default length with a non-default encryptionAlgorithm, I get an error:

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=AES/CBC/NoPadding';
          ERROR XJ041: Failed to create database 'encDB', see the next exception for details.
          ERROR XBM01: Startup failed due to an exception. See next exception for details.
          ERROR XBCX0: Exception from Cryptography provider. See next exception for details.
          ERROR XJ001: Java exception: 'Invalid key for AES: java.security.InvalidKeyException'.
          ERROR XJ001: Java exception: 'Key length must be between 128 and 256 bits: java.security.InvalidAlgorithmParameterException'.
          ij>

          I think the key length is 128, so the error message is mysterious. I get the same error if I add "encryptionKeyLength=128" to the URL. I haven't tried with a non-default key length because that requires a different policy file, according to "Specifying an alternate encryption algorithm" in the Developer's Guide.

          Show
          Kim Haase added a comment - Hm. If I specify encryptionKey and an invalid encryptionKeyLength without specifying an encryptionAlgorithm, there's no error: jdench 49 =>java -jar $DERBY_HOME/jars/insane/derbyrun.jar ij ij version 10.10 ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionKeyLength=5'; ij> Derby seems to ignore the length if the key is specified. The following URLs also succeed with no error – specifying the default algorithm, and either the default key length or an incorrect key length: ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding'; ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKeyLength=128'; ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=DES/CBC/NoPadding;encryptionKeyLength=5'; On the other hand, if I specify an encryptionKey of the default length with a non-default encryptionAlgorithm, I get an error: ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;encryptionKey=6162636465666768;encryptionAlgorithm=AES/CBC/NoPadding'; ERROR XJ041: Failed to create database 'encDB', see the next exception for details. ERROR XBM01: Startup failed due to an exception. See next exception for details. ERROR XBCX0: Exception from Cryptography provider. See next exception for details. ERROR XJ001: Java exception: 'Invalid key for AES: java.security.InvalidKeyException'. ERROR XJ001: Java exception: 'Key length must be between 128 and 256 bits: java.security.InvalidAlgorithmParameterException'. ij> I think the key length is 128, so the error message is mysterious. I get the same error if I add "encryptionKeyLength=128" to the URL. I haven't tried with a non-default key length because that requires a different policy file, according to "Specifying an alternate encryption algorithm" in the Developer's Guide.
          Hide
          Kim Haase added a comment -

          On the other hand, if I use bootPassword with an invalid encryptionKeyLength, other interesting things happen.

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionKeyLength=5';
          ERROR XJ041: Failed to create database 'encDB', see the next exception for details.
          ERROR XBM01: Startup failed due to an exception. See next exception for details.
          ERROR XJ001: Java exception: ': java.security.InvalidParameterException'.
          ERROR XJ001: Java exception: 'DES key length must be 56 bits: java.security.InvalidAlgorithmParameterException'.

          This is interesting, because we say the default key length is 128. If I specify 56, I get no error. But if I specify 128, I get an error:

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionKeyLength=128';
          ERROR XJ041: Failed to create database 'encDB', see the next exception for details.
          ERROR XBM01: Startup failed due to an exception. See next exception for details.
          ERROR XJ001: Java exception: ': java.security.InvalidParameterException'.
          ERROR XJ001: Java exception: 'DES key length must be 56 bits: java.security.InvalidAlgorithmParameterException'.

          Apparently the default is 128 for AES, not for DES. The following command succeeds:

          ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionAlgorithm=AES/CBC/NoPadding;encryptionKeyLength=128';

          So why did a 128-bit encryptionKey argument succeed?

          Show
          Kim Haase added a comment - On the other hand, if I use bootPassword with an invalid encryptionKeyLength, other interesting things happen. ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionKeyLength=5'; ERROR XJ041: Failed to create database 'encDB', see the next exception for details. ERROR XBM01: Startup failed due to an exception. See next exception for details. ERROR XJ001: Java exception: ': java.security.InvalidParameterException'. ERROR XJ001: Java exception: 'DES key length must be 56 bits: java.security.InvalidAlgorithmParameterException'. This is interesting, because we say the default key length is 128. If I specify 56, I get no error. But if I specify 128, I get an error: ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionKeyLength=128'; ERROR XJ041: Failed to create database 'encDB', see the next exception for details. ERROR XBM01: Startup failed due to an exception. See next exception for details. ERROR XJ001: Java exception: ': java.security.InvalidParameterException'. ERROR XJ001: Java exception: 'DES key length must be 56 bits: java.security.InvalidAlgorithmParameterException'. Apparently the default is 128 for AES, not for DES. The following command succeeds: ij> connect 'jdbc:derby:encDB;create=true;dataEncryption=true;bootPassword=Thursday;encryptionAlgorithm=AES/CBC/NoPadding;encryptionKeyLength=128'; So why did a 128-bit encryptionKey argument succeed?
          Hide
          Kim Haase added a comment -

          Closing, since changes have appeared in Latest Alpha Manuals.

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

          Removing 10.5.2.0 as the issue was fixed in 10.5.3.1. I think it causes the issue to not show up in the release notes (just guessing)

          Show
          Kathey Marsden added a comment - Removing 10.5.2.0 as the issue was fixed in 10.5.3.1. I think it causes the issue to not show up in the release notes (just guessing)
          Hide
          Kim Haase added a comment -

          I have a theory that the issue also has to be closed to show up in the release notes ... no harm, anyway. Thanks for the version fix, Kathey.

          Show
          Kim Haase added a comment - I have a theory that the issue also has to be closed to show up in the release notes ... no harm, anyway. Thanks for the version fix, Kathey.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kathey Marsden
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development