secrets — Генерация защищённых случайных чисел для управления секретами

Новая версия 3.6.

Исходный код: Lib/secrets.py

Модуль secrets используется для генерации криптографически стойких случайных чисел, пригодных для управления данными, такими как пароли, аутентификация учётных записей, маркеры безопасности и аналогичные секреты.

В частности, secrets следует использовать вместо генератора псевдослучайных чисел по умолчанию в модуле random, который предназначен для моделирования и симуляции, а не для безопасности или криптографии.

См. также

PEP 506

Случайные числа

Модуль secrets предоставляет доступ к самому надёжному источнику случайности, доступному в вашей операционной системе.

class secrets.SystemRandom: Класс для генерации случайных чисел с использованием источников наивысшего качества, предоставляемых операционной системой. Дополнительные сведения см. в random.SystemRandom.

secrets.choice(sequence): Возвращает случайно выбранный элемент из непустого последовательности.

secrets.randbelow(n): Возвращает случайное целое число в диапазоне [0, n).

secrets.randbits(k): Возвращает целое число с k случайными битами.

Генерация маркеров

Модуль secrets предоставляет функции для генерации защищённых маркеров, пригодных для таких приложений, как сброс паролей, трудноугадываемые URL-адреса и аналогичные задачи.

secrets.token_bytes([nbytes=None])

Возвращает случайную строку байтов, содержащую nbytes количество байтов. Если nbytes равно None или не указано, используется разумное значение по умолчанию.

>>> token_bytes(16)  
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'

secrets.token_hex([nbytes=None])

Возвращает случайную текстовую строку в шестнадцатеричном формате. Строка содержит nbytes случайных байтов, каждый байт преобразован в две шестнадцатеричные цифры. Если nbytes равно None или не указано, используется разумное значение по умолчанию.

>>> token_hex(16)  
'f9bf78b9a18ce6d46a0cd2b0b86df9da'

secrets.token_urlsafe([nbytes=None])

Возвращает случайную URL-безопасную текстовую строку, содержащую nbytes случайных байтов. Текст закодирован в Base64, поэтому в среднем каждый байт приводит примерно к 1,3 символам. Если nbytes равно None или не указано, используется разумное значение по умолчанию.

>>> token_urlsafe(16)  
'Drmhze6EPcv0fN_81Bj-nA'

Сколько байтов следует использовать для маркеров?

Для защиты от атак методом перебора маркерам необходимо достаточное количество случайности. К сожалению, то, что считается достаточным, обязательно увеличивается по мере того, как компьютеры становятся мощнее и могут выполнять больше попыток за меньшее время. По состоянию на 2015 год считается, что 32 байта (256 бит) случайности достаточно для типичного использования модуля secrets.

Для тех, кто хочет управлять длиной маркера самостоятельно, вы можете явно указать, сколько случайности используется для маркеров, передав аргумент int различным функциям token_*. Этот аргумент принимается как количество байтов случайности для использования.

В противном случае, если аргумент не указан или если он равен None, функции token_* вместо этого будут использовать разумное значение по умолчанию.

Примечание

Это значение по умолчанию может быть изменено в любое время, в том числе во время релизов с исправлениями.

Другие функции

secrets.compare_digest(a, b): Возвращает True если строки или объекты типа байты a и b равны, в противном случае False, используя сравнение с постоянным временем, чтобы уменьшить риск атак с использованием времени timing attacks. Дополнительные сведения см. в hmac.compare_digest().

Рецепты и рекомендации

Этот раздел демонстрирует рецепты и рекомендации по использованию secrets для обеспечения базового уровня безопасности.

Сгенерировать восьмисимвольный буквенно-цифровой пароль:

import string
import secrets
alphabet = string.ascii_letters + string.digits
password = ''.join(secrets.choice(alphabet) for i in range(8))

Примечание

Приложения не должны хранить пароли в восстановимом формате, будь то в виде простого текста или зашифрованном. Они должны быть сохранены с солью и зашифрованы с использованием криптографически стойкой односторонней (необратимой) хеш-функции.

Сгенерировать десятисимвольный буквенно-цифровой пароль с как минимум одной строчной буквой, как минимум одной заглавной буквой и как минимум тремя цифрами:

import string
import secrets
alphabet = string.ascii_letters + string.digits
while True:
    password = ''.join(secrets.choice(alphabet) for i in range(10))
    if (any(c.islower() for c in password)
            and any(c.isupper() for c in password)
            and sum(c.isdigit() for c in password) >= 3):
        break

Сгенерировать пароль в стиле XKCD:

import secrets
# On standard Linux systems, use a convenient dictionary file.
# Other platforms may need to provide their own word-list.
with open('/usr/share/dict/words') as f:
    words = [word.strip() for word in f]
    password = ' '.join(secrets.choice(words) for i in range(4))

Сгенерировать трудноугадываемый временный URL, содержащий маркер безопасности, подходящий для приложений восстановления паролей:

import secrets
url = 'https://example.com/reset=' + secrets.token_urlsafe()