docs/JWT-HOWTO.md - platform/external/tink - Git at Google

 # Tink's JWT HOW-TO

 This is a short introduction on the JSON Web Token (JWT) library in
 [Tink](https://github.com/google/tink).

 The JWT standard is defined in
 [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519). The standard has many
 options, and many options are rarely used and some options are difficult to use
 correctly. The goal of Tink's JWT implementation is provide as subset of the JWT
 standard that we consider safe to use, and fit well into Tink.

 These are the limitations of Tink's JWT library:

 -   Tink only supports the
     [JWS Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.1)
     format.
     [JWS JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.2)
     and [JWE](https://datatracker.ietf.org/doc/html/rfc7516) is not supported.
 -   Tink does not support the `None` value in the `alg` header.
 -   Tink only supports the headers `typ`, `alg` and `kid`. All other headers are
     not supported.
 -   Tink does not allow tokens to be parsed before the signature/mac is
     verified.

 ## JWT Primitives and Key Types

 Tink's JWT library provides primitives for both MAC and signatures. The
 interfaces for these primitives are called `JwtMac`, `JwtPublicKeySign` and
 `JwtPublicKeyVerify`. As with normal MACs and signatures, symmetric and
 asymmetric primitives are kept separate.

 Note that even though the JWT library uses the same MAC and signature algorithms
 as the normal MAC and signature primitives, the JWT library
 uses *different* key types. This is needed because some metadata (such as `alg`
 and `kid`) needs to be stored with the key.

 If tokens are generated and verified by different entities, then you should use
 asymmetric keys with the primitives `JwtPublicKeySign` and `JwtPublicKeyVerify`.
 The private key is used to generate tokens, and the public key is used to
 verify tokens. The algorithms supported by these primitives are: `ES256`,
 `ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384` and `PS512`. Only
 use the `JwtMac` primitive if the tokens are generated and verified by the same
 entity. The algorithms supported by this primitive are `HS256`, `HS384` and
 `HS512`.

 In [Tinkey](TINKEY.md), all templates that can be used with the JWT primitives
 start with `JWT_`, followed by the algorithm and some additonal paramters. For
 example `JWT_HS256`, `JWT_ES256`, `JWT_RS256_3072_F4` or `JWT_PS256_3072_F4`.

 ## Public keyset distribution

 In most cases, JWTs are generated by one party using a private keyset and
 verified by another party using the public keyset. This requires that the public
 keyset can be exported and shared. Tink allows public keyset to be converted to
 and from the standard
 [JWK Set](https://datatracker.ietf.org/doc/html/rfc7517#section-5) format, which
 most JWT libraries will understand. (Note that while Tink's `JsonKeysetWriter`
 will also produce keysets in JSON format, the output is *not* a JWK Set and
 other libraries will not be able to read it.)

 Tink does not support exporting public JWT keysets in any other format. The
 reason for this is that other formats do not contain the `alg` and the `kid`
 metadata to be used in the verification, which makes using them more error-prone
 and may make it more difficult to rotate keys.

 It is preferable to not just share the public keyset once, but to provide a way
 to *automatically* update the public keyset. (If not, rotating to a new key will
 be very hard.) Often, this is done by publishing the public keyset on a trusted
 and secured URL. A server that verifies tokens then simply has to periodically
 re-fetch the public keyset from that URL, for example once per day. To rotate
 the key, the new public key needs to be added to the public keyset *at least one
 day before* it is used to sign tokens. Otherwise the new tokens signed with the
 new private key will be rejected by servers that still use the old public keyset.

 Some implementations re-fetch the public key as soon as a token with an unknown
 `kid` header is received. Implementing this logic is not possible in Tink, since
 we don't parse the token before they are verified. We also don't recommend doing
 this, as it may result in lots of extra requests to the keyset URL if malicious
 tokens with random `kid` headers are sent.

 ## Headers and Claims

 #### Algorithm Header `alg`

 The `alg` header is always set and verified automatically by the Tink primitives
 and cannot be accessed by the user. This makes it easier to rotate to a
 different key type, as the user code does not depend on the particular key type
 used.

 #### Key ID Header `kid`

 The `kid` header is set and verified automatically by the Tink primitives. Tink
 supports both tokens with and without a `kid` header. They can be used in
 exactly the same way, both support key rotation. Tokens without a `kid` header
 are a bit shorter, but the difference is small. It is usually safer to generate
 tokens with the `kid` header set, as other JWT libraries may require them to be
 set.

 Tinkey JWT key templates without a `_RAW` suffix (such as `JWT_ES256`) generate
 tokens with `kid` header. Templates with `_RAW` suffix (such as `JWT_ES256_RAW`)
 generate tokens without `kid` header.

 #### Type Header `typ`

 The goal of the `typ` header is to clearly separate different types of token
 from each other. Not doing this separation correctly may result in security
 issues.

 But there are other ways to do this separation, for example by distinguishing
 different tokens by the claim names they use, or simply by using different
 keyset for different tokens. We therefore don't enforce the usage of the `typ`
 header. But, when a token with a `typ` header is verified, we require that the
 verifier explicitly validates it, or explicitly ignores it. This makes sure that
 the validation of this header is not forgotten.

 Setting the `typ` header always to the constant value `JWT` is not needed.

 #### Issuer claim `iss`

 This claim identifies the party that signed the token. This claim is usually a
 constant value for a given keyset, and globally unique. Often a URI is used to
 make it unique. Often, identity of the issuer is already clear by the fact that
 only the owner of the private keyset (which is the issuer) can generate tokens.
 In these cases, it may not be necessary to set the issuer claim in the token.
 But if the issuer claim is set, then we require that the verifier explicitly
 checks it, or explicitly ignores it.

 Tink does not support to dynamically look-up a keyset based on the issuer claim,
 as this may lead to security problems if the lookup is done without proper
 validation. We require that the verifier know the issuer and the keyset used to
 verify the token before looking at the token.

 #### Audiences claim `aud`

 This claim identifies a list of verifier that may accept this token. If this
 claim is set the verifier is required to pass its identity as expected
 audience. We do allow to explicitly ignore this claim, as it may be needed in
 some cases, for example if verifier's identity changed, and both the old
 and the new identity need to be accepted.

 #### Expiration `exp`, not-before `nbf` and issued-at `iat` claims

 In most use cases, tokens should have an expiration date set. That's why Tink
 by default expects the user to set an expiration. There are some tokens that
 don't have expiration dates, see for example
 [RFC 8417](https://datatracker.ietf.org/doc/html/rfc8417). Tink allows this,
 but requires the user to explicitly pass a parameter without_expiration when
 creating a token, to make sure that this is on purpose.

 *   The expiration date claim `exp` is *always* validated. Tink does not allow
     to turn this off, because the content of an expired token could be outdated
     or invalid, and should not be used.

 *   The not-before claim `nbf` is rarly used, but it is supported and will
     always be validated.

 *   Tink optionally supports validating that the issued-at claim `iat` is not in
     the pass.

 #### Validating any other claim

 Your application may have other claims that need to be validated. For example,
 maybe the token has a `sub` claim that needs to be in a special format, or it
 requires an `email` claim to be present. Tink can't really help the verifier in
 validating these claims, as validating these is different for different types of
 tokens. We recommend validating these claims immediately after Tink has
 successfully verified the token.

 ## Code Examples

 Here are some small examples on how to use Tink's JWT library:

 * [examples/cc/jwt](https://github.com/google/tink/tree/master/cc/examples/jwt)
 * [examples/java_src/jwt](https://github.com/google/tink/tree/master/java_src/examples/jwt)
 * [examples/python/jwt](https://github.com/google/tink/tree/master/python/examples/jwt)
	# Tink's JWT HOW-TO

	This is a short introduction on the JSON Web Token (JWT) library in
	[Tink](https://github.com/google/tink).

	The JWT standard is defined in
	[RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519). The standard has many
	options, and many options are rarely used and some options are difficult to use
	correctly. The goal of Tink's JWT implementation is provide as subset of the JWT
	standard that we consider safe to use, and fit well into Tink.

	These are the limitations of Tink's JWT library:

	- Tink only supports the
	[JWS Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.1)
	format.
	[JWS JSON Serialization](https://datatracker.ietf.org/doc/html/rfc7515#section-3.2)
	and [JWE](https://datatracker.ietf.org/doc/html/rfc7516) is not supported.
	- Tink does not support the `None` value in the `alg` header.
	- Tink only supports the headers `typ`, `alg` and `kid`. All other headers are
	not supported.
	- Tink does not allow tokens to be parsed before the signature/mac is
	verified.

	## JWT Primitives and Key Types

	Tink's JWT library provides primitives for both MAC and signatures. The
	interfaces for these primitives are called `JwtMac`, `JwtPublicKeySign` and
	`JwtPublicKeyVerify`. As with normal MACs and signatures, symmetric and
	asymmetric primitives are kept separate.

	Note that even though the JWT library uses the same MAC and signature algorithms
	as the normal MAC and signature primitives, the JWT library
	uses different key types. This is needed because some metadata (such as `alg`
	and `kid`) needs to be stored with the key.

	If tokens are generated and verified by different entities, then you should use
	asymmetric keys with the primitives `JwtPublicKeySign` and `JwtPublicKeyVerify`.
	The private key is used to generate tokens, and the public key is used to
	verify tokens. The algorithms supported by these primitives are: `ES256`,
	`ES384`, `ES512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384` and `PS512`. Only
	use the `JwtMac` primitive if the tokens are generated and verified by the same
	entity. The algorithms supported by this primitive are `HS256`, `HS384` and
	`HS512`.

	In [Tinkey](TINKEY.md), all templates that can be used with the JWT primitives
	start with `JWT_`, followed by the algorithm and some additonal paramters. For
	example `JWT_HS256`, `JWT_ES256`, `JWT_RS256_3072_F4` or `JWT_PS256_3072_F4`.

	## Public keyset distribution

	In most cases, JWTs are generated by one party using a private keyset and
	verified by another party using the public keyset. This requires that the public
	keyset can be exported and shared. Tink allows public keyset to be converted to
	and from the standard
	[JWK Set](https://datatracker.ietf.org/doc/html/rfc7517#section-5) format, which
	most JWT libraries will understand. (Note that while Tink's `JsonKeysetWriter`
	will also produce keysets in JSON format, the output is not a JWK Set and
	other libraries will not be able to read it.)

	Tink does not support exporting public JWT keysets in any other format. The
	reason for this is that other formats do not contain the `alg` and the `kid`
	metadata to be used in the verification, which makes using them more error-prone
	and may make it more difficult to rotate keys.

	It is preferable to not just share the public keyset once, but to provide a way
	to automatically update the public keyset. (If not, rotating to a new key will
	be very hard.) Often, this is done by publishing the public keyset on a trusted
	and secured URL. A server that verifies tokens then simply has to periodically
	re-fetch the public keyset from that URL, for example once per day. To rotate
	the key, the new public key needs to be added to the public keyset *at least one
	day before* it is used to sign tokens. Otherwise the new tokens signed with the
	new private key will be rejected by servers that still use the old public keyset.

	Some implementations re-fetch the public key as soon as a token with an unknown
	`kid` header is received. Implementing this logic is not possible in Tink, since
	we don't parse the token before they are verified. We also don't recommend doing
	this, as it may result in lots of extra requests to the keyset URL if malicious
	tokens with random `kid` headers are sent.

	## Headers and Claims

	#### Algorithm Header `alg`

	The `alg` header is always set and verified automatically by the Tink primitives
	and cannot be accessed by the user. This makes it easier to rotate to a
	different key type, as the user code does not depend on the particular key type
	used.

	#### Key ID Header `kid`

	The `kid` header is set and verified automatically by the Tink primitives. Tink
	supports both tokens with and without a `kid` header. They can be used in
	exactly the same way, both support key rotation. Tokens without a `kid` header
	are a bit shorter, but the difference is small. It is usually safer to generate
	tokens with the `kid` header set, as other JWT libraries may require them to be
	set.

	Tinkey JWT key templates without a `_RAW` suffix (such as `JWT_ES256`) generate
	tokens with `kid` header. Templates with `_RAW` suffix (such as `JWT_ES256_RAW`)
	generate tokens without `kid` header.

	#### Type Header `typ`

	The goal of the `typ` header is to clearly separate different types of token
	from each other. Not doing this separation correctly may result in security
	issues.

	But there are other ways to do this separation, for example by distinguishing
	different tokens by the claim names they use, or simply by using different
	keyset for different tokens. We therefore don't enforce the usage of the `typ`
	header. But, when a token with a `typ` header is verified, we require that the
	verifier explicitly validates it, or explicitly ignores it. This makes sure that
	the validation of this header is not forgotten.

	Setting the `typ` header always to the constant value `JWT` is not needed.

	#### Issuer claim `iss`

	This claim identifies the party that signed the token. This claim is usually a
	constant value for a given keyset, and globally unique. Often a URI is used to
	make it unique. Often, identity of the issuer is already clear by the fact that
	only the owner of the private keyset (which is the issuer) can generate tokens.
	In these cases, it may not be necessary to set the issuer claim in the token.
	But if the issuer claim is set, then we require that the verifier explicitly
	checks it, or explicitly ignores it.

	Tink does not support to dynamically look-up a keyset based on the issuer claim,
	as this may lead to security problems if the lookup is done without proper
	validation. We require that the verifier know the issuer and the keyset used to
	verify the token before looking at the token.

	#### Audiences claim `aud`

	This claim identifies a list of verifier that may accept this token. If this
	claim is set the verifier is required to pass its identity as expected
	audience. We do allow to explicitly ignore this claim, as it may be needed in
	some cases, for example if verifier's identity changed, and both the old
	and the new identity need to be accepted.

	#### Expiration `exp`, not-before `nbf` and issued-at `iat` claims

	In most use cases, tokens should have an expiration date set. That's why Tink
	by default expects the user to set an expiration. There are some tokens that
	don't have expiration dates, see for example
	[RFC 8417](https://datatracker.ietf.org/doc/html/rfc8417). Tink allows this,
	but requires the user to explicitly pass a parameter without_expiration when
	creating a token, to make sure that this is on purpose.

	* The expiration date claim `exp` is always validated. Tink does not allow
	to turn this off, because the content of an expired token could be outdated
	or invalid, and should not be used.

	* The not-before claim `nbf` is rarly used, but it is supported and will
	always be validated.

	* Tink optionally supports validating that the issued-at claim `iat` is not in
	the pass.

	#### Validating any other claim

	Your application may have other claims that need to be validated. For example,
	maybe the token has a `sub` claim that needs to be in a special format, or it
	requires an `email` claim to be present. Tink can't really help the verifier in
	validating these claims, as validating these is different for different types of
	tokens. We recommend validating these claims immediately after Tink has
	successfully verified the token.

	## Code Examples

	Here are some small examples on how to use Tink's JWT library:

	* [examples/cc/jwt](https://github.com/google/tink/tree/master/cc/examples/jwt)
	* [examples/java_src/jwt](https://github.com/google/tink/tree/master/java_src/examples/jwt)
	* [examples/python/jwt](https://github.com/google/tink/tree/master/python/examples/jwt)