Sync faq from master

Author: mrotteveel

src/docs/asciidoc/faq.adoc

@@ -7,12 +7,12 @@
 :source-highlighter: prettify
 :toc: left
 :icons: font
-:jaybird6-full-version: 6.0.0
-:jaybird6-jna-version: 5.16.0
-:jaybird5-full-version: 5.0.6
+:jaybird6-full-version: 6.0.1
+:jaybird6-jna-version: 5.17.0
+:jaybird5-full-version: 5.0.7
 :jaybird5-template-version: {jaybird5-full-version}.<java>
 :jaybird5-example-version: {jaybird5-full-version}.java11
-:jaybird5-jna-version: 5.15.0
+:jaybird5-jna-version: 5.17.0
 :jaybird4-full-version: 4.0.10
 :jaybird4-template-version: {jaybird4-full-version}.<java>
 :jaybird4-example-version: {jaybird4-full-version}.java11
@@ -23,6 +23,13 @@
 :sectnums:
 :fb-canonical-html: https://firebirdsql.org/docs/drivers/java/faq.html
 
+////
+SPDX-FileCopyrightText: Copyright 2021-2024 Firebird development team and individual contributors
+SPDX-FileCopyrightText: Copyright 2002-2004 Rick Fincher
+SPDX-FileCopyrightText: Copyright 2013-2025 Mark Rotteveel
+SPDX-License-Identifier: LicenseRef-PDL-1.0
+////
+
 [#jaybird]
 = Jaybird
 
@@ -324,14 +331,14 @@ Future versions of Jaybird may specify an explicit version, or be released under
 [discrete]
 === Jaybird 6
 
-Jaybird 6 supports Java 17, Java 21, and Java 23.
+Jaybird 6 supports Java 17, Java 21, and Java 24.
 Support for Java 17 and higher is limited to Java 17, Java 21, -- once available -- the latest LTS after Java 21, and the latest Java release.
 
 [#java-jaybird-5]
 [discrete]
 === Jaybird 5
 
-Jaybird 5 supports Java 8, Java 11, Java 17, Java 21, and Java 23.
+Jaybird 5 supports Java 8, Java 11, Java 17, Java 21, and Java 24.
 Support for Java 9 and higher is limited to Java 8, Java 11, Java 17, Java 21, -- once available -- the latest LTS version after Java 21, and the latest Java release.
 
 Jaybird 5 is the last version to support Java 8 and Java 11, support has been dropped with Jaybird 6, raising the minimum supported version to Java 17.
@@ -487,7 +494,6 @@ For version specific details, consult the release notes
 * The {firebird-java}[Firebird-Java group] and corresponding mailing list firebird-java@googlegroups.com
 +
 You can subscribe to the mailing list by sending an email to link:mailto:firebird-java+subscribe@googlegroups.com[firebird-java+subscribe@googlegroups.com]
-
 * Looking for professional support of Jaybird?
 Jaybird is now part of the https://tidelift.com/subscription/pkg/maven-org-firebirdsql-jdbc-jaybird?utm_source=maven-org-firebirdsql-jdbc-jaybird&utm_medium=referral&utm_campaign=docs[Tidelift subscription].
 * The https://firebirdsql.org[Firebird project home page]
@@ -559,7 +565,7 @@ Jaybird 4 and higher also support:
  jdbc:firebird:host[/port]:<database>
 
 [#open-officelibre-office-pure-java]
-=== Open Office/Libre Office (Pure Java)
+=== OpenOffice/LibreOffice (Pure Java)
 
 Jaybird 5 and earlier can be used together with OpenOffice and LibreOffice Base.
 To address some compatibility issues (and differences in interpretation of JDBC specifications) a separate sub-protocol is used:
@@ -616,7 +622,7 @@ The JDBC URL sub-protocol `jdbc:firebirdsql:local` and `jdbc:firebird:local` are
  jdbc:firebirdsql:embedded:<database>
 
 Similar to the Firebird client library, however `fbembed.dll` on Windows and `libfbembed.so` on Linux are used, falling back to `fbclient.dll`/`libfbclient.so` under the assumption it provides Embedded functionality.
-Requires correctly installed and configured Firebird embedded library and -- for Jaybird 2.2 or earlier -- the Jaybird native  library, or -- for Jaybird 3 and higher -- the JNA jar file.
+Requires correctly installed and configured Firebird embedded library and -- for Jaybird 2.2 or earlier -- the Jaybird native library, or -- for Jaybird 3 and higher -- the JNA jar file.
 
 Jaybird 4 and higher also support:
 
@@ -698,7 +704,6 @@ To address this error, you can set the default connection character set using on
 * Use connection property `encoding` (alias: `lc_ctype`) with a Firebird character set name.
 +
 Use `encoding=NONE` for the default behavior (with some caveats, see  <<how-does-character-set-none-work,How does character set `NONE` work?>>).
-
 * Use connection property `charSet` (alias: `localEncoding`) with a Java character set name.
 * Use a combination of `encoding` and `charSet`, if you want to reinterpret a Firebird character set in a Java character set other than the default  mapping.
 * By providing a default Firebird character set with system property  `org.firebirdsql.jdbc.defaultConnectionEncoding`.
@@ -738,9 +743,27 @@ On the other hand, this has the benefit that this works for all Jaybird versions
 
 This error means that the user does not exist, or that the specified password is not correct.
 
+The following are common causes authentication can fail with the same error even if the username and password are correct.
+
+==== Cause: authentication plugin mismatch
+
 When connecting to Firebird 3.0 and higher, this error can also mean that the user does exist (with that password), but not for the authentication plugins tried for this connection.
+The list of authentication plugins tried is the conjunction of the plugins offered by the client (connection property `authPlugins`) and the `AuthServer` setting in _firebird.conf_.
+
+For example, Jaybird 2.2.x and earlier only support legacy authentication, if you try to log in as a user created with the _Srp_ user manager, you will get the same error.
+
+Similarly, Jaybird 4 and higher -- by default -- only connect using the _Srp256_ and _Srp_ authentication plugins, which means only users created with the _Srp_ user manager can be authenticated, and users created with _Legacy_UserManager_ cannot be authenticated.
+The recommended solution is to create the user for the _Srp_ user manager (e.g. see https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-security-user.html#fblangref50-security-user-create[Firebird 5.0 `CREATE USER`^], specifically the `USING PLUGIN ...` clause).
+Alternatively, you can set connection property `authPlugins` to `Srp256,Srp,Legacy_Auth` to also try legacy authentication, see also https://firebirdsql.github.io/jaybird-manual/jaybird_manual.html#ref-auth-plugins[Authentication plugins] in the Jaybird manual.
 
-For example, Jaybird 2.2.x and earlier only support legacy authentication, if you try to log in as a user created for SRP authentication, you will get the same error.
+You can check -- as `SYSDBA`, or with `RDB$ADMIN` in the security database -- what user manager(s) were used to create a user in the `SEC$USERS` virtual table.
+
+==== Cause: case-sensitive username
+
+With Firebird 3.0 and higher, this error can also be the result of using a case-sensitive username (i.e. the username was quoted, e.g. `CREATE USER "lowercaseuser" ...`).
+
+To login, you must surround the username with quotes so it's handled case-sensitive.
+In a Java string literal, that means using `"\"lowercaseuser\""` instead of `"lowercaseuser"`.
 
 [#incompatible-wire-encryption-levels-requested-on-client-and-server-335545064]
 === Incompatible wire encryption levels requested on client and server (335545064)
@@ -776,7 +799,7 @@ Relax this setting (in `firebird.conf`) to `WireCrypt = Enabled`.
 
 See also https://github.com/FirebirdSQL/jaybird/wiki/Jaybird-and-Firebird-3[Jaybird Wiki -- Jaybird and Firebird 3].
 
-Make sure you check the other settings mentioned in that article, otherwise you'll get the next error.
+Make sure you check the other settings mentioned in that article, otherwise you'll get another error (<<error-occurred-during-login-please-check-server-firebird-log-for-details-335545106>>).
 
 [#cause-unsupported-protocol]
 ==== Cause: unsupported protocol version
@@ -969,3 +992,23 @@ With Jaybird 3.0.4 and higher for Java 7 (but not Java 8!) in Wildfly (or JBoss)
 ----
 
 Alternatively, use Jaybird for Java 8 (or higher).
+
+[appendix#license-notice]
+== License Notice
+
+The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”);
+you may only use this Documentation if you comply with the terms of this License.
+A copy of the License is available at https://firebirdsql.org/en/public-documentation-license/.
+
+The Original Documentation is "`Jaybird Frequently Asked Questions`".
+The Initial Writer of the Original Documentation is Mark Rotteveel, Copyright © 2013-2025.
+All Rights Reserved.
+(Initial Writer contact(s): mark (at) lawinegevaar (dot) nl).
+
+Contributor(s): Rick Fincher. +
+Portions created by Rick Fincher are Copyright © 2002-2004.
+All Rights Reserved.
+(Contributor contact(s): _unknown_).
+
+The exact file history is recorded in our Git repository;
+see https://github.com/FirebirdSQL/jaybird