Token Verification

Find the information about the various algorithms described below in RFC 7518.

Verification with Shared Secret

The shared secret methods are based on Hash-based Message Authentication Code (HMAC) algorithm, where the hash is being computed using SHA256, SHA384, and SHA512 hash functions.

The supported methods for the verification of token signatures are:

HS256
HS384
HS512

The following Caddyfile directives set the default token verification key to "shared" (symmetric) key with the value of 383aca9a-1c39-4d7a-b4d8-67ba4718dd3f. It also sets a custom token name. The plugin would search for tokens with the app_token name.

{
  security {
    authorization policy mypolicy {
      crypto key verify 383aca9a-1c39-4d7a-b4d8-67ba4718dd3f
      crypto key token name app_token
    }
  }
}

assetq.myfiosgateway.com {
  authorize with mypolicy
  root * {env.HOME}/www
  file_server
}

The syntax is:

crypto key verify <SHARED_SECRET>
crypto key token name <TOKEN_NAME>

Alternatively, the key could be set via environment variables. The from env APP_TOKEN instructs the plugin to load the key from APP_TOKEN environment variable.

{
  security {
    authorization policy mypolicy {
      crypto key verify from env APP_TOKEN
      crypto key token name app_token
    }
  }
}

assetq.myfiosgateway.com {
  authorize with mypolicy
  root * {env.HOME}/www
  file_server
}

The syntax is:

crypto key verify from env <NAME>
crypto key token name <TOKEN_NAME>

Additionally, the key may have a key ID. It is otherwise known as kid. It could be passed via right after the crypto key keywords.

{
  security {
    authorization policy mypolicy {
      crypto key e5ZaB46bF27d verify 383aca9a-1c39-4d7a-b4d8-67ba4718dd3f
      crypto key e5ZaB46bF27d token name app_token
      crypto key 3bc4be49abf6 verify from env SECRET_TOKEN
      crypto key 3bc4be49abf6 token name secret_token
    }
  }
}

assetq.myfiosgateway.com {
  authorize with mypolicy
  root * {env.HOME}/www
  file_server
}

The syntax is:

crypto key <ID> verify <SHARED_SECRET>
crypto key <ID> verify from env <NAME>
crypto key <ID> token name <TOKEN_NAME>

Verification with RSA and ECDSA Keys

The RSA and ECDSA methods are based on asymmetric signature algorithms defined in RFC7518.

The supported RSA methods are:

RS256: RSASSA-PKCS1-v1_5 using SHA-256
RS384
RS512

The DSA are based on the Elliptic Curve Digital Signature Algorithm (ECDSA). See RFC7518 Section 3.4 for details.

The supported DSA methods are:

ES256: ECDSA using P-256 and SHA-256 (SHA256withECDSA)
- The Elliptic Curve has 256-bit integer prime.
ES384: ECDSA using P-384 and SHA-384 (SHA384withECDSA)
- The Elliptic Curve has 384-bit integer prime.
ES512: ECDSA using P-521 and SHA-512 (SHA512withECDSA)
- The Elliptic Curve has 512-bit integer prime.

The P-256 curve (aka prime256v1) is being used in U2F and CBOR.

The verification of the tokens is being done by "public" RSA or ECDSA keys. If the plugin finds a "private" key, it would extract "public" key from it and that key would be used to verify tokens.

NOTE: The verify keyword is used when the keys provided are public keys. Otherwise, user sign-verify or auto.

The following Caddyfile directives configure multiple token verification keys.

The default key ID (aka kid 0) is defined when the key ID value is not provided. Loads the key from /etc/gatekeeper/auth/jwt/verify_key1.pem file.
The key ID e5ZaB46bF27d: loads from /etc/gatekeeper/auth/jwt/verify_key2.pem.
The key ID 3bc4be49abf6: loads the key from the file stored in the VERIFY_KEY_FILE environment variable.
The key ID pik3mfhsXR1B: loads the keys from the directory stored in the environment variable VERIFY_KEY_DIR.

{
  security {
    authorization policy mypolicy {
      crypto key verify from file /etc/gatekeeper/auth/jwt/verify_key1.pem
      crypto key e5ZaB46bF27d verify from file /etc/gatekeeper/auth/jwt/verify_key2.pem
      crypto key 3bc4be49abf6 verify from env VERIFY_KEY_FILE as file
      crypto key pik3mfhsXR1B verify from env VERIFY_KEY_DIR as directory
    }
  }
}

assetq.myfiosgateway.com {
  authorize with mypolicy
  root * {env.HOME}/www
  file_server
}

Additionally, there could be a directory with public PEM keys.

{
  security {
    authorization policy mypolicy {
      crypto key e5ZaB46bF27d verify from directory /etc/gatekeeper/auth/jwt
      crypto key 3bc4be49abf6 verify from env VERIFY_KEY_DIR as directory
    }
  }
}

assetq.myfiosgateway.com {
  authorize with mypolicy
  root * {env.HOME}/www
  file_server
}

The syntax is:

crypto key <ID> verify from <directory|file> <PATH>
crypto key <ID> verify from env <NAME> as <directory|file|value>

Generate RSA Public Key

Th verify_key1.pem is RSA public key. It is generated with the following commands:

openssl genrsa -out /etc/gatekeeper/auth/jwt/sign_key1.pem 2048
openssl rsa -in /etc/gatekeeper/auth/jwt/sign_key1.pem -pubout -out /etc/gatekeeper/auth/jwt/verify_key1.pem

The content of verify_key1.pem follows:

Generate ECDSA Public Key

The verify_key1.pem is generated with the following commands.

First, review the output of the following command to determine the available Elliptic Curves.

$ openssl ecparam -list_curves
  secp224r1 : NIST/SECG curve over a 224 bit prime field
  secp256k1 : SECG curve over a 256 bit prime field
  secp384r1 : NIST/SECG curve over a 384 bit prime field
  secp521r1 : NIST/SECG curve over a 521 bit prime field
  prime256v1: X9.62/SECG curve over a 256 bit prime field

Next, generate ES256 private and public key pair:

openssl ecparam -genkey -name prime256v1 -noout \
  -out /etc/gatekeeper/auth/jwt/sign_key2.pem
openssl ec -in /etc/gatekeeper/auth/jwt/sign_key2.pem -pubout \
  -out /etc/gatekeeper/auth/jwt/verify_key2.pem

The content of verify_key2 follows:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwlCJyaA2uhZ29yhDkmsSm6nEageO
e0rB8fQM/g4WpLtz1AbPVZq9mjFHz390r7b2Dz6P/fNYqk5joikWVXrJ9g==
-----END PUBLIC KEY-----

For ES384 use -name secp384r1 argument.

For ES512 use -name secp521r1 argument.

Token Verification

Verification with Shared Secret​

Verification with RSA and ECDSA Keys​

Generate RSA Public Key​

Generate ECDSA Public Key​

Verification with Shared Secret

Verification with RSA and ECDSA Keys

Generate RSA Public Key

Generate ECDSA Public Key