JWSKATE

https://guillp.github.io/jwskate/
Admin
A Pythonic implementation of JOSE specifications (JSON Web Signature, Keys, Algorithms, Tokens, and...
Tokens:205,401
Snippets:1,452
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install jwskate from Source

Source: https://guillp.github.io/jwskate/installation

Install jwskate after downloading the source code. This command should be run from the root directory of the source code.

```bash
pip install .
```

--------------------------------

### Install jwskate Stable Release

Source: https://guillp.github.io/jwskate/installation

Use this command to install the most recent stable release of jwskate. Ensure pip is installed; refer to the Python installation guide if needed.

```bash
pip install jwskate
```

--------------------------------

### Get Supported Signing Algorithms

Source: https://guillp.github.io/jwskate/api

Retrieves a list of all signature algorithms that are compatible with the current key.

```python
def supported_signing_algorithms(self) -> list[str]:
    """Return the list of Signature algorithms that can be used with this key.

    Returns:
      a list of supported algs

    """
    return list(self.SIGNATURE_ALGORITHMS)
```

--------------------------------

### Create and activate virtual environment

Source: https://guillp.github.io/jwskate/contributing

After installing hatch, create and activate your virtual environment to manage project dependencies.

```bash
hatch env create
```

--------------------------------

### Get Supported Key Management Algorithms

Source: https://guillp.github.io/jwskate/api

Retrieves a list of all key management algorithms that are compatible with the current key.

```python
def supported_key_management_algorithms(self) -> list[str]:
    """Return the list of Key Management algorithms that can be used with this key.

    Returns:
        a list of supported algs

    """
    return list(self.KEY_MANAGEMENT_ALGORITHMS)
```

--------------------------------

### Get supported signing algorithms

Source: https://guillp.github.io/jwskate/usage

Retrieve a list of algorithms supported by the JWK for signing operations.

```python
jwk.supported_signing_algorithms()
```

--------------------------------

### Get supported key management algorithms

Source: https://guillp.github.io/jwskate/usage

Retrieve a list of algorithms supported by the JWK for key management operations.

```python
jwk.supported_key_management_algorithms()
```

--------------------------------

### Get Supported Key Management Algorithms for ECJwk

Source: https://guillp.github.io/jwskate/api

Returns a list of all supported key management algorithms for the ECJwk.

```python
@override
    def supported_key_management_algorithms(self) -> list[str]:
        return list(self.KEY_MANAGEMENT_ALGORITHMS)
```

--------------------------------

### Get OKPCurve Instance from Identifier

Source: https://guillp.github.io/jwskate/api

Gets an OKPCurve instance from a given curve identifier string. Raises UnsupportedOKPCurve if the curve is not supported.

```python
@classmethod
def get_curve(cls, crv: str) -> OKPCurve:
    """Get the `OKPCurve` instance from a curve identifier.

    Args:
      crv: a curve identifier

    Returns:
        the matching `OKPCurve` instance

    Raises:
        UnsupportedOKPCurve: if the curve is not supported

    """
    curve = cls.CURVES.get(crv)
    if curve is None:
        raise UnsupportedOKPCurve(crv)
    return curve
```

--------------------------------

### Instantiate Algorithm with Public Key

Source: https://guillp.github.io/jwskate/api

Returns a new algorithm instance initialized with the public key derived from the current instance. Requires the current instance to have a private key.

```python
from typing import Self

def public_alg(self) -> Self:
    """Return an alg instance initialised with the public key."""
    with self.private_key_required():
        return self.__class__(self.public_key())
```

--------------------------------

### Initialize SymmetricJwk from Bytes

Source: https://guillp.github.io/jwskate/api

Create a SymmetricJwk instance from raw key bytes. The key is base64url encoded and stored as the 'k' parameter.

```python
cls.from_bytes(dict(kty=cls.KTY, k=BinaPy(k).to("b64u").ascii(), **params))
```

--------------------------------

### get_claim

Source: https://guillp.github.io/jwskate/api

Get a claim by name from this Jwt.

```APIDOC
## get_claim

### Description
Get a claim by name from this Jwt.

### Method Signature
```python
get_claim(key: str, default: Any = None) -> Any
```

### Parameters
- `key` (str): the claim name.
- `default` (Any): a default value if the claim is not found. Default: `None`.

### Returns
- `Any`: the claim value if found, or `default` if not found.
```

--------------------------------

### Initialize Public OKPJwk

Source: https://guillp.github.io/jwskate/api

Use this class method to create a public OKPJwk instance. It requires the key curve and the public key bytes as input, along with any additional JWK parameters.

```python
@classmethod
def public(cls, *, crv: str, x: bytes, **params: Any) -> OKPJwk:
    """Initialize a public `OKPJwk` based on the provided parameters.

    Args:
      crv: the key curve
      x: the public key
      **params: additional members to include in the `Jwk`

    Returns:
        the resulting `OKPJwk`

    """
    return cls(dict(kty=cls.KTY, crv=crv, x=BinaPy(x).to("b64u").ascii(), **params))
```

--------------------------------

### Jwk.curve

Source: https://guillp.github.io/jwskate/api

Get the OKPCurve instance for this key.

```APIDOC
## Jwk.curve

### Description
Get the `OKPCurve` instance for this key.

### Property
`curve`: OKPCurve
```

--------------------------------

### Initialize Key Management Wrapper

Source: https://guillp.github.io/jwskate/api

Initializes a key management wrapper with the current key. If the key lacks an algorithm identifier, one must be provided. Returns a BaseKeyManagementAlg subclass instance.

```python
def key_management_wrapper(self, alg: str | None = None) -> BaseKeyManagementAlg:
    """Initialize a key management wrapper with this key.

    This returns an instance of a `BaseKeyManagementAlg` subclass.

    If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

    Args:
        alg: the algorithm identifier, if not already present in this Jwk

    Returns:
        a `BaseKeyManagementAlg` instance initialized with the current key

    """
    alg_class = self.key_management_class(alg)
    if issubclass(alg_class, BaseSymmetricAlg):
        return alg_class(self.key)
    elif issubclass(alg_class, BaseAsymmetricAlg):
        return alg_class(self.cryptography_key)
    raise UnsupportedAlg(alg)  # pragma: no cover
```

--------------------------------

### Jwk.get_curve

Source: https://guillp.github.io/jwskate/api

Get the OKPCurve instance from a curve identifier.

```APIDOC
## Jwk.get_curve

### Description
Get the `OKPCurve` instance from a curve identifier.

### Method
`get_curve(crv: str) -> OKPCurve`

### Parameters
#### Path Parameters
- **crv** (str) - Required - a curve identifier

### Returns
- **OKPCurve** - the matching `OKPCurve` instance

### Raises
- **UnsupportedOKPCurve** - if the curve is not supported
```

--------------------------------

### key_management_wrapper

Source: https://guillp.github.io/jwskate/api

Initializes a key management wrapper with this key. Returns an instance of a `BaseKeyManagementAlg` subclass. If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

```APIDOC
## key_management_wrapper

### Description
Initializes a key management wrapper with this key. Returns an instance of a `BaseKeyManagementAlg` subclass.
If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (This is a method within a class)

### Endpoint
None (This is a method within a class)

### Request Example
None

### Response
#### Success Response
- **alg_class** (`BaseKeyManagementAlg` subclass) - The initialized key management algorithm class.

#### Response Example
None
```

--------------------------------

### Jwk.private_key

Source: https://guillp.github.io/jwskate/api

Get the private key from this Jwk, base64url-decoded.

```APIDOC
## Jwk.private_key

### Description
Get the private key from this `Jwk`, from param `d`, base64url-decoded.

### Property
`private_key`: bytes
```

--------------------------------

### Jwk.public_key

Source: https://guillp.github.io/jwskate/api

Get the public key from this Jwk, base64url-decoded.

```APIDOC
## Jwk.public_key

### Description
Get the public key from this `Jwk`, from param `x`, base64url-decoded.

### Property
`public_key`: bytes
```

--------------------------------

### SymmetricJwk.key_size

Source: https://guillp.github.io/jwskate/api

Gets the size of the symmetric key in bits.

```APIDOC
## SymmetricJwk.key_size

### Description
Returns the size of the symmetric key in bits.

### Property
`key_size` (int)
```

--------------------------------

### Get Subject

Source: https://guillp.github.io/jwskate/api

Retrieves the subject ('sub' claim) from the JWT.

```APIDOC
## subject

### Description
Gets the *Subject* (`sub`) claim from this token. Returns `None` if the `sub` claim is not present.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
subject = jwt.subject
if subject:
    print(f"Token subject is: {subject}")
else:
    print("Token does not have a subject claim.")
```

### Response
#### Success Response (200)
- **Returns** (`str` | `None`): The subject as a string, or `None` if there is no `sub` claim.

#### Response Example
```python
# Example return value:
# "user123"
# None
```

### Errors
- `AttributeError`: Raised if the `sub` value is not a string.
```

--------------------------------

### Sign and Encrypt a JWT to create a JWE

Source: https://guillp.github.io/jwskate/recipes

This example demonstrates signing a JWT and then encrypting it to form a JWE. It requires both a signing key and an encryption key. The decryption and verification process for the inner signed JWT is also shown.

```python
from jwskate import Jwk, Jwt

enc_key = Jwk.generate(alg="ECDH-ES+A128KW")  # choose your own key management alg!
sig_key = Jwk.generate(alg="ES256")  # choose your own signature alg!

claims = {"iss": "my_issuer", "iat": 1695715510, "sub": "my_sub"}

signed_and_encryted_jwt = Jwt.sign(claims, key=sig_key).encrypt(  # this signs a JWT
    key=enc_key.public_jwk(), enc="A256GCM"
)  # this encrypts the signed JWT into a JWE. Choose your own encryption alg!

print(signed_and_encryted_jwt)
# eyJjdHkiOiJKV1QiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJSOS05eExHb052M3JhVGp6bUJndXFoZUU0NlBCbVB3VnVSc2lGVkllQnVZIiwieSI6Il8tS2txYXNtR0E1M2g5RTB4MTF2QmlEQ1g1M3M4Qi1TZTdvR0M4OW5yR0EifSwiYWxnIjoiRUNESC1FUytBMTI4S1ciLCJlbmMiOiJBMjU2R0NNIn0.KJSBiz5MkCy-YojozYgs5wn14T4llyI-MQBtkkzQpeHx7NPEhxUieA.x-flJmO6j5fX1ayE.LgpTlnZ6t01rO_ojhpep8RVxvI0ijdV_PbR6JcolTp7e327QpSsLgEA6_gllMO6_oxSPiqFwNgU-FkQhInT1FGZWKc04EA1coAsvmkDykshKWxiSC4LimYkqi-YOSQW7K9IBuMdMyEY6gYEj-znsY1HbYrh3nhS8_03QRbK56fJYIYcLUhkbcZBe3nHdD5kqNNigCuMW8ENo7M6jT53ZC__lYUyVIc-_JLZGUCGCEbJB--1ctFYDA4Iwyvxhk-wi.esupByQ5sWTq2lvzyNLi4w

print(
    signed_and_encryted_jwt.headers
)  # note that this header is generated automatically, including the ephemeral public key (epk)
# {'cty': 'JWT', # the inner content-type is JWT
# 'epk': {'kty': 'EC', 'crv': 'P-256', 'x': 'R9-9xLGoNv3raTjzmBguqheE46PBmPwVuRsiFVIeBuY', 'y': '_-KkqasmGA53h9E0x11vBiDCX53s8B-Se7oGC89nrGA'},
# 'alg': 'ECDH-ES+A128KW',
# 'enc': 'A256GCM'}

# to decode and verify the inner signed JWT:
inner_signed_jwt = signed_and_encryted_jwt.decrypt_jwt(enc_key).verify(
    sig_key.public_jwk()
)

print(inner_signed_jwt)
# eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteV9pc3N1ZXIiLCJpYXQiOjE2OTU3MTU1MTAsInN1YiI6Im15X3N1YiJ9.smfmqDYveE4TQboXhzxb7qddrITvU7JpWNwSfLj4XDOt8-tHe-pAuZ5EYJD0p4cynS1OwhT8LGSWnVpi7bPBCw
```

--------------------------------

### Get Issuer

Source: https://guillp.github.io/jwskate/api

Retrieves the issuer ('iss' claim) from the JWT.

```APIDOC
## issuer

### Description
Gets the *Issuer* (`iss`) claim from this token. Returns `None` if the `iss` claim is not present.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
issuer = jwt.issuer
if issuer:
    print(f"Token issued by: {issuer}")
else:
    print("Token does not have an issuer claim.")
```

### Response
#### Success Response (200)
- **Returns** (`str` | `None`): The issuer as a string, or `None` if there is no `iss` claim.

#### Response Example
```python
# Example return value:
# "https://example.com/auth"
# None
```

### Errors
- `AttributeError`: Raised if the `iss` claim value is not a string.
```

--------------------------------

### Initialize and Use JwtVerifier

Source: https://guillp.github.io/jwskate/api

Initialize a JwtVerifier with expected issuer, JWKS, audience, and allowed signature algorithms. Then, use the verifier to validate JWT tokens, checking signatures, claims, and expiration.

```python
from jwskate import JwtVerifier

# initialize a JwtVerifier based on its expected issuer, audience, JwkSet and allowed signature algs
jwks = requests.get("https://myissuer.local/jwks").json()
verifier = JwtVerifier(
    issuer="https://myissuer.local", jwkset=jwks, audience="myapp", alg="ES256"
)

# then verify tokens
try:
    verifier.verify(
        "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL215aXNzdWVyLmxvY2FsIiwiYXVkIjoibXlhcHAiLCJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNjcyNzU5NjM0LCJleHAiOjE2NzI3NTk2OTR9.Uu5DtCnf9cwYtem8tQ4trHVgXyZBoa8fhFcGL87O2D4"
    )
    print("token is verified!")
except ValueError:
    print("token failed verification :(")
```

--------------------------------

### with_usage_parameters

Source: https://guillp.github.io/jwskate/api

Copies the Jwk and adds `alg`, `use`, and `key_ops` parameters based on the provided or existing algorithm. Deduces `use` and `key_ops` based on the algorithm and key type.

```APIDOC
## with_usage_parameters

### Description
Copy this Jwk and add the `use` and `key_ops` parameters. The `alg` parameter will be the one passed or the one declared in the Jwk. The `use` and `key_ops` are deduced based on the `alg` and key properties.

### Arguments
- `alg` (str | None, optional): the alg to use, if not present in this Jwk.
- `with_alg` (bool, optional): whether to include an `alg` parameter. Defaults to `True`.
- `with_use` (bool, optional): whether to include a `use` parameter. Defaults to `True`.
- `with_key_ops` (bool, optional): whether to include a `key_ops` parameter. Defaults to `True`.

### Returns
a Jwk with the same key, with `alg`, `use` and `key_ops` parameters.

### Raises
- `ExpectedAlgRequired`: if an algorithm is not provided and not present in the Jwk.

### Method Signature
`with_usage_parameters(alg: str | None = None, *, with_alg: bool = True, with_use: bool = True, with_key_ops: bool = True) -> Jwk`
```

--------------------------------

### Get OKPCurve Instance

Source: https://guillp.github.io/jwskate/api

Retrieves the OKPCurve instance associated with this Jwk.

```python
curve: OKPCurve
```

--------------------------------

### Get Audiences

Source: https://guillp.github.io/jwskate/api

Retrieves the audience(s) ('aud' claim) from the JWT as a list of strings.

```APIDOC
## audiences

### Description
Gets the *Audience(s)* (`aud`) claim from this token. Returns an empty list if the `aud` claim is not present. If there is a single audience, it will be returned in a list.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
audiences = jwt.audiences
if audiences:
    print(f"Token is intended for audiences: {', '.join(audiences)}")
else:
    print("Token does not specify any audiences.")
```

### Response
#### Success Response (200)
- **Returns** (`list[str]`): A list of strings representing the audiences.

#### Response Example
```python
# Example return value:
# ["https://api.example.com", "https://another.example.com"]
# []
```

### Errors
- `AttributeError`: Raised if the audience is an unexpected type.
```

--------------------------------

### Initialize JweCompact from parts

Source: https://guillp.github.io/jwskate/api

Use this class method to initialize a JweCompact instance from its constituent parts: headers, CEK, IV, ciphertext, and authentication tag. The parts are serialized and Base64URL-encoded to form the compact representation.

```python
cls(
            b".".join(
                (
                    BinaPy.serialize_to("json", headers).to("b64u"),
                    BinaPy(cek).to("b64u"),
                    BinaPy(iv).to("b64u"),
                    BinaPy(ciphertext).to("b64u"),
                    BinaPy(tag).to("b64u"),
                )
            )
        )
```

--------------------------------

### Initialize OKPJwk from Bytes

Source: https://guillp.github.io/jwskate/api

Initializes an OKPJwk from its private key as bytes. The public key is derived automatically. The curve is guessed based on key length or `crv`/`use` hints. For 32-byte keys, `crv` or `use` must be specified to distinguish between Ed25519 and X25519.

```python
from jwskate import OKPJwk

# Example usage:
# Assuming you have a private key as bytes, e.g., 32 bytes for Ed25519
# private_key_bytes = b'...' 
# jwk = OKPJwk.from_bytes(private_key_bytes, crv='Ed25519')

@classmethod
def from_bytes(  # noqa: C901
    cls,
    private_key: bytes,
    crv: str | None = None,
    use: str | None = None,
    **kwargs: Any,
) -> OKPJwk:
    """Initialize an `OKPJwk` from its private key, as `bytes`.

    The public key will be automatically derived from the supplied private key, according to the OKP curve.

    The appropriate curve will be guessed based on the key length or supplied `crv`/`use` hints:

    - 56 bytes will use `X448`
    - 57 bytes will use `Ed448`
    - 32 bytes will use `Ed25519` or `X25519`. Since there is no way to guess which one you want,
      it needs a hint with either a `crv` or `use` parameter.

    Args:
        private_key: the 32, 56 or 57 bytes private key, as raw `bytes`
        crv: the curve identifier to use
        use: the key usage
        **kwargs: additional members to include in the `Jwk`

    Returns:
        the matching `OKPJwk`

    """
    if crv and use:
        if (crv in ("Ed25519", "Ed448") and use != "sig") or (crv in ("X25519", "X448") and use != "enc"):
            msg = (
                f"Inconsistent `crv={crv}` and `use={use}` parameters. "
                "Ed25519 and Ed448 are used for signing (use='sig'). "
                "X25519 and X448 are used for encryption (use='enc')."
            )
            raise ValueError(msg)
    elif crv:
        if crv in ("Ed25519", "Ed448"):
            use = "sig"
        elif crv in ("X25519", "X448"):
            use = "enc"
        else:
            raise UnsupportedOKPCurve(crv)
    elif use and use not in ("sig", "enc"):
        msg = f"Invalid `use={use}` parameter, it must be either 'sig' or 'enc'."
        raise ValueError(msg)

    cryptography_key: Any
    if len(private_key) == Ed25519.key_size:
        if use == "sig":
            cryptography_key = ed25519.Ed25519PrivateKey.from_private_bytes(private_key)
        elif use == "enc":
            cryptography_key = x25519.X25519PrivateKey.from_private_bytes(private_key)
        else:
            msg = (
                "You provided a 32 bytes private key, which is appropriate for both Ed25519 and X25519 curves. "
                "There is no way to guess which curve you need, so please specify either `crv='Ed25519'` "
                "or `use='sig'` for an `Ed25519` key, or either `crv='X25519'` or `use='enc'` for a `X25519` key."
            )
            raise ValueError(msg)
    elif len(private_key) == X448.key_size:
        cryptography_key = x448.X448PrivateKey.from_private_bytes(private_key)
        if use and use != "enc":
            msg = f"Invalid `use='{use}'` parameter. Keys of length 56 bytes are only suitable for curve 'X448'."
            raise ValueError(msg)
        use = "enc"
    elif len(private_key) == Ed448.key_size:
        cryptography_key = ed448.Ed448PrivateKey.from_private_bytes(private_key)
        if use and use != "sig":
            msg = f"Invalid `use='{use}'` parameter. Keys of length 57 bytes are only suitable for curve 'Ed448'."
            raise ValueError(msg)
        use = "sig"
    else:
        msg = "Invalid private key. It must be `bytes`, of length 32, 56 or 57 bytes."
        raise ValueError(msg)

    return OKPJwk.from_cryptography_key(cryptography_key, use=use, **kwargs)
```

--------------------------------

### Get Not Before Time

Source: https://guillp.github.io/jwskate/api

Retrieves the not before time ('nbf' claim) from the JWT as a datetime object.

```APIDOC
## not_before

### Description
Gets the *Not Before* (`nbf`) date from this token as a `datetime` object. Returns `None` if the `nbf` claim is not present.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
not_before_date = jwt.not_before
if not_before_date:
    print(f"Token is valid starting from: {not_before_date}")
else:
    print("Token does not have a not before date.")
```

### Response
#### Success Response (200)
- **Returns** (`datetime` | `None`): A `datetime` object initialized from the `nbf` claim, or `None` if there is no `nbf` claim.

#### Response Example
```python
# Example return value:
# datetime.datetime(2023, 10, 27, 9, 30, 0, tzinfo=datetime.timezone.utc)
# None
```

### Errors
- `AttributeError`: Raised if the `nbf` claim cannot be parsed to a date.
```

--------------------------------

### Get Symmetric Key Size

Source: https://guillp.github.io/jwskate/api

Returns the size of the symmetric key in bits.

```python
key_size: int
```

--------------------------------

### Verify JWT Token with Custom Verifier

Source: https://guillp.github.io/jwskate/api

Demonstrates how to set up a JwtVerifier with a specific JWK and issuer, and then apply a custom verifier to check for a specific claim before verifying the token.

```APIDOC
## Verify JWT Token with Custom Verifier

### Description
This example shows how to initialize a `JwtVerifier` with a public key and issuer, and then define and use a custom verification function to ensure a specific claim exists in the token.

### Method
`JwtVerifier.verify()`

### Endpoint
N/A (This is an SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (The token is passed as an argument to the `verify` method)

### Request Example
```python
from jwskate import Jwk, JwtVerifier

verification_key = Jwk({"kty": "oct", "k": "eW91ci0yNTYtYml0LXNlY3JldA", "alg": "HS256"})
verifier = JwtVerifier(verification_key.as_jwks(), issuer="https://foo.bar")


@verifier.custom_verifier
def must_contain_claim_foo(jwt):
    if "foo" not in jwt:
        raise ValueError("No foo!")


verifier.verify(
    "eyJhbGciOiJIUzI1NiIsImtpZCI6ImlfdXRLRXhBS05jXy1hd3FEUkFVYmFoTWd5RGFLREdfTTc1S01Cd2xBdkEifQ.eyJpc3MiOiJodHRwczovL2Zvby5iYXIiLCJmb28iOiJZRVMiLCJpYXQiOjE1MTYyMzkwMjJ9.hk2vnymjcww8K-OcOkNCPUiJK-8Rj--RKJqsHSKe4jM"
)
```

### Response
#### Success Response (200)
Returns the decoded JWT payload if verification is successful.

#### Response Example
```json
{
  "iss": "https://foo.bar",
  "foo": "YES",
  "iat": 1516239022
}
```
```

--------------------------------

### OKPJwk.public

Source: https://guillp.github.io/jwskate/api

Initializes a public OKPJwk based on the provided parameters. Requires the key curve and public key bytes.

```APIDOC
## OKPJwk.public

### Description
Initialize a public `OKPJwk` based on the provided parameters.

### Method Signature
`public(*, crv: str, x: bytes, **params: Any) -> OKPJwk`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **crv** (str) - Required - the key curve
- **x** (bytes) - Required - the public key
- **params** (Any) - Optional - additional members to include in the `Jwk`

### Request Example
```python
OKPJwk.public(crv='P-256', x=b'public_key_bytes')
```

### Response
#### Success Response
- **OKPJwk** - the resulting `OKPJwk`

### Response Example
```json
{
  "kty": "OKP",
  "crv": "P-256",
  "x": "base64url_encoded_public_key"
}
```
```

--------------------------------

### Get ECJwk Y Coordinate

Source: https://guillp.github.io/jwskate/api

Returns the y-coordinate of the ECJwk, decoded from its base64url representation.

```python
@cached_property
    def y_coordinate(self) -> int:
        """Return the *y coordinate*, parameter `y` from this `ECJwk`."""
        return BinaPy(self.y).decode_from("b64u").to_int()
```

--------------------------------

### Get JWK thumbprint

Source: https://guillp.github.io/jwskate/usage

Compute the JWK thumbprint according to RFC 7638.

```python
jwk.thumbprint()
```

--------------------------------

### signature_wrapper

Source: https://guillp.github.io/jwskate/api

Initializes a key management wrapper with this key. Returns an instance of a `BaseSignatureAlg` subclass. If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

```APIDOC
## signature_wrapper

### Description
Initializes a key management wrapper with this key. Returns an instance of a `BaseSignatureAlg` subclass.
If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None (This is a method within a class)

### Endpoint
None (This is a method within a class)

### Request Example
None

### Response
#### Success Response
- **alg_class** (`BaseSignatureAlg` subclass) - The initialized signature algorithm class.

#### Response Example
None
```

--------------------------------

### Get RSAJwk Modulus

Source: https://guillp.github.io/jwskate/api

Retrieves and returns the modulus (n) of the RSAJwk, decoded from base64url.

```python
return BinaPy(self.n).decode_from("b64u").to_int()
```

--------------------------------

### Initialize Private OKPJwk

Source: https://guillp.github.io/jwskate/api

Initializes a private OKPJwk instance using curve, public key (x), and private key (d). Additional parameters can be included.

```python
return cls(
            dict(
                kty=cls.KTY,
                crv=crv,
                x=BinaPy(x).to("b64u").ascii(),
                d=BinaPy(d).to("b64u").ascii(),
                **params,
            )
        )
```

--------------------------------

### Get RSAJwk Key Size

Source: https://guillp.github.io/jwskate/api

Calculates and returns the key size in bits for an RSAJwk.

```python
return len(BinaPy(self.n).decode_from("b64u")) * 8
```

--------------------------------

### Get Private Key

Source: https://guillp.github.io/jwskate/api

Retrieves the private key from this Jwk, base64url-decoded from the 'd' parameter.

```python
private_key: bytes
```

--------------------------------

### JWT Claims Output Example

Source: https://guillp.github.io/jwskate

This output demonstrates the structure of claims within a generated JWT, including standard fields and any custom claims provided during the signing process.

```python
{'custom_claim1': 'value1',
 'custom_claim2': 'value2',
 'iss': 'https://myissuer.com',
 'aud': 'some_aud',
 'sub': 'some_sub',
 'iat': 1648823184,
 'exp': 1648823244,
 'jti': '3b400e27-c111-4013-84e0-714acd76bf3a'
}
```

--------------------------------

### Initialize SymmetricJwk from Bytes

Source: https://guillp.github.io/jwskate/api

Initializes a SymmetricJwk from raw secret key material. The key is encoded and used as the 'k' parameter.

```python
@classmethod
def from_bytes(cls, k: bytes | str, **params: Any) -> SymmetricJwk:
    """Initialize a `SymmetricJwk` from a raw secret key.

    The provided secret key is encoded and used as the `k` parameter for the returned `SymmetricKey`.

    Args:
      k: the key to use
      **params: additional members to include in the `Jwk`

    Returns:
      the resulting `SymmetricJwk`

    """
    return cls(dict(kty=cls.KTY, k=BinaPy(k).to("b64u").ascii(), **params))

```

--------------------------------

### Get Public Key

Source: https://guillp.github.io/jwskate/api

Retrieves the public key from this Jwk, base64url-decoded from the 'x' parameter.

```python
public_key: bytes
```

--------------------------------

### Get ECJwk X Coordinate

Source: https://guillp.github.io/jwskate/api

Returns the x-coordinate of the ECJwk, decoded from its base64url representation.

```python
@cached_property
    def x_coordinate(self) -> int:
        """Return the *x coordinate*, parameter `x` from this `ECJwk`."""
        return BinaPy(self.x).decode_from("b64u").to_int()
```

--------------------------------

### Initialize Encryption Wrapper

Source: https://guillp.github.io/jwskate/api

Initializes an encryption wrapper with the current key. If the key lacks an algorithm identifier, one must be provided. Returns a BaseAESEncryptionAlg subclass instance.

```python
def encryption_wrapper(self, alg: str | None = None) -> BaseAESEncryptionAlg:
    """Initialize an encryption wrapper with this key.

    This returns an instance of a `BaseAESEncryptionAlg` subclass.

    If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

    Args:
        alg: the algorithm identifier, if not already present in this Jwk

    Returns:
        a `BaseAESEncryptionAlg` instance initialized with the current key

    """
    alg_class = self.encryption_class(alg)
    if issubclass(alg_class, BaseSymmetricAlg):
        return alg_class(self.key)
    elif issubclass(alg_class, BaseAsymmetricAlg):  # pragma: no cover
        return alg_class(self.cryptography_key)  # pragma: no cover
    raise UnsupportedAlg(alg)  # pragma: no cover
```

--------------------------------

### Load Public Key from PEM and DER

Source: https://guillp.github.io/jwskate/recipes

Demonstrates loading public keys from PEM and DER encoded files into Jwk objects. It also shows how to add back parameters like 'alg' and 'kid' which are not present in the PEM/DER format.

```python
from jwskate import Jwk

# get the cryptography public key
cryptography_public_key = public_jwk.cryptography_key
print(type(cryptography_public_key))
# <class 'cryptography.hazmat.backends.openssl.ec._EllipticCurvePublicKey'>

# get the public PEM
public_pem = public_jwk.to_pem()
print(public_pem.decode())
# -----BEGIN PUBLIC KEY-----
# MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8xX1CEhDNNjEySUKLw88YeiVwEOW
# 34BWm0hBkAxqlVVR9nQkpPszF00zKowrMpwBxhNy6qhd6mVwneM1+ePe0w==
# -----END PUBLIC KEY-----

# write this public PEM to a file:
with open("my_public_key.pem", "wb") as foutput:
    foutput.write(public_pem)

# read the private PEM from file and load it as a Jwk:
with open("my_private_key.pem", "rb") as finput:
    private_pem_from_file = finput.read()
private_jwk_from_file = (
    Jwk.from_pem(private_pem_from_file, password="Th1s_P@ssW0rD_iS_5o_5tr0nG!")
    .with_usage_parameters(alg="ES256")  # adds back the alg, use and key_ops parameters
    .with_kid_thumbprint()  # adds back the thumbprint as kid
)
assert private_jwk_from_file == private_jwk

# read the public PEM from file and load it as a Jwk:
with open("my_public_key.pem", "rb") as finput:
    public_pem_from_file = finput.read()
public_jwk_from_pem_file = (
    Jwk.from_pem(public_pem_from_file)
    .with_usage_parameters(
        alg="ES256"
    )  # alg is not part of the PEM, so you can add it back
    .with_kid_thumbprint()  # adds back the thumbprint as kid
)
assert public_jwk_from_pem_file == public_jwk

# get the public DER
public_der = public_jwk.to_der()
print(public_der.hex())
# 3059301306072a8648ce3d020106082a8648ce3d03010703420004f315f508484334d8c4c9250a2f0f3c61e895c04396df80569b4841900c6a955551f67424a4fb33174d332a8c2b329c01c61372eaa85dea65709de335f9e3ded3
# write DER to a file
with open("my_public_key.der", "wb") as foutput:
    foutput.write(public_der)

# read a DER and load it as a Jwk:
with open("my_public_key.pem", "rb") as finput:
    public_pem_from_file = finput.read()
public_jwk_from_der_file = (
    Jwk.from_pem(public_pem_from_file)
    .with_usage_parameters(
        alg="ES256"
    )  # alg is not part of the DER, so you can add it back
    .with_kid_thumbprint()  # adds back the thumbprint as kid
)
assert public_jwk_from_der_file == public_jwk
```

--------------------------------

### Get JWK algorithm

Source: https://guillp.github.io/jwskate/usage

Retrieve the intended algorithm (alg) identifier for the JWK, if present.

```python
jwk.alg
```

--------------------------------

### Initialize Jwk with Parameters

Source: https://guillp.github.io/jwskate/api

Initializes a Jwk object with parameters and optionally includes the key ID thumbprint. It validates the key and attempts to convert it to a cryptography key object.

```python
def __init__(self, params: Mapping[str, Any] | Any, *, include_kid_thumbprint: bool = False):
        if isinstance(params, dict):  # this is to avoid double init due to the __new__ above
            super().__init__({key: val for key, val in params.items() if val is not None})
            self._validate()
            if self.get("kid") is None and include_kid_thumbprint:
                self["kid"] = self.thumbprint()

        try:
            self.cryptography_key = self._to_cryptography_key()
        except Exception as exc:
            raise InvalidJwk(params) from exc
```

--------------------------------

### Get JWK key type

Source: https://guillp.github.io/jwskate/usage

Retrieve the key type (kty) of the JWK as a string.

```python
jwk.kty
```

--------------------------------

### Initialize JwsSignature from Parts

Source: https://guillp.github.io/jwskate/api

Use `from_parts` to create a JwsSignature instance from its constituent components: protected headers, signature value, and unprotected header.

```python
class JwsSignature(BaseJsonDict):
    """Represent a JWS Signature.

    A JWS Signature has:

     - a protected header (as a JSON object)
     - a signature value (as raw data)
     - an unprotected header (as arbitrary JSON data)
     - optional extra JSON attributes

    """

    @classmethod
    def from_parts(
        cls: type[S],
        protected: Mapping[str, Any],
        signature: bytes,
        header: Any | None,
        **kwargs: Any,
    ) -> S:
        """Initialize a JwsSignature based on the provided parts.

        Args:
          protected: the protected headers, as a key: value mapping
          signature: the raw signature value
          header: the unprotected header, if any
          **kwargs: extra attributes, if any

        Returns:
            A `JwsSignature` based on the provided parts.

        """
        content = dict(
            kwargs,
            protected=BinaPy.serialize_to("json", protected).to("b64u").ascii(),
            signature=BinaPy(signature).to("b64u").ascii(),
        )
        if header is not None:
            content["header"] = header
        return cls(content)
```

--------------------------------

### Get Issued At Time

Source: https://guillp.github.io/jwskate/api

Retrieves the issued at time ('iat' claim) from the JWT as a datetime object.

```APIDOC
## issued_at

### Description
Gets the *Issued At* (`iat`) date from this token as a `datetime` object. Returns `None` if the `iat` claim is not present.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
issued_date = jwt.issued_at
if issued_date:
    print(f"Token issued at: {issued_date}")
else:
    print("Token does not have an issued at date.")
```

### Response
#### Success Response (200)
- **Returns** (`datetime` | `None`): A `datetime` object initialized from the `iat` claim, or `None` if there is no `iat` claim.

#### Response Example
```python
# Example return value:
# datetime.datetime(2023, 10, 27, 9, 0, 0, tzinfo=datetime.timezone.utc)
# None
```

### Errors
- `AttributeError`: Raised if the `iat` claim cannot be parsed to a date.
```

--------------------------------

### Get Expiration Time

Source: https://guillp.github.io/jwskate/api

Retrieves the expiration time ('exp' claim) from the JWT as a datetime object.

```APIDOC
## expires_at

### Description
Gets the *Expires At* (`exp`) date from this token as a `datetime` object. Returns `None` if the `exp` claim is not present.

### Parameters
None

### Method
Accessed as a property on a Jwt object.

### Endpoint
N/A (Property on an object)

### Request Example
```python
# Assuming 'jwt' is a Jwt object
expiration_date = jwt.expires_at
if expiration_date:
    print(f"Token expires at: {expiration_date}")
else:
    print("Token does not have an expiration date.")
```

### Response
#### Success Response (200)
- **Returns** (`datetime` | `None`): A `datetime` object initialized from the `exp` claim, or `None` if there is no `exp` claim.

#### Response Example
```python
# Example return value:
# datetime.datetime(2023, 10, 27, 10, 30, 0, tzinfo=datetime.timezone.utc)
# None
```

### Errors
- `AttributeError`: Raised if the `exp` claim cannot be parsed to a date.
```

--------------------------------

### Initialize Signature Algorithm Wrapper

Source: https://guillp.github.io/jwskate/api

Initializes a signature algorithm wrapper with the current key. This returns an instance of a `BaseSignatureAlg` subclass. Supply an algorithm identifier if it's not present in the JWK.

```python
def signature_wrapper(self, alg: str | None = None) -> BaseSignatureAlg:
    """Initialize a  key management wrapper with this key.

    This returns an instance of a `BaseSignatureAlg` subclass.

    If this key doesn't have an `alg` parameter, you must supply one as parameter to this method.

    Args:
        alg: the algorithm identifier, if not already present in this Jwk

    Returns:
        a `BaseSignatureAlg` instance initialized with the current key

    """
    alg_class = self.signature_class(alg)
    if issubclass(alg_class, BaseSymmetricAlg):
        return alg_class(self.key)
    elif issubclass(alg_class, BaseAsymmetricAlg):
        return alg_class(self.cryptography_key)
    raise UnsupportedAlg(alg)  # pragma: no cover
```

--------------------------------

### Get RSAJwk Private Exponent

Source: https://guillp.github.io/jwskate/api

Retrieves and returns the private exponent (d) of the RSAJwk, decoded from base64url.

```python
return BinaPy(self.d).decode_from("b64u").to_int()
```

--------------------------------

### public_alg

Source: https://guillp.github.io/jwskate/api

Returns a new algorithm instance initialized with the public key.

```APIDOC
## public_alg

### Description
Return an alg instance initialised with the public key.

### Returns
- `Self`: An alg instance initialized with the public key.

### Raises
- `PrivateKeyRequired`: if the configured key is not private.
```

--------------------------------

### Generating New Keys

Source: https://guillp.github.io/jwskate/usage

Demonstrates how to generate new JWK keys for specific algorithms or key types.

```APIDOC
## Generating new keys

Usage | Method
---|---
For a specific algorithm | `Jwk.generate(alg='ES256')`
For a specific key type | `Jwk.generate(kty='RSA')`

```
Tokens:
Raw