hmac --- Băm khóa để xác thực tin nhắn

Source code: Lib/hmac.py

Mô-đun này triển khai thuật toán HMAC như được mô tả bởi RFC 2104. Giao diện cho phép sử dụng bất kỳ hàm băm nào có kích thước thông báo fixed. Đặc biệt, không thể sử dụng các chức năng đầu ra có thể mở rộng như SHAKE-128 hoặc SHAKE-256 với HMAC.

hmac.new(key, msg=None, digestmod)

Trả về một đối tượng hmac mới. key là một đối tượng byte hoặc bytearray cung cấp khóa bí mật. Nếu có msg, lệnh gọi phương thức update(msg) sẽ được thực hiện. digestmod là tên thông báo, hàm tạo thông báo hoặc mô-đun để đối tượng HMAC sử dụng. Nó có thể là bất kỳ tên nào phù hợp với hashlib.new(). Bất chấp quan điểm tranh luận của nó, nó là bắt buộc.

Thay đổi trong phiên bản 3.4: Tham số key có thể là đối tượng byte hoặc bytearray. Tham số msg có thể thuộc bất kỳ loại nào được hashlib hỗ trợ. Tham số digestmod có thể là tên của thuật toán băm.

Thay đổi trong phiên bản 3.8: Đối số digestmod hiện là bắt buộc. Chuyển nó dưới dạng đối số từ khóa để tránh sự lúng túng khi bạn không có msg ban đầu.

hmac.digest(key, msg, digest)

Trả về bản tóm tắt của msg cho key và digest bí mật đã cho. Chức năng này tương đương với HMAC(key, msg, digest).digest(), nhưng sử dụng cách triển khai nội tuyến hoặc C được tối ưu hóa, nhanh hơn đối với các tin nhắn vừa với bộ nhớ. Các tham số key, msg và digest có ý nghĩa tương tự như trong new().

Chi tiết triển khai CPython, việc triển khai C được tối ưu hóa chỉ được sử dụng khi digest là một chuỗi và tên của thuật toán tóm tắt được OpenSSL hỗ trợ.

Added in version 3.7.

class hmac.HMAC

Một đối tượng HMAC có các phương thức sau:

HMAC.update(msg)

Cập nhật đối tượng hmac bằng msg. Các cuộc gọi lặp lại tương đương với một cuộc gọi duy nhất có sự kết hợp của tất cả các đối số: m.update(a); m.update(b) tương đương với m.update(a + b).

Thay đổi trong phiên bản 3.4: Tham số msg có thể thuộc bất kỳ loại nào được hashlib hỗ trợ.

HMAC.digest()

Trả về bản tóm tắt của các byte được truyền cho phương thức update() cho đến nay. Đối tượng byte này sẽ có cùng độ dài với digest_size của thông báo được cung cấp cho hàm tạo. Nó có thể chứa các byte không phải ASCII, bao gồm cả byte NUL.

Cảnh báo

Khi so sánh đầu ra của digest() với thông báo được cung cấp bên ngoài trong quy trình xác minh, bạn nên sử dụng hàm compare_digest() thay vì toán tử == để giảm lỗ hổng trước các cuộc tấn công tính thời gian.

HMAC.hexdigest()

Giống như digest() ngoại trừ thông báo được trả về dưới dạng một chuỗi có độ dài gấp đôi chỉ chứa các chữ số thập lục phân. Điều này có thể được sử dụng để trao đổi giá trị một cách an toàn trong email hoặc các môi trường phi nhị phân khác.

Cảnh báo

Khi so sánh đầu ra của hexdigest() với thông báo được cung cấp bên ngoài trong quy trình xác minh, bạn nên sử dụng hàm compare_digest() thay vì toán tử == để giảm lỗ hổng trước các cuộc tấn công tính thời gian.

HMAC.copy()

Trả về một bản sao ("bản sao") của đối tượng hmac. Điều này có thể được sử dụng để tính toán hiệu quả các chuỗi có chung chuỗi con ban đầu.

Một đối tượng băm có các thuộc tính sau:

HMAC.digest_size

Kích thước của thông báo HMAC thu được tính bằng byte.

HMAC.block_size

Kích thước khối bên trong của thuật toán băm tính bằng byte.

Added in version 3.4.

HMAC.name

Tên chuẩn của HMAC này, luôn là chữ thường, ví dụ: hmac-md5.

Added in version 3.4.

Thay đổi trong phiên bản 3.10: Đã xóa các thuộc tính không có giấy tờ HMAC.digest_cons, HMAC.inner và HMAC.outer.

Mô-đun này cũng cung cấp chức năng trợ giúp sau:

hmac.compare_digest(a, b)

Trả về a == b. Chức năng này sử dụng một phương pháp được thiết kế để ngăn chặn việc phân tích thời gian bằng cách tránh hành vi đoản mạch dựa trên nội dung, làm cho nó phù hợp với mật mã. a và b đều phải cùng loại: str (chỉ ASCII, ví dụ: được trả về bởi HMAC.hexdigest()) hoặc bytes-like object.

Ghi chú

Nếu a và b có độ dài khác nhau hoặc nếu xảy ra lỗi thì về mặt lý thuyết, một cuộc tấn công tính thời gian có thể tiết lộ thông tin về loại và độ dài của a và b—nhưng không tiết lộ giá trị của chúng.

Added in version 3.3.

Thay đổi trong phiên bản 3.10: Chức năng này sử dụng CRYPTO_memcmp() của OpenSSL trong nội bộ khi khả dụng.

Xem thêm

Mô-đun hashlib

Mô-đun Python cung cấp các hàm băm an toàn.