0
# PEM Object Types
1

2
Complete set of PEM object classes representing different cryptographic objects. All classes inherit from `AbstractPEMObject` and provide specialized functionality while maintaining consistent access to raw content, payloads, and metadata.
3

4
## Base Class
5

6
### AbstractPEMObject
7

8
Base class for all parsed PEM objects providing common functionality for content access and manipulation.
9

10
```python { .api }
11
class AbstractPEMObject:
12
    """Base class for all PEM objects."""
13
    
14
    def __init__(self, pem_bytes: bytes | str):
15
        """Initialize with PEM-encoded content."""
16
    
17
    def __str__(self) -> str:
18
        """Return the PEM-encoded content as a native string."""
19
    
20
    def __repr__(self) -> str:
21
        """Return a string representation with class name and SHA-1 digest."""
22
    
23
    def __eq__(self, other: object) -> bool:
24
        """Compare objects for equality based on type and content."""
25
    
26
    def __hash__(self) -> int:
27
        """Return hash of the PEM bytes for use in sets and dictionaries."""
28
    
29
    @property
30
    def sha1_hexdigest(self) -> str:
31
        """SHA-1 digest of the whole object for differentiation."""
32
    
33
    def as_bytes(self) -> bytes:
34
        """Return PEM-encoded content as bytes."""
35
    
36
    def as_text(self) -> str:
37
        """Return PEM-encoded content as text."""
38
    
39
    @property
40
    def bytes_payload(self) -> bytes:
41
        """Base64 payload without headers."""
42
    
43
    @property
44
    def text_payload(self) -> str:
45
        """Base64 payload as text."""
46
    
47
    @property
48
    def decoded_payload(self) -> bytes:
49
        """Base64-decoded payload."""
50
    
51
    @property
52
    def meta_headers(self) -> dict[str, str]:
53
        """Dictionary of payload headers (if any)."""
54
```
55

56
## Certificate Types
57

58
### Certificate
59

60
Standard X.509 certificate objects.
61

62
```python { .api }
63
class Certificate(AbstractPEMObject):
64
    """Standard certificate."""
65
```
66

67
### OpenSSLTrustedCertificate
68

69
OpenSSL "trusted certificate" format with additional metadata.
70

71
```python { .api }
72
class OpenSSLTrustedCertificate(Certificate):
73
    """OpenSSL trusted certificate with metadata."""
74
```
75

76
### CertificateRequest
77

78
Certificate signing request (CSR) objects.
79

80
```python { .api }
81
class CertificateRequest(AbstractPEMObject):
82
    """Certificate signing request."""
83
```
84

85
### CertificateRevocationList
86

87
Certificate revocation list (CRL) objects.
88

89
```python { .api }
90
class CertificateRevocationList(AbstractPEMObject):
91
    """Certificate revocation list."""
92
```
93

94
## Key Types
95

96
### Key Hierarchy
97

98
Base classes for different key types.
99

100
```python { .api }
101
class Key(AbstractPEMObject):
102
    """Base class for keys of unknown type."""
103

104
class PrivateKey(Key):
105
    """Private key of unknown type."""
106

107
class PublicKey(Key):
108
    """Public key of unknown type."""
109
```
110

111
### RSA Keys
112

113
RSA-specific key types.
114

115
```python { .api }
116
class RSAPrivateKey(PrivateKey):
117
    """RSA private key in PKCS#1 format."""
118

119
class RSAPublicKey(PublicKey):
120
    """RSA public key in PKCS#1 format."""
121
```
122

123
### Elliptic Curve Keys
124

125
Elliptic curve cryptography keys.
126

127
```python { .api }
128
class ECPrivateKey(PrivateKey):
129
    """Elliptic curve private key."""
130
```
131

132
### DSA Keys
133

134
Digital Signature Algorithm keys.
135

136
```python { .api }
137
class DSAPrivateKey(PrivateKey):
138
    """DSA private key (including OpenSSH legacy format)."""
139
```
140

141
### SSH Keys
142

143
SSH-specific key formats.
144

145
```python { .api }
146
class OpenSSHPrivateKey(PrivateKey):
147
    """OpenSSH private key format."""
148

149
class SSHPublicKey(PublicKey):
150
    """SSH RFC 4716 format public key."""
151

152
class SSHCOMPrivateKey(PrivateKey):
153
    """SSH.COM / Tectia format private key."""
154
```
155

156
## OpenPGP Types
157

158
OpenPGP armored key formats.
159

160
```python { .api }
161
class OpenPGPPublicKey(PublicKey):
162
    """RFC 4880 armored OpenPGP public key."""
163

164
class OpenPGPPrivateKey(PrivateKey):
165
    """RFC 4880 armored OpenPGP private key."""
166
```
167

168
## Other Object Types
169

170
### DHParameters
171

172
Diffie-Hellman parameters for key exchange.
173

174
```python { .api }
175
class DHParameters(AbstractPEMObject):
176
    """Diffie-Hellman parameters for DHE cipher suites."""
177
```
178

179
## Usage Examples
180

181
### Working with Certificates
182

183
```python
184
import pem
185

186
# Parse mixed PEM file
187
objects = pem.parse_file("bundle.pem")
188

189
# Filter by type
190
certificates = [obj for obj in objects if isinstance(obj, pem.Certificate)]
191
private_keys = [obj for obj in objects if isinstance(obj, pem.PrivateKey)]
192

193
# Access certificate properties
194
for cert in certificates:
195
    print(f"Certificate SHA-1: {cert.sha1_hexdigest}")
196
    print(f"Certificate text: {cert.as_text()}")
197
    
198
    # Access decoded certificate data for further processing
199
    der_data = cert.decoded_payload
200
```
201

202
### Key Type Detection
203

204
```python
205
import pem
206

207
objects = pem.parse_file("keys.pem")
208

209
for obj in objects:
210
    if isinstance(obj, pem.RSAPrivateKey):
211
        print("RSA private key found")
212
    elif isinstance(obj, pem.ECPrivateKey):
213
        print("EC private key found")
214
    elif isinstance(obj, pem.OpenSSHPrivateKey):
215
        print("OpenSSH private key found")
216
    elif isinstance(obj, pem.PrivateKey):
217
        print("Generic private key found")
218
```
219

220
### Accessing Metadata
221

222
```python
223
import pem
224

225
# Some PEM objects may contain headers
226
objects = pem.parse(pem_with_headers)
227

228
for obj in objects:
229
    headers = obj.meta_headers
230
    if headers:
231
        print(f"Headers: {headers}")
232
    
233
    # Access base64 payload
234
    b64_payload = obj.text_payload
235
    raw_payload = obj.decoded_payload
236
```
237

238
## Object Properties
239

240
All PEM objects are immutable and provide:
241

242
- **SHA-1 digests** cached for performance and cross-platform consistency  
243
- **Multiple content formats** (bytes, text, decoded)
244
- **Payload extraction** with header removal
245
- **Equality comparison** based on content
246
- **Hash support** for use in sets and dictionaries
247
- **Pattern-based recognition** automatically registered during class definition