0
# JOSEPY
1

2
A comprehensive Python implementation of the JOSE (Javascript Object Signing and Encryption) standards developed by the IETF. Provides JSON Web Algorithms (JWA), JSON Web Key (JWK), and JSON Web Signature (JWS) functionality for secure token handling, digital signatures, and cryptographic key operations.
3

4
## Package Information
5

6
- **Package Name**: josepy
7
- **Language**: Python
8
- **Installation**: `pip install josepy`
9
- **License**: Apache License 2.0
10
- **Homepage**: https://github.com/certbot/josepy
11

12
## Core Imports
13

14
```python
15
import josepy
16
```
17

18
Common usage imports:
19

20
```python
21
from josepy import JWK, JWS, Header, b64encode, b64decode
22
from josepy import RS256, ES256, HS256  # Signature algorithms
23
from josepy import JWKRSA, JWKEC, JWKOct  # Key types
24
```
25

26
## Basic Usage
27

28
```python
29
from josepy import JWKRSA, JWS, Header, RS256
30
from cryptography.hazmat.primitives.asymmetric import rsa
31
from cryptography.hazmat.backends import default_backend
32

33
# Generate RSA key pair
34
private_key = rsa.generate_private_key(
35
    public_exponent=65537,
36
    key_size=2048,
37
    backend=default_backend()
38
)
39

40
# Create JWK from cryptography key
41
jwk = JWKRSA(key=private_key)
42

43
# Create JWS with payload
44
payload = b'{"msg": "Hello, JOSE!"}'
45
header = Header(alg=RS256)
46

47
# Sign the payload
48
jws = JWS.sign(payload, key=jwk, alg=RS256)
49

50
# Serialize to JSON
51
jws_json = jws.json_dumps()
52

53
# Verify signature (using public key)
54
public_jwk = jwk.public_key()
55
verified_jws = JWS.json_loads(jws_json)
56
is_valid = verified_jws.verify(public_jwk)
57
if is_valid:
58
    print(verified_jws.payload.decode())  # {"msg": "Hello, JOSE!"}
59
else:
60
    print("Signature verification failed")
61
```
62

63
## Architecture
64

65
JOSEPY follows the JOSE standard architecture with three main components:
66

67
- **JSON Web Algorithms (JWA)**: Cryptographic algorithms for signing and verification
68
- **JSON Web Keys (JWK)**: Key representation and management for RSA, ECDSA, and symmetric keys
69
- **JSON Web Signature (JWS)**: Complete signing and verification workflow with headers and payloads
70

71
The library provides a type-safe, serializable interface built on the `cryptography` library for all cryptographic operations, with comprehensive error handling and RFC-compliant implementations.
72

73
## Capabilities
74

75
### JSON Web Algorithms (JWA)
76

77
Cryptographic signature algorithms supporting HMAC, RSA, and ECDSA variants with different hash functions. All algorithms provide sign() and verify() methods for secure token operations.
78

79
```python { .api }
80
# Signature algorithm instances
81
RS256: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-256
82
RS384: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-384
83
RS512: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-512
84
PS256: JWASignature  # RSASSA-PSS using SHA-256 and MGF1
85
PS384: JWASignature  # RSASSA-PSS using SHA-384 and MGF1
86
PS512: JWASignature  # RSASSA-PSS using SHA-512 and MGF1
87
ES256: JWASignature  # ECDSA using P-256 and SHA-256
88
ES384: JWASignature  # ECDSA using P-384 and SHA-384
89
ES512: JWASignature  # ECDSA using P-521 and SHA-512
90
HS256: JWASignature  # HMAC using SHA-256
91
HS384: JWASignature  # HMAC using SHA-384
92
HS512: JWASignature  # HMAC using SHA-512
93
```
94

95
[JSON Web Algorithms](./jwa.md)
96

97
### JSON Web Keys (JWK)
98

99
Key representation and management for RSA, Elliptic Curve, and symmetric keys with support for key loading, thumbprint generation, and public key extraction.
100

101
```python { .api }
102
class JWK:
103
    def thumbprint(self, hash_function=hashes.SHA256) -> bytes: ...
104
    def public_key(self) -> 'JWK': ...
105
    @classmethod
106
    def from_json(cls, jobj) -> 'JWK': ...
107

108
class JWKRSA(JWK):
109
    def __init__(self, key=None): ...
110

111
class JWKEC(JWK):
112
    def __init__(self, key=None): ...
113

114
class JWKOct(JWK):
115
    def __init__(self, key=None): ...
116
```
117

118
[JSON Web Keys](./jwk.md)
119

120
### JSON Web Signature (JWS)
121

122
Complete signing and verification workflow with header and payload management, supporting multiple serialization formats and comprehensive validation.
123

124
```python { .api }
125
class JWS:
126
    @classmethod
127
    def sign(cls, payload: bytes, **kwargs) -> 'JWS': ...
128
    def verify(self, key: Optional[JWK] = None) -> bool: ...
129
    def json_dumps(self, **kwargs) -> str: ...
130
    @classmethod
131
    def json_loads(cls, json_string: str) -> 'JWS': ...
132

133
class Header:
134
    def __init__(self, alg=None, **kwargs): ...
135
```
136

137
[JSON Web Signature](./jws.md)
138

139
### Base64 and JSON Utilities
140

141
JOSE-compliant base64 encoding/decoding and JSON serialization utilities with support for certificates, CSRs, and typed field handling.
142

143
```python { .api }
144
def b64encode(data: bytes) -> bytes: ...
145
def b64decode(data: Union[bytes, str]) -> bytes: ...
146
def encode_cert(cert: x509.Certificate) -> str: ...
147
def decode_cert(b64der: str) -> x509.Certificate: ...
148
def encode_csr(csr: x509.CertificateSigningRequest) -> str: ...
149
def decode_csr(b64der: str) -> x509.CertificateSigningRequest: ...
150
```
151

152
[Base64 and JSON Utilities](./utilities.md)
153

154
### Error Handling
155

156
Comprehensive error hierarchy for serialization, deserialization, and cryptographic operation failures with detailed error information.
157

158
```python { .api }
159
class Error(Exception): ...
160
class DeserializationError(Error): ...
161
class SerializationError(Error): ...
162
class UnrecognizedTypeError(DeserializationError):
163
    def __init__(self, typ: str, jobj: Any): ...
164
```
165

166
[Error Handling](./errors.md)
167

168
### JSON Serialization Interfaces
169

170
Core interfaces and base classes for JSON serialization and deserialization with support for partial and full serialization modes, implemented by all JOSE objects.
171

172
```python { .api }
173
class JSONDeSerializable:
174
    def to_partial_json(self) -> Any: ...
175
    def to_json(self) -> Any: ...
176
    @classmethod
177
    def from_json(cls, jobj: Any) -> 'JSONDeSerializable': ...
178
    @classmethod
179
    def json_loads(cls, json_string: Union[str, bytes]) -> 'JSONDeSerializable': ...
180
    def json_dumps(self, **kwargs) -> str: ...
181
    def json_dumps_pretty(self) -> str: ...
182
```
183

184
[JSON Serialization Interfaces](./interfaces.md)
185

186
## Types
187

188
```python { .api }
189
class JSONDeSerializable:
190
    def to_partial_json(self) -> Any: ...
191
    def to_json(self) -> Any: ...
192
    @classmethod
193
    def from_json(cls, jobj: Any): ...
194
    def json_dumps(self, **kwargs) -> str: ...
195
    @classmethod
196
    def json_loads(cls, json_string: Union[str, bytes]): ...
197

198
class JSONObjectWithFields(JSONDeSerializable):
199
    """Base class for JSON objects with field definitions"""
200

201
class Field:
202
    """Field descriptor for JSON object properties"""
203

204
class ComparableKey:
205
    """Comparable wrapper for cryptography keys"""
206

207
class ImmutableMap:
208
    """Immutable key-to-value mapping with attribute access"""
209

210
class MediaType:
211
    """Media Type field encoder/decoder for JOSE headers"""
212
    PREFIX = "application/"
213
    @classmethod
214
    def decode(cls, value: str) -> str: ...
215
    @classmethod
216
    def encode(cls, value: str) -> str: ...
217
```