0
# OpenID Utilities
1

2
Core utility functions and classes providing essential functionality for OpenID implementations. These utilities handle URI normalization, cryptographic operations, key-value form processing, logging, and Diffie-Hellman key exchange operations.
3

4
## Capabilities
5

6
### Logging and Debugging
7

8
Logging infrastructure and debugging utilities for OpenID operations.
9

10
```python { .api }
11
def log(message, level=0):
12
    """
13
    Log a message at the specified level.
14
    
15
    Parameters:
16
    - message: str, the message to log
17
    - level: int, logging level (0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR)
18
    """
19

20
def autoSubmitHTML(form, title='OpenID transaction in progress'):
21
    """
22
    Generate HTML page that automatically submits a form.
23
    
24
    Parameters:
25
    - form: str, HTML form markup to auto-submit
26
    - title: str, page title for the auto-submit page
27
    
28
    Returns:
29
    str: Complete HTML page with auto-submit JavaScript
30
    """
31

32
def toUnicode(value):
33
    """
34
    Convert value to Unicode string.
35
    
36
    Parameters:
37
    - value: str or bytes, value to convert
38
    
39
    Returns:
40
    str: Unicode representation of the input value
41
    """
42
```
43

44
### URI Normalization
45

46
RFC 3986 compliant URI normalization for OpenID identifier processing.
47

48
```python { .api }
49
def urinorm(uri):
50
    """
51
    Normalize a URI according to RFC 3986.
52
    
53
    Parameters:
54
    - uri: str, URI to normalize
55
    
56
    Returns:
57
    str: Normalized URI
58
    
59
    Raises:
60
    ValueError: if URI contains illegal characters or malformed components
61
    """
62

63
def urlnorm(url):
64
    """
65
    Normalize a URL (alias for urinorm).
66
    
67
    Parameters:
68
    - url: str, URL to normalize
69
    
70
    Returns:
71
    str: Normalized URL
72
    """
73

74
def urlencode_unreserved(query):
75
    """
76
    URL encode query parameters, leaving unreserved characters unencoded.
77
    
78
    Parameters:
79
    - query: dict or list of tuples, query parameters
80
    
81
    Returns:
82
    str: URL encoded query string
83
    """
84
```
85

86
### Key-Value Form Processing
87

88
Processing of OpenID key-value form data format.
89

90
```python { .api }
91
def kvToDict(kv):
92
    """
93
    Parse key-value form data into a dictionary.
94
    
95
    Parameters:
96
    - kv: str, key-value form data (key:value\\nkey:value format)
97
    
98
    Returns:
99
    dict: Parsed key-value pairs
100
    
101
    Raises:
102
    ValueError: if form data is malformed
103
    """
104

105
def dictToKV(data):
106
    """
107
    Convert dictionary to key-value form data format.
108
    
109
    Parameters:
110
    - data: dict, key-value pairs to encode
111
    
112
    Returns:
113
    str: Key-value form data string
114
    """
115

116
def seqToKV(seq, sep=':'):
117
    """
118
    Convert sequence of pairs to key-value format.
119
    
120
    Parameters:
121
    - seq: list of tuples, key-value pairs
122
    - sep: str, separator character (default ':')
123
    
124
    Returns:
125
    str: Key-value formatted string
126
    """
127
```
128

129
### Cryptographic Utilities
130

131
Cryptographic helper functions for OpenID operations.
132

133
```python { .api }
134
def randomString(length, chrs=None):
135
    """
136
    Generate cryptographically secure random string.
137
    
138
    Parameters:
139
    - length: int, desired string length
140
    - chrs: str, character set to use (default: base64 characters)
141
    
142
    Returns:
143
    str: Random string of specified length
144
    """
145

146
def sha1(data):
147
    """
148
    Compute SHA-1 hash of data.
149
    
150
    Parameters:
151
    - data: bytes, data to hash
152
    
153
    Returns:
154
    bytes: SHA-1 hash digest
155
    """
156

157
def sha256(data):
158
    """
159
    Compute SHA-256 hash of data.
160
    
161
    Parameters:
162
    - data: bytes, data to hash
163
    
164
    Returns:
165
    bytes: SHA-256 hash digest
166
    """
167

168
def hmacSha1(key, data):
169
    """
170
    Compute HMAC-SHA1 of data with key.
171
    
172
    Parameters:
173
    - key: bytes, HMAC key
174
    - data: bytes, data to authenticate
175
    
176
    Returns:
177
    bytes: HMAC-SHA1 digest
178
    """
179

180
def hmacSha256(key, data):
181
    """
182
    Compute HMAC-SHA256 of data with key.
183
    
184
    Parameters:
185
    - key: bytes, HMAC key
186
    - data: bytes, data to authenticate
187
    
188
    Returns:
189
    bytes: HMAC-SHA256 digest
190
    """
191
```
192

193
### Base64 Encoding
194

195
Base64 encoding utilities for OpenID data handling.
196

197
```python { .api }
198
def toBase64(data):
199
    """
200
    Encode data to base64 string.
201
    
202
    Parameters:
203
    - data: bytes, data to encode
204
    
205
    Returns:
206
    str: Base64 encoded string
207
    """
208

209
def fromBase64(data):
210
    """
211
    Decode base64 string to bytes.
212
    
213
    Parameters:
214
    - data: str, base64 encoded string
215
    
216
    Returns:
217
    bytes: Decoded data
218
    
219
    Raises:
220
    ValueError: if input is not valid base64
221
    """
222
```
223

224
### Diffie-Hellman Key Exchange
225

226
Diffie-Hellman key exchange implementation for secure association establishment.
227

228
```python { .api }
229
class DiffieHellman:
230
    """
231
    Diffie-Hellman key exchange implementation.
232
    """
233
    
234
    def __init__(self, modulus, generator, private=None):
235
        """
236
        Initialize DH parameters.
237
        
238
        Parameters:
239
        - modulus: int, DH modulus (p)
240
        - generator: int, DH generator (g)
241
        - private: int, private key (optional, generated if not provided)
242
        """
243
    
244
    def createKeyExchange(cls, modulus=None, generator=None):
245
        """
246
        Create a new DH key exchange with default or custom parameters.
247
        
248
        Parameters:
249
        - modulus: int, DH modulus (default: OpenID default modulus)
250
        - generator: int, DH generator (default: 2)
251
        
252
        Returns:
253
        DiffieHellman: New DH instance
254
        """
255
    
256
    def getSharedSecret(self, other_public):
257
        """
258
        Compute shared secret from other party's public key.
259
        
260
        Parameters:
261
        - other_public: int, other party's public key
262
        
263
        Returns:
264
        bytes: Shared secret
265
        """
266
    
267
    def xorSecret(self, hash_func, shared_secret, composite):
268
        """
269
        XOR secret with composite using hash function.
270
        
271
        Parameters:
272
        - hash_func: callable, hash function (sha1 or sha256)
273
        - shared_secret: bytes, DH shared secret
274
        - composite: bytes, data to XOR with hashed secret
275
        
276
        Returns:
277
        bytes: XORed result
278
        """
279

280
# DH Constants
281
DEFAULT_MOD = 155172898181473697471232257763715539915724801966915404479707795314057629378541917580651227423698188993727816152646631438561595825688188889951272158842675419950341258706556549803580104870537681476726513255747040765857479291291572334510643245094715007229621094194349783925984760375594985848253359305585439638443
282
DEFAULT_GEN = 2