0
# Python-Yubico
1

2
A comprehensive Python library for communicating with Yubico YubiKey hardware authentication tokens. It enables bidirectional USB communication for advanced YubiKey operations including device configuration, challenge-response authentication, and device management functions.
3

4
## Package Information
5

6
- **Package Name**: python-yubico
7
- **Language**: Python
8
- **Installation**: `pip install python-yubico`
9
- **Dependencies**: `pyusb` (for USB HID communication)
10

11
## Core Imports
12

13
```python
14
import yubico
15
```
16

17
For specific components:
18

19
```python
20
from yubico import find_yubikey, YubiKey
21
from yubico.yubikey_config import YubiKeyConfig
22
from yubico.yubico_exception import YubicoError
23
```
24

25
## Basic Usage
26

27
```python
28
import yubico
29

30
try:
31
    # Find and connect to YubiKey
32
    yubikey = yubico.find_yubikey(debug=False)
33
    
34
    # Get device information
35
    print("Version:", yubikey.version())
36
    print("Serial:", yubikey.serial())
37
    
38
    # Simple challenge-response example
39
    challenge = b"test challenge data"
40
    response = yubikey.challenge_response(challenge, mode='HMAC', slot=1)
41
    print("Response:", response.hex())
42
    
43
except yubico.yubico_exception.YubicoError as e:
44
    print("ERROR:", e.reason)
45
```
46

47
## Architecture
48

49
The library uses a hierarchical class structure:
50

51
- **Device Discovery**: `find_yubikey()` automatically detects and returns the appropriate YubiKey class instance
52
- **YubiKey Base Class**: Abstract interface providing common methods across all YubiKey versions
53
- **Device-Specific Classes**: `YubiKeyUSBHID`, `YubiKeyNEO_USBHID`, `YubiKey4_USBHID` handle version-specific features
54
- **Configuration System**: `YubiKeyConfig` provides declarative configuration with validation and version compatibility checking
55
- **Frame Protocol**: `YubiKeyFrame` handles low-level USB HID communication protocol
56

57
This design abstracts hardware differences while providing full access to device-specific capabilities, making it suitable for both simple authentication tasks and advanced YubiKey management applications.
58

59
## Capabilities
60

61
### Device Discovery and Connection
62

63
Locate and establish communication with YubiKey devices, supporting multiple connected devices and providing automatic device type detection.
64

65
```python { .api }
66
def find_yubikey(debug=False, skip=0):
67
    """
68
    Locate and connect to a YubiKey device.
69
    
70
    Parameters:
71
    - debug (bool): Enable debug output
72
    - skip (int): Number of devices to skip
73
    
74
    Returns:
75
    YubiKey: Connected YubiKey instance
76
    
77
    Raises:
78
    YubiKeyError: If no YubiKey found
79
    """
80
```
81

82
[Device Discovery](./device-discovery.md)
83

84
### YubiKey Device Interface
85

86
Core device operations including version detection, serial number retrieval, and basic device status queries available across all YubiKey models.
87

88
```python { .api }
89
class YubiKey:
90
    def version(self): ...
91
    def serial(self, may_block=True): ...
92
    def challenge_response(self, challenge, mode='HMAC', slot=1, variable=True, may_block=True): ...
93
    def write_config(self, cfg, slot): ...
94
```
95

96
[Device Interface](./device-interface.md)
97

98
### YubiKey Configuration
99

100
Comprehensive configuration system supporting all YubiKey modes including Yubico OTP, OATH-HOTP, and challenge-response with full control over device settings, flags, and security parameters.
101

102
```python { .api }
103
class YubiKeyConfig:
104
    def __init__(self, ykver=None, capabilities=None, update=False, swap=False, zap=False): ...
105
    def mode_yubikey_otp(self, private_uid, aes_key): ...
106
    def mode_oath_hotp(self, secret, digits=6, factor_seed=None, omp=0x0, tt=0x0, mui=''): ...
107
    def mode_challenge_response(self, secret, type='HMAC', variable=True, require_button=False): ...
108
    def aes_key(self, data): ...
109
    def ticket_flag(self, which, new=None): ...
110
    def config_flag(self, which, new=None): ...
111
    def extended_flag(self, which, new=None): ...
112
```
113

114
[YubiKey Configuration](./configuration.md)
115

116
### Challenge-Response Operations
117

118
HMAC-SHA1 and Yubico challenge-response authentication for secure authentication workflows, supporting both variable and fixed-length responses.
119

120
```python { .api }
121
def challenge_response(challenge, mode='HMAC', slot=1, variable=True, may_block=True):
122
    """
123
    Perform challenge-response operation.
124
    
125
    Parameters:
126
    - challenge (bytes): Challenge data
127
    - mode (str): 'HMAC' or 'OTP'
128
    - slot (int): Configuration slot (1 or 2)
129
    - variable (bool): Variable length response
130
    - may_block (bool): Allow blocking operations
131
    
132
    Returns:
133
    bytes: Response data
134
    """
135
```
136

137
[Challenge-Response](./challenge-response.md)
138

139
### Exception Handling
140

141
Comprehensive error handling with specific exception types for different failure modes including device communication errors, configuration errors, and timeout conditions.
142

143
```python { .api }
144
class YubicoError(Exception):
145
    def __init__(self, reason): ...
146

147
class YubiKeyError(YubicoError): ...
148
class YubiKeyTimeout(YubiKeyError): ...
149
class YubiKeyVersionError(YubiKeyError): ...
150
class InputError(YubicoError): ...
151
```
152

153
[Exception Handling](./exceptions.md)
154

155
### Utility Functions
156

157
Helper functions for data processing, CRC validation, hex dumping, and ModHex encoding/decoding operations commonly needed in YubiKey applications.
158

159
```python { .api }
160
def crc16(data): ...
161
def validate_crc16(data): ...
162
def hexdump(src, length=8, colorize=False): ...
163
def modhex_decode(data): ...
164
def hotp_truncate(hmac_result, length=6): ...
165
```
166

167
[Utilities](./utilities.md)
168

169
## Constants and Definitions
170

171
### SLOT Constants
172
Configuration slot identifiers and command constants:
173

174
```python { .api }
175
class SLOT:
176
    CONFIG = 0x01      # First configuration slot
177
    CONFIG2 = 0x03     # Second configuration slot
178
    UPDATE1 = 0x04     # Update slot 1
179
    UPDATE2 = 0x05     # Update slot 2
180
    SWAP = 0x06        # Swap slots
181
    NDEF = 0x08        # Write NDEF record
182
```
183

184
### Device Mode Constants
185
YubiKey operating mode identifiers:
186

187
```python { .api }
188
class MODE:
189
    OTP = 0x00                # OTP only
190
    CCID = 0x01               # CCID only, no eject
191
    OTP_CCID = 0x02           # OTP + CCID composite
192
    U2F = 0x03                # U2F mode
193
    OTP_U2F = 0x04            # OTP + U2F composite
194
    U2F_CCID = 0x05           # U2F + CCID composite
195
    OTP_U2F_CCID = 0x06       # OTP + U2F + CCID composite
196
    MASK = 0x07               # Mask for mode bits
197
    FLAG_EJECT = 0x80         # CCID device supports eject
198
```
199

200
### USB Product IDs
201
YubiKey hardware model identification:
202

203
```python { .api }
204
class PID:
205
    YUBIKEY = 0x0010          # YubiKey (versions 1 and 2)
206
    NEO_OTP = 0x0110          # YubiKey NEO - OTP only
207
    NEO_OTP_CCID = 0x0111     # YubiKey NEO - OTP and CCID
208
    NEO_CCID = 0x0112         # YubiKey NEO - CCID only
209
    NEO_U2F = 0x0113          # YubiKey NEO - U2F only
210
    NEO_OTP_U2F = 0x0114      # YubiKey NEO - OTP and U2F
211
    NEO_U2F_CCID = 0x0115     # YubiKey NEO - U2F and CCID
212
    NEO_OTP_U2F_CCID = 0x0116 # YubiKey NEO - OTP, U2F and CCID
213
    YK4_OTP = 0x0401          # YubiKey 4 - OTP only
214
    YK4_U2F = 0x0402          # YubiKey 4 - U2F only
215
    YK4_OTP_U2F = 0x0403      # YubiKey 4 - OTP and U2F
216
    YK4_CCID = 0x0404         # YubiKey 4 - CCID only
217
    YK4_OTP_CCID = 0x0405     # YubiKey 4 - OTP and CCID
218
    YK4_U2F_CCID = 0x0406     # YubiKey 4 - U2F and CCID
219
    YK4_OTP_U2F_CCID = 0x0407 # YubiKey 4 - OTP, U2F and CCID
220
```