secrets — Generate secure random numbers for managing secrets

Added in version 3.6.

Вихідний код: Lib/secrets.py

The secrets module is used for generating cryptographically strong random numbers suitable for managing data such as passwords, account authentication, security tokens, and related secrets.

In particular, secrets should be used in preference to the default pseudo-random number generator in the random module, which is designed for modelling and simulation, not security or cryptography.

Дивись також

PEP 506

Випадкові числа

The secrets module provides access to the most secure source of randomness that your operating system provides.

class secrets.SystemRandom

Клас для генерації випадкових чисел з використанням джерел найвищої якості, наданих операційною системою. Дивіться random.SystemRandom для отримання додаткової інформації.

secrets.choice(seq)

Return a randomly chosen element from a non-empty sequence.

secrets.randbelow(exclusive_upper_bound)

Return a random int in the range [0, exclusive_upper_bound).

secrets.randbits(k)

Return a non-negative int with k random bits.

Генерація токенів

The secrets module provides functions for generating secure tokens, suitable for applications such as password resets, hard-to-guess URLs, and similar.

secrets.token_bytes(nbytes=None)

Return a random byte string containing nbytes number of bytes.

If nbytes is not specified or None, DEFAULT_ENTROPY is used instead.

>>> token_bytes(16)
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'
secrets.token_hex(nbytes=None)

Return a random text string, in hexadecimal. The string has nbytes random bytes, each byte converted to two hex digits.

If nbytes is not specified or None, DEFAULT_ENTROPY is used instead.

>>> token_hex(16)
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
secrets.token_urlsafe(nbytes=None)

Return a random URL-safe text string, containing nbytes random bytes. The text is Base64 encoded, so on average each byte results in approximately 1.3 characters.

If nbytes is not specified or None, DEFAULT_ENTROPY is used instead.

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

Скільки байтів мають використовувати токени?

To be secure against brute-force attacks, tokens need to have sufficient randomness. Unfortunately, what is considered sufficient will necessarily increase as computers get more powerful and able to make more guesses in a shorter period. As of 2015, it is believed that 32 bytes (256 bits) of randomness is sufficient for the typical use-case expected for the secrets module.

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

Otherwise, if no argument is provided, or if the argument is None, the token_* functions uses DEFAULT_ENTROPY instead.

secrets.DEFAULT_ENTROPY

Default number of bytes of randomness used by the token_* functions.

The exact value is subject to change at any time, including during maintenance releases.

Інші функції

secrets.compare_digest(a, b)

Return True if strings or bytes-like objects a and b are equal, otherwise False, using a «constant-time compare» to reduce the risk of timing attacks. See hmac.compare_digest() for additional details.

Рецепти та найкращі практики

This section shows recipes and best practices for using secrets to manage a basic level of security.

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

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

Примітка

Applications should not store passwords in a recoverable format, whether plain text or encrypted. They should be salted and hashed using a cryptographically strong one-way (irreversible) hash function.

Згенеруйте буквено-цифровий пароль із десяти символів, який містить принаймні один символ у нижньому регістрі, принаймні один символ у верхньому регістрі та принаймні три цифри:

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()