Derby
  1. Derby
  2. DERBY-4579

Document the configurable hash authentication scheme

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.6.1.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      DERBY-4483 adds the ability to configure which message digest algorithm to use to protect the passwords that are stored in the database when using BUILTIN authentication.

      I think these changes are required:

      • Reference manual: Document the new database property derby.authentication.builtin.algorithm. It's a dynamic property that can be set either on database level or on system level. Its value is the name of a message digest algorithm available from one of the Java Cryptography Extension providers registered in the JVM. Example values: MD5, SHA-256, SHA-512. The specified algorithm will be applied on the concatenation of the user name and the password before it's stored in the database. If the property is NULL or the empty string, the old algorithm (SHA-1 on the password only) is applied instead.
      • Developer's guide: Mention the property in "List of user authentication properties"
      • Server and admin guide: In the table in section "Network client security", mention that strong password substitution cannot be used to connect as a user whose password has been stored with the new scheme. I'd suggest changing the following sentence:

      Strong password substitution cannot be used with external Derby authentication schemes (for example, LDAP).

      And replacing it with something like:

      Strong password substitution can only be used with Derby's NONE and BUILTIN authentication schemes. Also, for the BUILTIN scheme, it does not work for database-level users whose password has been protected by a custom message digest algorithm specified by the derby.authentication.builtin.algorithm property.

      1. DERBY-4579.diff
        9 kB
        Kim Haase
      2. DERBY-4579.stat
        0.2 kB
        Kim Haase
      3. DERBY-4579.zip
        13 kB
        Kim Haase
      4. DERBY-4579-2.diff
        9 kB
        Kim Haase
      5. DERBY-4579-2.zip
        13 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Committed patch DERBY-4579-2.diff to documentation trunk at revision 936934.

          Show
          Kim Haase added a comment - Committed patch DERBY-4579 -2.diff to documentation trunk at revision 936934.
          Hide
          Kim Haase added a comment -

          Thanks very much, Knut. I've incorporated your edits into a second patch (DERBY-4579-2.diff and DERBY-4579-2.zip), which I'll commit. I put the added sentence under Syntax.

          Show
          Kim Haase added a comment - Thanks very much, Knut. I've incorporated your edits into a second patch ( DERBY-4579 -2.diff and DERBY-4579 -2.zip), which I'll commit. I put the added sentence under Syntax.
          Hide
          Knut Anders Hatlen added a comment -

          Hi Kim,

          This looks great. Thank you very much for writing it up! I only have a
          couple of minor comments to the new section in the reference manual:

          1) We should add one more sentence under "Function":

          "If the property is NULL or an empty string, SHA-1 will be used on
          the password only."

          2) Under "Default", it says "If SHA-256 is not available, the default
          is SHA-1 on the password only." The last part should be changed to
          "(...), the default is SHA-1."

          3) Under "Dynamic or static", we may want to add that the setting only
          affects passwords that are updated after the property has been
          changed. Existing passwords are not touched.

          Show
          Knut Anders Hatlen added a comment - Hi Kim, This looks great. Thank you very much for writing it up! I only have a couple of minor comments to the new section in the reference manual: 1) We should add one more sentence under "Function": "If the property is NULL or an empty string, SHA-1 will be used on the password only." 2) Under "Default", it says "If SHA-256 is not available, the default is SHA-1 on the password only." The last part should be changed to "(...), the default is SHA-1." 3) Under "Dynamic or static", we may want to add that the setting only affects passwords that are updated after the property has been changed. Existing passwords are not touched.
          Hide
          Kim Haase added a comment -

          Thanks, Knut. I hope this patch (DERBY-4579.diff, DERBY-4579.stat, DERBY-4579.zip) covers what you had hoped.

          For the Admin Guide topic I also made a formatting fix (paragraph element) that improves the appearance of the output.

          Show
          Kim Haase added a comment - Thanks, Knut. I hope this patch ( DERBY-4579 .diff, DERBY-4579 .stat, DERBY-4579 .zip) covers what you had hoped. For the Admin Guide topic I also made a formatting fix (paragraph element) that improves the appearance of the output.
          Hide
          Knut Anders Hatlen added a comment -

          One more thing. After this issue was filed, the new authentication mechanism has been made the default for BUILTIN in new databases. At database creation time, the property will be initialized to SHA-256 (or under certain conditions SHA-1 because of DERBY-4602). We may want to state that in the documentation for the property. For example: "In a newly created database, the value of this property will be either SHA-256, if it is available on the platform, or SHA-1 otherwise."

          Show
          Knut Anders Hatlen added a comment - One more thing. After this issue was filed, the new authentication mechanism has been made the default for BUILTIN in new databases. At database creation time, the property will be initialized to SHA-256 (or under certain conditions SHA-1 because of DERBY-4602 ). We may want to state that in the documentation for the property. For example: "In a newly created database, the value of this property will be either SHA-256, if it is available on the platform, or SHA-1 otherwise."
          Hide
          Kim Haase added a comment -

          That's very helpful, Knut – thanks very much.

          Show
          Kim Haase added a comment - That's very helpful, Knut – thanks very much.
          Hide
          Knut Anders Hatlen added a comment -

          Hi Kim. Thanks for picking up this issue.

          > Which is the case for this property? I'm guessing it takes effect
          > immediately, but I want to make sure.

          Yes, the changes take effect immediately.

          > I'm not aware of a NONE scheme; for the
          > derby.authentication.provider property the possibilities are LDAP,
          > BUILTIN, and a Java class name, which I thought also indicated the
          > use of an external authentication scheme.

          You're right, NONE isn't mentioned in the documentation. There is a
          no-op authentication service implementation class called
          NoneAuthenticationServiceImpl, and it's sometimes referred to as NONE
          in code comments. This is the authentication service that's used when
          authentication is disabled. I guess it's clearer if we say
          "authentication disabled" instead of "the NONE authentication
          service"...

          > So is it only BUILTIN that you can use strong password substitution
          > with?

          It is possible to use strong password substitution with (old) BUILTIN
          and when authentication is turned off. Using password substitution
          when authentication is turned off may perhaps not make much sense, but
          it is possible (you can specify user name and password when
          authentication is disabled, and they will be sent to the server, they
          just won't be checked).

          Hope this made things clearer.

          Show
          Knut Anders Hatlen added a comment - Hi Kim. Thanks for picking up this issue. > Which is the case for this property? I'm guessing it takes effect > immediately, but I want to make sure. Yes, the changes take effect immediately. > I'm not aware of a NONE scheme; for the > derby.authentication.provider property the possibilities are LDAP, > BUILTIN, and a Java class name, which I thought also indicated the > use of an external authentication scheme. You're right, NONE isn't mentioned in the documentation. There is a no-op authentication service implementation class called NoneAuthenticationServiceImpl, and it's sometimes referred to as NONE in code comments. This is the authentication service that's used when authentication is disabled. I guess it's clearer if we say "authentication disabled" instead of "the NONE authentication service"... > So is it only BUILTIN that you can use strong password substitution > with? It is possible to use strong password substitution with (old) BUILTIN and when authentication is turned off. Using password substitution when authentication is turned off may perhaps not make much sense, but it is possible (you can specify user name and password when authentication is disabled, and they will be sent to the server, they just won't be checked). Hope this made things clearer.
          Hide
          Kim Haase added a comment -

          I've run into a couple of questions working on this –

          Reference topic:

          For dynamic properties, we say either

          Dynamic; the change takes effect immediately.

          or

          Dynamic. Current connection is not affected, but all future connections
          are affected.

          Which is the case for this property? I'm guessing it takes effect immediately, but I want to make sure.

          Admin Guide topic:

          You suggest saying, "Strong password substitution can only be used with Derby's NONE and BUILTIN authentication schemes." I'm not aware of a NONE scheme; for the derby.authentication.provider property the possibilities are LDAP, BUILTIN, and a Java class name, which I thought also indicated the use of an external authentication scheme. So is it only BUILTIN that you can use strong password substitution with?

          Thanks for any help.

          Show
          Kim Haase added a comment - I've run into a couple of questions working on this – Reference topic: For dynamic properties, we say either Dynamic; the change takes effect immediately. or Dynamic. Current connection is not affected, but all future connections are affected. Which is the case for this property? I'm guessing it takes effect immediately, but I want to make sure. Admin Guide topic: You suggest saying, "Strong password substitution can only be used with Derby's NONE and BUILTIN authentication schemes." I'm not aware of a NONE scheme; for the derby.authentication.provider property the possibilities are LDAP, BUILTIN, and a Java class name, which I thought also indicated the use of an external authentication scheme. So is it only BUILTIN that you can use strong password substitution with? Thanks for any help.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Knut Anders Hatlen
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development