Added note about DER encoding requirement for all pub/priv key files …

…for token auth (apache#9617)

### Motivation

Added a note about required encoding type (DER) for public/private keys used to token auth.
Added missing `tokenPublicKey` and `tokenSecretKey` fields and associated comments to conf/standalone.conf.

### Modifications

Added notes about DER-encoding requirement for all instances of `tokenPublicKey` and `tokenSecretKey` in the documentation and reference config files.

### Verifying this change

This change is a documentation update without any test coverage.

### Documentation

This change is a documentation update.

conf/broker.conf

@@ -625,14 +625,14 @@ anonymousUserRole=
 # Configure the secret key to be used to validate auth tokens
 # The key can be specified like:
 # tokenSecretKey=data:;base64,xxxxxxxxx
-# tokenSecretKey=file:///my/secret.key
+# tokenSecretKey=file:///my/secret.key    ( Note: key file must be DER-encoded )
 tokenSecretKey=
 
 ## Asymmetric public/private key pair
 # Configure the public key to be used to validate auth tokens
 # The key can be specified like:
 # tokenPublicKey=data:;base64,xxxxxxxxx
-# tokenPublicKey=file:///my/public.key
+# tokenPublicKey=file:///my/public.key    ( Note: key file must be DER-encoded )
 tokenPublicKey=
 
 # The token "claim" that will be interpreted as the authentication "role" or "principal" by AuthenticationProviderToken (defaults to "sub" if blank)

conf/proxy.conf

@@ -202,14 +202,14 @@ httpRequestsMaxPerSecond=100.0
 # Configure the secret key to be used to validate auth tokens
 # The key can be specified like:
 # tokenSecretKey=data:;base64,xxxxxxxxx
-# tokenSecretKey=file:///my/secret.key
+# tokenSecretKey=file:///my/secret.key    ( Note: key file must be DER-encoded )
 tokenSecretKey=
 
 ## Asymmetric public/private key pair
 # Configure the public key to be used to validate auth tokens
 # The key can be specified like:
 # tokenPublicKey=data:;base64,xxxxxxxxx
-# tokenPublicKey=file:///my/public.key
+# tokenPublicKey=file:///my/public.key    ( Note: key file must be DER-encoded )
 tokenPublicKey=
 
 # The token "claim" that will be interpreted as the authentication "role" or "principal" by AuthenticationProviderToken (defaults to "sub" if blank)

conf/standalone.conf

@@ -419,6 +419,24 @@ athenzDomainNames=
 # When this parameter is not empty, unauthenticated users perform as anonymousUserRole
 anonymousUserRole=
 
+
+### --- Token Authentication Provider --- ###
+
+## Symmetric key
+# Configure the secret key to be used to validate auth tokens
+# The key can be specified like:
+# tokenSecretKey=data:;base64,xxxxxxxxx
+# tokenSecretKey=file:///my/secret.key  ( Note: key file must be DER-encoded )
+tokenSecretKey=
+
+## Asymmetric public/private key pair
+# Configure the public key to be used to validate auth tokens
+# The key can be specified like:
+# tokenPublicKey=data:;base64,xxxxxxxxx
+# tokenPublicKey=file:///my/public.key    ( Note: key file must be DER-encoded )
+tokenPublicKey=
+
+
 # The token "claim" that will be interpreted as the authentication "role" or "principal" by AuthenticationProviderToken (defaults to "sub" if blank)
 tokenAuthClaim=
 

deployment/terraform-ansible/templates/broker.conf

@@ -576,14 +576,14 @@ anonymousUserRole=
 # Configure the secret key to be used to validate auth tokens
 # The key can be specified like:
 # tokenSecretKey=data:;base64,xxxxxxxxx
-# tokenSecretKey=file:///my/secret.key
+# tokenSecretKey=file:///my/secret.key    ( Note: key file must be DER-encoded )
 tokenSecretKey=
 
 ## Asymmetric public/private key pair
 # Configure the public key to be used to validate auth tokens
 # The key can be specified like:
 # tokenPublicKey=data:;base64,xxxxxxxxx
-# tokenPublicKey=file:///my/public.key
+# tokenPublicKey=file:///my/public.key    ( Note: key file must be DER-encoded )
 tokenPublicKey=
 
 # The token "claim" that will be interpreted as the authentication "role" or "principal" by AuthenticationProviderToken (defaults to "sub" if blank)

deployment/terraform-ansible/templates/proxy.conf

@@ -189,14 +189,14 @@ httpNumThreads=
 # Configure the secret key to be used to validate auth tokens
 # The key can be specified like:
 # tokenSecretKey=data:;base64,xxxxxxxxx
-# tokenSecretKey=file:///my/secret.key
+# tokenSecretKey=file:///my/secret.key    ( Note: key file must be DER-encoded )
 tokenSecretKey=
 
 ## Asymmetric public/private key pair
 # Configure the public key to be used to validate auth tokens
 # The key can be specified like:
 # tokenPublicKey=data:;base64,xxxxxxxxx
-# tokenPublicKey=file:///my/public.key
+# tokenPublicKey=file:///my/public.key    ( Note: key file must be DER-encoded )
 tokenPublicKey=
 
 # The token "claim" that will be interpreted as the authentication "role" or "principal" by AuthenticationProviderToken (defaults to "sub" if blank)

pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyConfiguration.java

@@ -535,7 +535,7 @@ public class ProxyConfiguration implements PulsarConfiguration {
                         + "Configure the public key to be used to validate auth tokens"
                         + " The key can be specified like:\n\n"
                         + "tokenPublicKey=data:;base64,xxxxxxxxx\n"
-                        + "tokenPublicKey=file:///my/public.key")
+                        + "tokenPublicKey=file:///my/public.key  ( Note: key file must be DER-encoded )")
             ),
             @PropertyContext(
                 key = "tokenSecretKey",
@@ -545,7 +545,7 @@ public class ProxyConfiguration implements PulsarConfiguration {
                         + "Configure the secret key to be used to validate auth tokens"
                         + "The key can be specified like:\n\n"
                         + "tokenSecretKey=data:;base64,xxxxxxxxx\n"
-                        + "tokenSecretKey=file:///my/secret.key")
+                        + "tokenSecretKey=file:///my/secret.key  ( Note: key file must be DER-encoded )")
             )
         }
     )

site2/docs/functions-runtime.md

@@ -265,8 +265,8 @@ superUserRoles:
   - superuser
   - proxy
 properties:
-  tokenSecretKey: file:///etc/pulsar/jwt/secret # if using a secret token
-  tokenPublicKey: file:///etc/pulsar/jwt/public.key # if using public/private key tokens
+  tokenSecretKey: file:///etc/pulsar/jwt/secret # if using a secret token, key file must be DER-encoded
+  tokenPublicKey: file:///etc/pulsar/jwt/public.key # if using public/private key tokens, key file must be DER-encoded
 ```
 
 > **Note**   

site2/docs/functions-worker.md

@@ -156,6 +156,7 @@ properties:
 
 For *Token Authentication* provider, add necessary settings for `properties` if needed.
 See [Token Authentication](security-jwt.md) for more details.
+Note: key files must be DER-encoded
 ```
 properties:
   tokenSecretKey:       file://my/secret.key 

site2/docs/reference-configuration.md

@@ -216,8 +216,8 @@ internalListenerName|Specify the internal listener name for the broker.<br><br>*
 |brokerClientTlsCiphers| Specify the tls cipher the internal client will use to negotiate during TLS Handshake. (a comma-separated list of ciphers) e.g.  [TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256]||
 |brokerClientTlsProtocols|Specify the tls protocols the broker will use to negotiate during TLS handshake. (a comma-separated list of protocol names). e.g.  [TLSv1.2, TLSv1.1, TLSv1] ||
 |ttlDurationDefaultInSeconds|The default Time to Live (TTL) for namespaces if the TTL is not configured at namespace policies. When the value is set to `0`, TTL is disabled. By default, TTL is disabled. |0|
-|tokenSecretKey| Configure the secret key to be used to validate auth tokens. The key can be specified like: `tokenSecretKey=data:;base64,xxxxxxxxx` or `tokenSecretKey=file:///my/secret.key`||
-|tokenPublicKey| Configure the public key to be used to validate auth tokens. The key can be specified like: `tokenPublicKey=data:;base64,xxxxxxxxx` or `tokenPublicKey=file:///my/secret.key`||
+|tokenSecretKey| Configure the secret key to be used to validate auth tokens. The key can be specified like: `tokenSecretKey=data:;base64,xxxxxxxxx` or `tokenSecretKey=file:///my/secret.key`.  Note: key file must be DER-encoded.||
+|tokenPublicKey| Configure the public key to be used to validate auth tokens. The key can be specified like: `tokenPublicKey=data:;base64,xxxxxxxxx` or `tokenPublicKey=file:///my/secret.key`.  Note: key file must be DER-encoded.||
 |tokenPublicAlg| Configure the algorithm to be used to validate auth tokens. This can be any of the asymettric algorithms supported by Java JWT (https://github.com/jwtk/jjwt#signature-algorithms-keys) |RS256|
 |tokenAuthClaim| Specify which of the token's claims will be used as the authentication "principal" or "role". The default "sub" claim will be used if this is left blank ||
 |tokenAudienceClaim| The token audience "claim" name, e.g. "aud", that will be used to get the audience from token. If not set, audience will not be verified. ||
@@ -551,6 +551,8 @@ The value of 0 disables message-byte dispatch-throttling.|0|
 |brokerClientAuthenticationParameters|  The parameters that go along with the plugin specified using brokerClientAuthenticationPlugin.  | |
 |athenzDomainNames| Supported Athenz authentication provider domain names as a comma-separated list.  | |
 | anonymousUserRole | When this parameter is not empty, unauthenticated users perform as anonymousUserRole. | |
+|tokenSecretKey| Configure the secret key to be used to validate auth tokens. The key can be specified like: `tokenSecretKey=data:;base64,xxxxxxxxx` or `tokenSecretKey=file:///my/secret.key`.  Note: key file must be DER-encoded.||
+|tokenPublicKey| Configure the public key to be used to validate auth tokens. The key can be specified like: `tokenPublicKey=data:;base64,xxxxxxxxx` or `tokenPublicKey=file:///my/secret.key`.  Note: key file must be DER-encoded.||
 |tokenAuthClaim| Specify the token claim that will be used as the authentication "principal" or "role". The "subject" field will be used if this is left blank ||
 |tokenAudienceClaim| The token audience "claim" name, e.g. "aud". It is used to get the audience from token. If it is not set, the audience is not verified. ||
 | tokenAudience | The token audience stands for this broker. The field `tokenAudienceClaim` of a valid token need contains this parameter.| |
@@ -743,8 +745,8 @@ The [Pulsar proxy](concepts-architecture-overview.md#pulsar-proxy) can be config
 | httpReverseProxyConfigs | HTTP directs to redirect to non-pulsar services | |
 | httpOutputBufferSize | HTTP output buffer size. The amount of data that will be buffered for HTTP requests before it is flushed to the channel. A larger buffer size may result in higher HTTP throughput though it may take longer for the client to see data. If using HTTP streaming via the reverse proxy, this should be set to the minimum value (1) so that clients see the data as soon as possible. | 32768 |
 | httpNumThreads | Number of threads to use for HTTP requests processing|  2 * Runtime.getRuntime().availableProcessors() |
-|tokenSecretKey| Configure the secret key to be used to validate auth tokens. The key can be specified like: `tokenSecretKey=data:;base64,xxxxxxxxx` or `tokenSecretKey=file:///my/secret.key`||
-|tokenPublicKey| Configure the public key to be used to validate auth tokens. The key can be specified like: `tokenPublicKey=data:;base64,xxxxxxxxx` or `tokenPublicKey=file:///my/secret.key`||
+|tokenSecretKey| Configure the secret key to be used to validate auth tokens. The key can be specified like: `tokenSecretKey=data:;base64,xxxxxxxxx` or `tokenSecretKey=file:///my/secret.key`.  Note: key file must be DER-encoded.||
+|tokenPublicKey| Configure the public key to be used to validate auth tokens. The key can be specified like: `tokenPublicKey=data:;base64,xxxxxxxxx` or `tokenPublicKey=file:///my/secret.key`. Note: key file must be DER-encoded.||
 |tokenAuthClaim| Specify the token claim that will be used as the authentication "principal" or "role". The "subject" field will be used if this is left blank ||
 |tokenAudienceClaim| The token audience "claim" name, e.g. "aud". It is used to get the audience from token. If it is not set, the audience is not verified. ||
 | tokenAudience | The token audience stands for this broker. The field `tokenAudienceClaim` of a valid token need contains this parameter.| |

site2/docs/security-jwt.md

@@ -229,12 +229,12 @@ brokerClientTrustCertsFilePath=/path/my-ca/certs/ca.cert.pem
 # else it just accepts the originalPrincipal and authorizes it (if required).
 authenticateOriginalAuthData=true
 
-# If using secret key
+# If using secret key (Note: key files must be DER-encoded)
 tokenSecretKey=file:///path/to/secret.key
 # The key can also be passed inline:
 # tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
 
-# If using public/private
+# If using public/private (Note: key files must be DER-encoded)
 # tokenPublicKey=file:///path/to/public.key
 ```
 

site2/docs/security-token-admin.md

@@ -127,12 +127,12 @@ authenticationEnabled=true
 authorizationEnabled=true
 authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
 
-# If using secret key
+# If using secret key (Note: key files must be DER-encoded)
 tokenSecretKey=file:///path/to/secret.key
 # The key can also be passed inline:
 # tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
 
-# If using public/private
+# If using public/private (Note: key files must be DER-encoded)
 # tokenPublicKey=file:///path/to/public.key
 ```