pysesame-ble 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,225 @@
1
+ """Python library for controlling Candy House Sesame smart locks and accessories over BLE."""
2
+
3
+ from .__version__ import __version__
4
+ from .const import (
5
+ COMPANY_ID,
6
+ COMPANY_IDS,
7
+ ITEM_ADD_SESAME,
8
+ ITEM_AUTOLOCK,
9
+ ITEM_CARD_ADD,
10
+ ITEM_CARD_CHANGE,
11
+ ITEM_CARD_DELETE,
12
+ ITEM_CARD_FIRST,
13
+ ITEM_CARD_GET,
14
+ ITEM_CARD_LAST,
15
+ ITEM_CARD_MODE_SET,
16
+ ITEM_CARD_NOTIFY,
17
+ ITEM_CARD_VERIFY_TO_CLOUD,
18
+ ITEM_DOOR_CLOSED,
19
+ ITEM_DOOR_OPEN,
20
+ ITEM_ENABLE_DFU,
21
+ ITEM_FACE_CHANGE,
22
+ ITEM_FACE_DELETE,
23
+ ITEM_FACE_FIRST,
24
+ ITEM_FACE_GET,
25
+ ITEM_FACE_LAST,
26
+ ITEM_FACE_MODE_SET,
27
+ ITEM_FACE_NOTIFY,
28
+ ITEM_FINGER_CHANGE,
29
+ ITEM_FINGER_DELETE,
30
+ ITEM_FINGER_FIRST,
31
+ ITEM_FINGER_GET,
32
+ ITEM_FINGER_LAST,
33
+ ITEM_FINGER_MODE_SET,
34
+ ITEM_FINGER_NOTIFY,
35
+ ITEM_HISTORY,
36
+ ITEM_HISTORY_DELETE,
37
+ ITEM_INITIAL,
38
+ ITEM_KEYPAD_LOCK_LIST,
39
+ ITEM_LOCK,
40
+ ITEM_LOGIN,
41
+ ITEM_MAGNET,
42
+ ITEM_MECH_SETTING,
43
+ ITEM_MECH_STATUS,
44
+ ITEM_OPS_TIMER_SETTING,
45
+ ITEM_PALM_CHANGE,
46
+ ITEM_PALM_DELETE,
47
+ ITEM_PALM_FIRST,
48
+ ITEM_PALM_GET,
49
+ ITEM_PALM_LAST,
50
+ ITEM_PALM_MODE_SET,
51
+ ITEM_PALM_NOTIFY,
52
+ ITEM_PASSCODE_ADD,
53
+ ITEM_PASSCODE_CHANGE,
54
+ ITEM_PASSCODE_DELETE,
55
+ ITEM_PASSCODE_FIRST,
56
+ ITEM_PASSCODE_GET,
57
+ ITEM_PASSCODE_LAST,
58
+ ITEM_PASSCODE_MODE_SET,
59
+ ITEM_PASSCODE_NOTIFY,
60
+ ITEM_PASSCODE_VERIFY_TO_CLOUD,
61
+ ITEM_REGISTRATION,
62
+ ITEM_REMOVE_SESAME,
63
+ ITEM_TIME,
64
+ ITEM_UNLOCK,
65
+ ITEM_VERSION_TAG,
66
+ MTU_SIZE,
67
+ OP_CREATE,
68
+ OP_PUBLISH,
69
+ OP_READ,
70
+ OP_RESPONSE,
71
+ RX_CHAR_UUID,
72
+ SERVICE_UUID,
73
+ TX_CHAR_UUID,
74
+ )
75
+ from .crypto import (
76
+ SesameCipher,
77
+ derive_device_secret,
78
+ derive_session_token_key,
79
+ generate_ecc_keypair,
80
+ )
81
+ from .device import (
82
+ BaseKeypad,
83
+ SesameBikeLock,
84
+ SesameBot,
85
+ SesameDevice,
86
+ SesameKeypad,
87
+ SesameLock,
88
+ SesameOpenSensor,
89
+ SesameSegmentLayer,
90
+ create_sesame_device,
91
+ find_sesame_device,
92
+ scan_sesame_devices,
93
+ )
94
+ from .exceptions import (
95
+ SesameAuthenticationError,
96
+ SesameCommandError,
97
+ SesameConnectionError,
98
+ SesameError,
99
+ SesameKeyError,
100
+ SesameRegistrationError,
101
+ )
102
+ from .models import (
103
+ FACE_KEYPAD_MODELS,
104
+ KeypadMechStatus,
105
+ ProductModels,
106
+ SesameAdData,
107
+ SesameMechStatus,
108
+ calculate_battery_percentage,
109
+ get_sesame_mfg_data,
110
+ is_bike_lock_model,
111
+ is_bot_model,
112
+ is_face_keypad_model,
113
+ is_keypad_model,
114
+ is_lock_model,
115
+ is_open_sensor_model,
116
+ )
117
+ from .parser import SesameQRCode
118
+
119
+ __all__ = [
120
+ "COMPANY_ID",
121
+ "COMPANY_IDS",
122
+ "FACE_KEYPAD_MODELS",
123
+ "ITEM_ADD_SESAME",
124
+ "ITEM_AUTOLOCK",
125
+ "ITEM_CARD_ADD",
126
+ "ITEM_CARD_CHANGE",
127
+ "ITEM_CARD_DELETE",
128
+ "ITEM_CARD_FIRST",
129
+ "ITEM_CARD_GET",
130
+ "ITEM_CARD_LAST",
131
+ "ITEM_CARD_MODE_SET",
132
+ "ITEM_CARD_NOTIFY",
133
+ "ITEM_CARD_VERIFY_TO_CLOUD",
134
+ "ITEM_DOOR_CLOSED",
135
+ "ITEM_DOOR_OPEN",
136
+ "ITEM_ENABLE_DFU",
137
+ "ITEM_FACE_CHANGE",
138
+ "ITEM_FACE_DELETE",
139
+ "ITEM_FACE_FIRST",
140
+ "ITEM_FACE_GET",
141
+ "ITEM_FACE_LAST",
142
+ "ITEM_FACE_MODE_SET",
143
+ "ITEM_FACE_NOTIFY",
144
+ "ITEM_FINGER_CHANGE",
145
+ "ITEM_FINGER_DELETE",
146
+ "ITEM_FINGER_FIRST",
147
+ "ITEM_FINGER_GET",
148
+ "ITEM_FINGER_LAST",
149
+ "ITEM_FINGER_MODE_SET",
150
+ "ITEM_FINGER_NOTIFY",
151
+ "ITEM_HISTORY",
152
+ "ITEM_HISTORY_DELETE",
153
+ "ITEM_INITIAL",
154
+ "ITEM_KEYPAD_LOCK_LIST",
155
+ "ITEM_LOCK",
156
+ "ITEM_LOGIN",
157
+ "ITEM_MAGNET",
158
+ "ITEM_MECH_SETTING",
159
+ "ITEM_MECH_STATUS",
160
+ "ITEM_OPS_TIMER_SETTING",
161
+ "ITEM_PALM_CHANGE",
162
+ "ITEM_PALM_DELETE",
163
+ "ITEM_PALM_FIRST",
164
+ "ITEM_PALM_GET",
165
+ "ITEM_PALM_LAST",
166
+ "ITEM_PALM_MODE_SET",
167
+ "ITEM_PALM_NOTIFY",
168
+ "ITEM_PASSCODE_ADD",
169
+ "ITEM_PASSCODE_CHANGE",
170
+ "ITEM_PASSCODE_DELETE",
171
+ "ITEM_PASSCODE_FIRST",
172
+ "ITEM_PASSCODE_GET",
173
+ "ITEM_PASSCODE_LAST",
174
+ "ITEM_PASSCODE_MODE_SET",
175
+ "ITEM_PASSCODE_NOTIFY",
176
+ "ITEM_PASSCODE_VERIFY_TO_CLOUD",
177
+ "ITEM_REGISTRATION",
178
+ "ITEM_REMOVE_SESAME",
179
+ "ITEM_TIME",
180
+ "ITEM_UNLOCK",
181
+ "ITEM_VERSION_TAG",
182
+ "MTU_SIZE",
183
+ "OP_CREATE",
184
+ "OP_PUBLISH",
185
+ "OP_READ",
186
+ "OP_RESPONSE",
187
+ "RX_CHAR_UUID",
188
+ "SERVICE_UUID",
189
+ "TX_CHAR_UUID",
190
+ "BaseKeypad",
191
+ "KeypadMechStatus",
192
+ "ProductModels",
193
+ "SesameAdData",
194
+ "SesameAuthenticationError",
195
+ "SesameBikeLock",
196
+ "SesameBot",
197
+ "SesameCipher",
198
+ "SesameCommandError",
199
+ "SesameConnectionError",
200
+ "SesameDevice",
201
+ "SesameError",
202
+ "SesameKeyError",
203
+ "SesameKeypad",
204
+ "SesameLock",
205
+ "SesameMechStatus",
206
+ "SesameOpenSensor",
207
+ "SesameQRCode",
208
+ "SesameRegistrationError",
209
+ "SesameSegmentLayer",
210
+ "__version__",
211
+ "calculate_battery_percentage",
212
+ "create_sesame_device",
213
+ "derive_device_secret",
214
+ "derive_session_token_key",
215
+ "find_sesame_device",
216
+ "generate_ecc_keypair",
217
+ "get_sesame_mfg_data",
218
+ "is_bike_lock_model",
219
+ "is_bot_model",
220
+ "is_face_keypad_model",
221
+ "is_keypad_model",
222
+ "is_lock_model",
223
+ "is_open_sensor_model",
224
+ "scan_sesame_devices",
225
+ ]
@@ -0,0 +1,3 @@
1
+ """Version definition for sesame-ble."""
2
+
3
+ __version__ = "0.1.0"
pysesame_ble/const.py ADDED
@@ -0,0 +1,106 @@
1
+ """Constants for the sesame-ble library.
2
+
3
+ Based strictly on the official CANDY HOUSE Sesame protocol specifications:
4
+ https://github.com/CANDY-HOUSE/API_document
5
+ """
6
+
7
+ # BLE GATT Service and Characteristic UUIDs
8
+ SERVICE_UUID = "0000fd81-0000-1000-8000-00805f9b34fb"
9
+ TX_CHAR_UUID = "16860002-a5ae-9856-b6d3-dbb4c676993e"
10
+ RX_CHAR_UUID = "16860003-a5ae-9856-b6d3-dbb4c676993e"
11
+
12
+ # BLE Manufacturer / Company Identifiers
13
+ COMPANY_ID = 0x055A
14
+ COMPANY_IDS = (0x055A, 0x05A7, 0x05A5, 0x053A)
15
+
16
+ # Packet Segmentation
17
+ MTU_SIZE = 20
18
+
19
+ # Protocol Operation Codes
20
+ OP_CREATE = 0x01
21
+ OP_READ = 0x02
22
+ OP_UPDATE = 0x03
23
+ OP_DELETE = 0x04
24
+ OP_ASYNC = 0x05
25
+ OP_RESPONSE = 0x07
26
+ OP_PUBLISH = 0x08
27
+
28
+ # Protocol Item Codes - Common & Locks
29
+ ITEM_REGISTRATION = 1
30
+ ITEM_LOGIN = 2
31
+ ITEM_HISTORY = 4
32
+ ITEM_VERSION_TAG = 5
33
+ ITEM_ENABLE_DFU = 7
34
+ ITEM_TIME = 8
35
+ ITEM_AUTOLOCK = 11
36
+ ITEM_INITIAL = 14
37
+ ITEM_MAGNET = 17
38
+ ITEM_HISTORY_DELETE = 18
39
+ ITEM_MECH_SETTING = 80
40
+ ITEM_MECH_STATUS = 81
41
+ ITEM_LOCK = 82
42
+ ITEM_UNLOCK = 83
43
+
44
+ # OpenSensor Item Codes
45
+ ITEM_DOOR_OPEN = 90
46
+ ITEM_DOOR_CLOSED = 91
47
+ ITEM_OPS_TIMER_SETTING = 92
48
+
49
+ # Keypad Lock Pairing Item Codes
50
+ ITEM_ADD_SESAME = 101
51
+ ITEM_KEYPAD_LOCK_LIST = 102
52
+ ITEM_REMOVE_SESAME = 103
53
+
54
+ # Touch Keypad Card Item Codes
55
+ ITEM_CARD_CHANGE = 107
56
+ ITEM_CARD_DELETE = 108
57
+ ITEM_CARD_GET = 109
58
+ ITEM_CARD_NOTIFY = 110
59
+ ITEM_CARD_LAST = 111
60
+ ITEM_CARD_FIRST = 112
61
+ ITEM_CARD_MODE_SET = 114
62
+ ITEM_CARD_ADD = 140
63
+ ITEM_CARD_VERIFY_TO_CLOUD = 203
64
+
65
+ # Touch Keypad Passcode Item Codes
66
+ ITEM_PASSCODE_CHANGE = 123
67
+ ITEM_PASSCODE_DELETE = 124
68
+ ITEM_PASSCODE_GET = 125
69
+ ITEM_PASSCODE_NOTIFY = 126
70
+ ITEM_PASSCODE_LAST = 127
71
+ ITEM_PASSCODE_FIRST = 128
72
+ ITEM_PASSCODE_MODE_GET = 129
73
+ ITEM_PASSCODE_MODE_SET = 130
74
+ ITEM_PASSCODE_ADD = 138
75
+ ITEM_PASSCODE_VERIFY_TO_CLOUD = 151
76
+
77
+ # Touch Keypad Fingerprint Item Codes
78
+ ITEM_FINGER_CHANGE = 115
79
+ ITEM_FINGER_DELETE = 116
80
+ ITEM_FINGER_GET = 117
81
+ ITEM_FINGER_NOTIFY = 118
82
+ ITEM_FINGER_LAST = 119
83
+ ITEM_FINGER_FIRST = 120
84
+ ITEM_FINGER_MODE_SET = 122
85
+
86
+ # Biometric Keypad Face Item Codes
87
+ ITEM_FACE_CHANGE = 154
88
+ ITEM_FACE_DELETE = 155
89
+ ITEM_FACE_GET = 156
90
+ ITEM_FACE_NOTIFY = 157
91
+ ITEM_FACE_LAST = 158
92
+ ITEM_FACE_FIRST = 159
93
+ ITEM_FACE_MODE_GET = 160
94
+ ITEM_FACE_MODE_SET = 161
95
+ ITEM_FACE_MODE_DELETE_NOTIFY = 192
96
+
97
+ # Biometric Keypad Palm Item Codes
98
+ ITEM_PALM_CHANGE = 162
99
+ ITEM_PALM_DELETE = 163
100
+ ITEM_PALM_GET = 164
101
+ ITEM_PALM_NOTIFY = 165
102
+ ITEM_PALM_LAST = 166
103
+ ITEM_PALM_FIRST = 167
104
+ ITEM_PALM_MODE_GET = 168
105
+ ITEM_PALM_MODE_SET = 169
106
+ ITEM_PALM_MODE_DELETE_NOTIFY = 193
pysesame_ble/crypto.py ADDED
@@ -0,0 +1,100 @@
1
+ """Cryptographic functions for the Sesame OS3 BLE protocol.
2
+
3
+ Implements ECDH P-256 key agreement, AES-CMAC session key derivation,
4
+ and AES-CCM message encryption/decryption as defined in the official docs:
5
+ https://github.com/CANDY-HOUSE/API_document/blob/main/SesameOS3/bluetooth.md
6
+ """
7
+
8
+ import logging
9
+
10
+ from cryptography.hazmat.primitives import cmac
11
+ from cryptography.hazmat.primitives.asymmetric import ec
12
+ from cryptography.hazmat.primitives.ciphers import algorithms
13
+ from cryptography.hazmat.primitives.ciphers.aead import AESCCM
14
+ from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
15
+
16
+ from .exceptions import SesameAuthenticationError
17
+
18
+ logger = logging.getLogger(__name__)
19
+
20
+
21
+ class SesameCipher:
22
+ """Manages secure communication using AES-CCM for a Sesame BLE session."""
23
+
24
+ def __init__(self, session_token: bytes, session_key: bytes) -> None:
25
+ """Initialize the cipher with the session token and derived key.
26
+
27
+ Args:
28
+ session_token: 4-byte session token (random code).
29
+ session_key: 16-byte session key (Token derived via AES-CMAC).
30
+ """
31
+ self._token = session_token
32
+ self._encrypt_seq = 0
33
+ self._decrypt_seq = 0
34
+ self._aesccm = AESCCM(session_key, tag_length=4)
35
+
36
+ def _build_nonce(self, counter: int) -> bytes:
37
+ """Constructs the 13-byte CCM_IV: 8-byte count (LE) + 1-byte nouse (0) + 4-byte token."""
38
+ return counter.to_bytes(8, byteorder="little") + b"\x00" + self._token
39
+
40
+ def encrypt_payload(self, plaintext: bytes) -> bytes:
41
+ """Encrypts data using AES-CCM (13-byte IV, 1-byte AAD: 0x00, 4-byte MAC/tag)."""
42
+ nonce = self._build_nonce(self._encrypt_seq)
43
+ self._encrypt_seq += 1
44
+ return self._aesccm.encrypt(nonce, plaintext, b"\x00")
45
+
46
+ def decrypt_payload(self, ciphertext: bytes) -> bytes:
47
+ """Decrypts and verifies data using AES-CCM."""
48
+ nonce = self._build_nonce(self._decrypt_seq)
49
+ self._decrypt_seq += 1
50
+
51
+ try:
52
+ return self._aesccm.decrypt(nonce, ciphertext, b"\x00")
53
+ except Exception as err:
54
+ logger.error(
55
+ "Decryption failed!\n Nonce: %s\n Ciphertext: %s",
56
+ nonce.hex(),
57
+ ciphertext.hex(),
58
+ )
59
+ raise SesameAuthenticationError(f"Failed to decrypt Sesame packet: {err}") from err
60
+
61
+
62
+ def generate_ecc_keypair() -> tuple[bytes, ec.EllipticCurvePrivateKey]:
63
+ """Generates a NIST P-256 ECC key pair for Sesame registration.
64
+
65
+ Returns:
66
+ A tuple of (public_key_raw_64_bytes, private_key_object).
67
+ """
68
+ private_key = ec.generate_private_key(ec.SECP256R1())
69
+ public_bytes = private_key.public_key().public_bytes(
70
+ encoding=Encoding.X962, format=PublicFormat.UncompressedPoint
71
+ )
72
+ # Remove the 0x04 uncompressed prefix byte
73
+ return public_bytes[1:], private_key
74
+
75
+
76
+ def derive_device_secret(
77
+ device_pubkey_raw: bytes, app_privkey: ec.EllipticCurvePrivateKey
78
+ ) -> bytes:
79
+ """Derives the 16-byte device secret using ECDH.
80
+
81
+ Args:
82
+ device_pubkey_raw: Device's 64-byte uncompressed public key (no 0x04 prefix).
83
+ app_privkey: The app's private ECC key.
84
+ """
85
+ uncompressed_pub = b"\x04" + device_pubkey_raw
86
+ device_public_key = ec.EllipticCurvePublicKey.from_encoded_point(
87
+ ec.SECP256R1(), uncompressed_pub
88
+ )
89
+ shared_secret = app_privkey.exchange(ec.ECDH(), device_public_key)
90
+ return shared_secret[:16]
91
+
92
+
93
+ def derive_session_token_key(device_secret: bytes, session_token: bytes) -> bytes:
94
+ """Derives the 16-byte session key (Token) by signing the random code using AES-CMAC.
95
+
96
+ Formula: AES_CMAC(key: device_secret, input: session_token)
97
+ """
98
+ c = cmac.CMAC(algorithms.AES(device_secret))
99
+ c.update(session_token)
100
+ return c.finalize()