---
title: crypto
sidebarTitle: crypto
---

# `keycardai.oauth.utils.crypto`


Cryptographic utilities for OAuth 2.0 (RFC 8705).

This module implements mutual TLS authentication and certificate-bound
access tokens as defined in RFC 8705.

RFC 8705: OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
https://datatracker.ietf.org/doc/html/rfc8705

Key Features:
- Certificate-based client authentication (mTLS)
- Certificate-bound access tokens for enhanced security
- Certificate thumbprint generation and validation
- X.509 certificate utilities

Security Benefits:
- Prevents token theft and replay attacks
- Eliminates client secret management issues
- Enables zero-trust architecture patterns
- Strong cryptographic authentication


## Classes

### `CertificateBoundToken` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Certificate-bound access token metadata for RFC 8705.

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-3


### `MutualTLSClientAuth` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L35" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Mutual TLS client authentication utilities for RFC 8705.

Implements certificate-based client authentication and certificate-bound
access tokens as specified in RFC 8705.

Reference: https://datatracker.ietf.org/doc/html/rfc8705


**Methods:**

#### `generate_cert_thumbprint` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L57" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_cert_thumbprint(certificate_pem: str) -> str
```

Generate SHA256 thumbprint of X.509 certificate.

Creates the x5t#S256 thumbprint used for certificate-bound tokens
as defined in RFC 8705 Section 3.

**Args:**
- `certificate_pem`: X.509 certificate in PEM format

**Returns:**
- Base64url-encoded SHA256 thumbprint

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-3


#### `extract_certificate_info` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L77" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
extract_certificate_info(certificate_pem: str) -> dict
```

Extract relevant information from X.509 certificate.

Parses certificate to extract subject DN, issuer, validity dates,
and other metadata useful for mTLS authentication.

**Args:**
- `certificate_pem`: X.509 certificate in PEM format

**Returns:**
- Dictionary containing certificate metadata

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-2


#### `validate_cert_bound_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L94" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_cert_bound_token(self, access_token: str, client_certificate: str) -> bool
```

Validate certificate-bound access token.

Verifies that the access token is bound to the provided client
certificate by comparing certificate thumbprints.

**Args:**
- `access_token`: JWT access token (should contain cnf claim)
- `client_certificate`: Client certificate in PEM format

**Returns:**
- True if token is bound to certificate, False otherwise

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-3


#### `create_certificate_bound_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_certificate_bound_token(self, base_token: dict, certificate_pem: str) -> dict
```

Create certificate-bound access token.

Adds the cnf (confirmation) claim to an access token to bind it
to a specific client certificate.

**Args:**
- `base_token`: Base JWT payload dictionary
- `certificate_pem`: Client certificate in PEM format

**Returns:**
- Token payload with cnf claim added

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-3.1


#### `validate_certificate_chain` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/crypto.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_certificate_chain(certificate_pem: str, ca_bundle: str | None = None) -> bool
```

Validate X.509 certificate chain.

Validates certificate chain up to trusted root CA and checks
certificate validity dates and revocation status.

**Args:**
- `certificate_pem`: Client certificate in PEM format
- `ca_bundle`: Optional CA bundle for validation

**Returns:**
- True if certificate chain is valid, False otherwise

Reference: https://datatracker.ietf.org/doc/html/rfc8705#section-2

