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, используя сравнение с «постоянным временем», чтобы уменьшить риск атак с использованием времени. Дополнительные сведения см. в 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()