secrets — Generate secure random numbers for managing secrets

Added in version 3.6.

Source code:Lib/secrets.py

Thesecrets module is used for generating cryptographically strongrandom numbers suitable for managing data such as passwords, accountauthentication, security tokens, and related secrets.

In particular,secrets should be used in preference to thedefault pseudo-random number generator in therandom module, whichis designed for modelling and simulation, not security or cryptography.

Δείτε επίσης

PEP 506

Random numbers

Thesecrets module provides access to the most secure source ofrandomness that your operating system provides.

classsecrets.SystemRandom

A class for generating random numbers using the highest-qualitysources provided by the operating system. Seerandom.SystemRandom for additional details.

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 withk random bits.

Generating tokens

Thesecrets module provides functions for generating securetokens, suitable for applications such as password resets,hard-to-guess URLs, and similar.

secrets.token_bytes([nbytes=None])

Return a random byte string containingnbytes number of bytes.Ifnbytes isNone or not supplied, a reasonable default isused.

>>>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 hasnbytesrandom bytes, each byte converted to two hex digits. Ifnbytes isNone or not supplied, a reasonable default is used.

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

Return a random URL-safe text string, containingnbytes randombytes. The text is Base64 encoded, so on average each byte resultsin approximately 1.3 characters. Ifnbytes isNone or notsupplied, a reasonable default is used.

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

How many bytes should tokens use?

To be secure againstbrute-force attacks,tokens need to have sufficient randomness. Unfortunately, what isconsidered sufficient will necessarily increase as computers get morepowerful 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 forthe typical use-case expected for thesecrets module.

For those who want to manage their own token length, you can explicitlyspecify how much randomness is used for tokens by giving anintargument to the varioustoken_* functions. That argument is takenas the number of bytes of randomness to use.

Otherwise, if no argument is provided, or if the argument isNone,thetoken_* functions will use a reasonable default instead.

Σημείωση

That default is subject to change at any time, including duringmaintenance releases.

Other functions

secrets.compare_digest(a,b)

ReturnTrue if strings orbytes-like objectsa andb are equal, otherwiseFalse,using a «constant-time compare» to reduce the risk oftiming attacks.Seehmac.compare_digest() for additional details.

Recipes and best practices

This section shows recipes and best practices for usingsecretsto manage a basic level of security.

Generate an eight-character alphanumeric password:

importstringimportsecretsalphabet=string.ascii_letters+string.digitspassword=''.join(secrets.choice(alphabet)foriinrange(8))

Σημείωση

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

Generate a ten-character alphanumeric password with at least onelowercase character, at least one uppercase character, and at leastthree digits:

importstringimportsecretsalphabet=string.ascii_letters+string.digitswhileTrue:password=''.join(secrets.choice(alphabet)foriinrange(10))if(any(c.islower()forcinpassword)andany(c.isupper()forcinpassword)andsum(c.isdigit()forcinpassword)>=3):break

Generate anXKCD-style passphrase:

importsecrets# On standard Linux systems, use a convenient dictionary file.# Other platforms may need to provide their own word-list.withopen('/usr/share/dict/words')asf:words=[word.strip()forwordinf]password=' '.join(secrets.choice(words)foriinrange(4))

Generate a hard-to-guess temporary URL containing a security tokensuitable for password recovery applications:

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