Towards a more secure API design (for JWT at least)

I've recently started working on vert.x - however, I was surprised about the JWT-API and its documentation.

I'd suggest re-considering its design in a more usable and secure way, hence addressing usable security from an API perspective.

I'd like to suggest these improvements. These ideas resulted from working with the JWT-API for a few hours - not a review or audit.

* [ ] Use arrays (byte arrays, char arrays) instead of passwords. Many Java APIs do so (for instance https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/security/KeyStore.html#getInstance(java.io.File,char%5B%5D) - whereas Vert.x does not (for instance: https://vertx.io/docs/apidocs/io/vertx/ext/auth/KeyStoreOptions.html#setPassword-java.lang.String-) . This is a security thing: Arrays are mutable and can be wiped out of memory, whereas Strings cannot. Hence, it's widespread practice to do so.

* [ ] Document best-practices for using the JWT integration. This may be obvious for an experienced programmer, but dangerous for a not-so crypto savvy one.

* [ ] Looking at https://vertx.io/docs/vertx-auth-jwt/java/ - secret key material is encoded in java source code. This is broken and insecure. Please provide a best-practice example for using this API in a secure manner - please avoid insecure examples without outlining their danger.

* [ ] https://vertx.io/docs/vertx-web/java/#_jwt_authentication - encodes the password in plain-text. At least, it says that this is insecure. However, it would be better to provide a secure example that can be used as best practice - i.e., how would one use an authentication provider

* [ ] Be more explicit about the algorithmic recommendations in https://vertx.io/docs/vertx-auth-jwt/java/. For instance, I do not yet see why one should generate a 2048-Bit key for a HS256 using keytool. 2048-Bit is typically used in asymmetric schemes, whereas HS256 is a symmetric one.

* [ ] Be explicit on encodings - for instance, by try and error I noticed that `HashingStrategy` requires the salt to be base64-encoded, whereas Java (PBEKeySpec) requires a non-encoded array. This is dangerous. For the compiler, strings are strings. But from a crypto-perspective, the byte-entropy of a base64-encoded string (i.e. printable ascii characters) is 6-bit. In result, confusing encoded and non-encoded data could result in weak passwords, salts and keys.