xref: /aosp_15_r20/external/tink/python/tink/jwt/_jwt_mac.py (revision e7b1675dde1b92d52ec075b0a92829627f2c52a5) 
1# Copyright 2021 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#      http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14"""Interface for JwtMac."""
15
16import abc
17
18from typing import Optional
19
20from tink.jwt import _jwt_validator
21from tink.jwt import _raw_jwt
22from tink.jwt import _verified_jwt
23
24
25class JwtMac(metaclass=abc.ABCMeta):
26  """Interface for authenticating and verifying JWT with JWS MAC.
27
28  Sees RFC 7519 and RFC 7515. Security guarantees: similar to MAC.
29  """
30
31  @abc.abstractmethod
32  def compute_mac_and_encode(self, token: _raw_jwt.RawJwt) -> str:
33    """Computes a MAC and encodes the token.
34
35    Args:
36      token: The RawJwt token to be MACed and encoded.
37
38    Returns:
39      The MACed token encoded in the JWS compact serialization format.
40    Raises:
41      tink.TinkError if the operation fails.
42    """
43    raise NotImplementedError()
44
45  @abc.abstractmethod
46  def verify_mac_and_decode(
47      self, compact: str,
48      validator: _jwt_validator.JwtValidator) -> _verified_jwt.VerifiedJwt:
49    """Verifies, validates and decodes a MACed compact JWT token.
50
51    The JWT is validated against the rules in validator. That is, every claim in
52    validator must also be present in the JWT. For example, if validator
53    contains an issuer (iss) claim, the JWT must contain an identical claim.
54    The JWT can contain claims that are NOT in the validator, which are then
55    ignored. However, if the JWT contains a list of audiences, the validator
56    must also contain an audience in the list.
57
58    If the JWT contains timestamp claims such as expiration (exp), issued_at
59    (iat) or not_before (nbf), they will also be validated. Validator allows to
60    set a clock skew, to deal with small clock differences among different
61    machines.
62
63    Args:
64      compact: A MACed token encoded in the JWS compact serialization format.
65      validator: A JwtValidator that validates the token.
66
67    Returns:
68      A VerifiedJwt.
69    Raises:
70      tink.TinkError if the operation fails.
71    """
72    raise NotImplementedError()
73
74
75class JwtMacInternal(metaclass=abc.ABCMeta):
76  """Internal interface for authenticating and verifying JWT with JWS MAC.
77
78  "kid" is an optional value that is set by the wrapper for keys with output
79  prefix TINK. It is set to None for output prefix RAW.
80  """
81
82  @abc.abstractmethod
83  def compute_mac_and_encode_with_kid(self, token: _raw_jwt.RawJwt,
84                                      kid: Optional[str]) -> str:
85    raise NotImplementedError()
86
87  @abc.abstractmethod
88  def verify_mac_and_decode_with_kid(
89      self, compact: str, validator: _jwt_validator.JwtValidator,
90      kid: Optional[str]) -> _verified_jwt.VerifiedJwt:
91    raise NotImplementedError()
92