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.