0
# Encoding and Hash Validation
1

2
Validators for various encoding formats and cryptographic hash functions. These validators ensure data integrity and proper encoding format compliance for base encodings and cryptographic hashes.
3

4
## Capabilities
5

6
### Base Encoding Validation
7

8
Validates strings encoded in various base formats commonly used in data transmission and storage.
9

10
```python { .api }
11
def base16(value: str, /) -> Union[Literal[True], ValidationError]:
12
    """
13
    Validate base16 (hexadecimal) encoded strings.
14
    
15
    Parameters:
16
    - value: String to validate as base16
17
    
18
    Returns:
19
    True if valid base16, ValidationError otherwise
20
    
21
    Validates hexadecimal strings containing only:
22
    - Digits: 0-9
23
    - Letters: A-F or a-f
24
    - Even number of characters (each byte = 2 hex chars)
25
    """
26

27
def base32(value: str, /) -> Union[Literal[True], ValidationError]:
28
    """
29
    Validate base32 encoded strings per RFC 4648.
30
    
31
    Parameters:
32
    - value: String to validate as base32
33
    
34
    Returns:
35
    True if valid base32, ValidationError otherwise
36
    
37
    Validates base32 strings containing:
38
    - Letters: A-Z
39
    - Digits: 2-7
40
    - Padding: = characters at end if needed
41
    - Proper length alignment (groups of 8 characters)
42
    """
43

44
def base58(value: str, /) -> Union[Literal[True], ValidationError]:
45
    """
46
    Validate base58 encoded strings.
47
    
48
    Parameters:
49
    - value: String to validate as base58
50
    
51
    Returns:
52
    True if valid base58, ValidationError otherwise
53
    
54
    Validates base58 strings using Bitcoin alphabet:
55
    - Excludes confusing characters: 0, O, I, l
56
    - Uses: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
57
    - Commonly used in cryptocurrency addresses
58
    """
59

60
def base64(value: str, /) -> Union[Literal[True], ValidationError]:
61
    """
62
    Validate base64 encoded strings per RFC 4648.
63
    
64
    Parameters:
65
    - value: String to validate as base64
66
    
67
    Returns:
68
    True if valid base64, ValidationError otherwise
69
    
70
    Validates base64 strings containing:
71
    - Letters: A-Z, a-z
72
    - Digits: 0-9  
73
    - Symbols: +, /
74
    - Padding: = characters at end if needed
75
    - Proper length alignment (groups of 4 characters)
76
    """
77
```
78

79
### Cryptographic Hash Validation
80

81
Validates cryptographic hash strings for integrity verification and security applications.
82

83
```python { .api }
84
def md5(value: str, /) -> Union[Literal[True], ValidationError]:
85
    """
86
    Validate MD5 hash strings.
87
    
88
    Parameters:
89
    - value: String to validate as MD5 hash
90
    
91
    Returns:
92
    True if valid MD5 hash, ValidationError otherwise
93
    
94
    Validates MD5 hashes:
95
    - Length: exactly 32 hexadecimal characters
96
    - Characters: 0-9, a-f (case insensitive)
97
    - Format: 128-bit hash as 32-character hex string
98
    
99
    Note: MD5 is cryptographically broken, use for legacy compatibility only.
100
    """
101

102
def sha1(value: str, /) -> Union[Literal[True], ValidationError]:
103
    """
104
    Validate SHA-1 hash strings.
105
    
106
    Parameters:
107
    - value: String to validate as SHA-1 hash
108
    
109
    Returns:
110
    True if valid SHA-1 hash, ValidationError otherwise
111
    
112
    Validates SHA-1 hashes:
113
    - Length: exactly 40 hexadecimal characters
114
    - Characters: 0-9, a-f (case insensitive)
115
    - Format: 160-bit hash as 40-character hex string
116
    
117
    Note: SHA-1 is deprecated for cryptographic use.
118
    """
119

120
def sha224(value: str, /) -> Union[Literal[True], ValidationError]:
121
    """
122
    Validate SHA-224 hash strings.
123
    
124
    Parameters:
125
    - value: String to validate as SHA-224 hash
126
    
127
    Returns:
128
    True if valid SHA-224 hash, ValidationError otherwise
129
    
130
    Validates SHA-224 hashes:
131
    - Length: exactly 56 hexadecimal characters
132
    - Characters: 0-9, a-f (case insensitive)
133
    - Format: 224-bit hash as 56-character hex string
134
    """
135

136
def sha256(value: str, /) -> Union[Literal[True], ValidationError]:
137
    """
138
    Validate SHA-256 hash strings.
139
    
140
    Parameters:
141
    - value: String to validate as SHA-256 hash
142
    
143
    Returns:
144
    True if valid SHA-256 hash, ValidationError otherwise
145
    
146
    Validates SHA-256 hashes:
147
    - Length: exactly 64 hexadecimal characters
148
    - Characters: 0-9, a-f (case insensitive)
149
    - Format: 256-bit hash as 64-character hex string
150
    
151
    Most commonly used secure hash algorithm.
152
    """
153

154
def sha384(value: str, /) -> Union[Literal[True], ValidationError]:
155
    """
156
    Validate SHA-384 hash strings.
157
    
158
    Parameters:
159
    - value: String to validate as SHA-384 hash
160
    
161
    Returns:
162
    True if valid SHA-384 hash, ValidationError otherwise
163
    
164
    Validates SHA-384 hashes:
165
    - Length: exactly 96 hexadecimal characters
166
    - Characters: 0-9, a-f (case insensitive)
167
    - Format: 384-bit hash as 96-character hex string
168
    """
169

170
def sha512(value: str, /) -> Union[Literal[True], ValidationError]:
171
    """
172
    Validate SHA-512 hash strings.
173
    
174
    Parameters:
175
    - value: String to validate as SHA-512 hash
176
    
177
    Returns:
178
    True if valid SHA-512 hash, ValidationError otherwise
179
    
180
    Validates SHA-512 hashes:
181
    - Length: exactly 128 hexadecimal characters
182
    - Characters: 0-9, a-f (case insensitive)
183
    - Format: 512-bit hash as 128-character hex string
184
    
185
    Highest security level in SHA-2 family.
186
    """
187
```
188

189
## Usage Examples
190

191
```python
192
import validators
193

194
# Base encoding validation
195
validators.base16('48656c6c6f20576f726c64')     # True (hex)
196
validators.base16('Hello World')                # ValidationError (not hex)
197

198
validators.base32('JBSWY3DPEBLW64TMMQQQ====')  # True
199
validators.base32('HelloWorld123')              # ValidationError (invalid chars)
200

201
validators.base58('3mJr7YhWNM')                 # True
202
validators.base58('3mJr7YhWNM0O')               # ValidationError (contains 0, O)
203

204
validators.base64('SGVsbG8gV29ybGQ=')           # True
205
validators.base64('Hello World!')               # ValidationError (invalid chars)
206

207
# Hash validation
208
validators.md5('5d41402abc4b2a76b9719d911017c592')       # True (32 chars)
209
validators.md5('hello')                                  # ValidationError (too short)
210

211
validators.sha1('aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d')     # True (40 chars)
212
validators.sha256('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')  # True (64 chars)
213

214
# Case insensitive validation
215
validators.md5('5D41402ABC4B2A76B9719D911017C592')       # True (uppercase)
216
validators.sha256('E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855')  # True
217

218
# Invalid hash examples
219
validators.md5('5d41402abc4b2a76b9719d911017c59')        # ValidationError (31 chars, too short)
220
validators.sha256('hello')                               # ValidationError (too short)
221
validators.sha512('not-a-hash')                          # ValidationError (invalid format)
222
```
223

224
## Common Use Cases
225

226
### Data Integrity Verification
227

228
```python
229
import validators
230
import hashlib
231

232
def verify_file_hash(file_content: bytes, expected_hash: str, algorithm: str = 'sha256'):
233
    """Verify file integrity using hash validation."""
234
    
235
    # First validate the hash format
236
    if algorithm == 'md5' and not validators.md5(expected_hash):
237
        raise ValueError("Invalid MD5 hash format")
238
    elif algorithm == 'sha256' and not validators.sha256(expected_hash):
239
        raise ValueError("Invalid SHA-256 hash format")
240
    
241
    # Calculate actual hash
242
    hasher = hashlib.new(algorithm)
243
    hasher.update(file_content)
244
    actual_hash = hasher.hexdigest()
245
    
246
    return actual_hash.lower() == expected_hash.lower()
247

248
# Usage
249
file_data = b"Hello, World!"
250
expected = "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"
251
if verify_file_hash(file_data, expected):
252
    print("File integrity verified")
253
```
254

255
### Encoding Validation Pipeline
256

257
```python
258
import validators
259
import base64
260

261
def validate_and_decode_base64(encoded_data: str) -> bytes:
262
    """Validate base64 format and decode if valid."""
263
    
264
    if not validators.base64(encoded_data):
265
        raise ValueError("Invalid base64 format")
266
    
267
    try:
268
        return base64.b64decode(encoded_data)
269
    except Exception as e:
270
        raise ValueError(f"Base64 decode failed: {e}")
271

272
# Usage
273
encoded = "SGVsbG8gV29ybGQ="
274
if validators.base64(encoded):
275
    decoded = validate_and_decode_base64(encoded)
276
    print(f"Decoded: {decoded.decode()}")
277
```