Fernet (symmetric encryption) — Cryptography 44.0.0.dev1 documentation (2024)

Fernet guarantees that a message encrypted using it cannot bemanipulated or read without the key. Fernet is an implementation ofsymmetric (also known as “secret key”) authenticated cryptography. Fernet alsohas support for implementing key rotation via MultiFernet.

class cryptography.fernet.Fernet(key)[source]

This class provides both encryption and decryption facilities.

>>> from cryptography.fernet import Fernet>>> key = Fernet.generate_key()>>> f = Fernet(key)>>> token = f.encrypt(b"my deep dark secret")>>> tokenb'...'>>> f.decrypt(token)b'my deep dark secret'

Parameters:

key (bytes or str) – A URL-safe base64-encoded 32-byte key. This must bekept secret. Anyone with this key is able to create andread messages.

classmethod generate_key()[source]

Generates a fresh fernet key. Keep this some place safe! If you lose ityou’ll no longer be able to decrypt messages; if anyone else gainsaccess to it, they’ll be able to decrypt all of your messages, andthey’ll also be able to forge arbitrary messages that will beauthenticated and decrypted.

encrypt(data)[source]

Encrypts data passed. The result of this encryption is known as a“Fernet token” and has strong privacy and authenticity guarantees.

Parameters:

data (bytes) – The message you would like to encrypt.

Returns bytes:

A secure message that cannot be read or alteredwithout the key. It is URL-safe base64-encoded. This isreferred to as a “Fernet token”.

Raises:

TypeError – This exception is raised if data is notbytes.

Note

The encrypted message contains the current time when it wasgenerated in plaintext, the time a message was created willtherefore be visible to a possible attacker.

See Also

Decryption: What is Decryption & How Does it Protect Your Data?

encrypt_at_time(data, current_time)[source]

Added in version 3.0.

Encrypts data passed using explicitly passed current time. Seeencrypt() for the documentation of the data parameter, thereturn type and the exceptions raised.

The motivation behind this method is for the client code to be able totest token expiration. Since this method can be used in an insecuremanner one should make sure the correct time (int(time.time()))is passed as current_time outside testing.

Parameters:

current_time (int) – The current time.

Note

Similarly to encrypt() the encrypted message contains thetimestamp in plaintext, in this case the timestamp is the valueof the current_time parameter.

decrypt(token, ttl=None)[source]

Decrypts a Fernet token. If successfully decrypted you will receive theoriginal plaintext as the result, otherwise an exception will beraised. It is safe to use this data immediately as Fernet verifiesthat the data has not been tampered with prior to returning it.

Parameters:

• token (bytes or str) – The Fernet token. This is the result ofcalling encrypt().

• ttl (int) – Optionally, the number of seconds old a message may befor it to be valid. If the message is older thanttl seconds (from the time it was originallycreated) an exception will be raised. If ttl is notprovided (or is None), the age of the message isnot considered.

Returns bytes:

The original plaintext.

Raises:

• cryptography.fernet.InvalidToken – If the token is in anyway invalid, this exceptionis raised. A token may beinvalid for a number ofreasons: it is older than thettl, it is malformed, orit does not have a validsignature.

• TypeError – This exception is raised if token is notbytes or str.

decrypt_at_time(token, ttl, current_time)[source]

Added in version 3.0.

Decrypts a token using explicitly passed current time. Seedecrypt() for the documentation of the token and ttlparameters (ttl is required here), the return type and the exceptionsraised.

The motivation behind this method is for the client code to be able totest token expiration. Since this method can be used in an insecuremanner one should make sure the correct time (int(time.time()))is passed as current_time outside testing.

Parameters:

current_time (int) – The current time.

extract_timestamp(token)[source]

Added in version 2.3.

Returns the timestamp for the token. The caller can then decide ifthe token is about to expire and, for example, issue a new token.

Parameters:

token (bytes or str) – The Fernet token. This is the result ofcalling encrypt().

Returns int:

The Unix timestamp of the token.

Raises:

• cryptography.fernet.InvalidToken – If the token’s signatureis invalid this exceptionis raised.

• TypeError – This exception is raised if token is notbytes or str.

class cryptography.fernet.MultiFernet(fernets)[source]

Added in version 0.7.

This class implements key rotation for Fernet. It takes a list ofFernet instances and implements the same API with the exceptionof one additional method: MultiFernet.rotate():

>>> from cryptography.fernet import Fernet, MultiFernet>>> key1 = Fernet(Fernet.generate_key())>>> key2 = Fernet(Fernet.generate_key())>>> f = MultiFernet([key1, key2])>>> token = f.encrypt(b"Secret message!")>>> tokenb'...'>>> f.decrypt(token)b'Secret message!'

MultiFernet performs all encryption options using the first key in thelist provided. MultiFernet attempts to decrypt tokens with each key inturn. A cryptography.fernet.InvalidToken exception is raised ifthe correct key is not found in the list provided.

Key rotation makes it easy to replace old keys. You can add your new key atthe front of the list to start encrypting new messages, and remove old keysas they are no longer needed.

Token rotation as offered by MultiFernet.rotate() is a best practiceand manner of cryptographic hygiene designed to limit damage in the event ofan undetected event and to increase the difficulty of attacks. For example,if an employee who had access to your company’s fernet keys leaves, you’llwant to generate new fernet key, rotate all of the tokens currently deployedusing that new key, and then retire the old fernet key(s) to which theemployee had access.

rotate(msg)[source]

Added in version 2.2.

Rotates a token by re-encrypting it under the MultiFernetinstance’s primary key. This preserves the timestamp that was originallysaved with the token. If a token has successfully been rotated then therotated token will be returned. If rotation fails this will raise anexception.

>>> from cryptography.fernet import Fernet, MultiFernet>>> key1 = Fernet(Fernet.generate_key())>>> key2 = Fernet(Fernet.generate_key())>>> f = MultiFernet([key1, key2])>>> token = f.encrypt(b"Secret message!")>>> tokenb'...'>>> f.decrypt(token)b'Secret message!'>>> key3 = Fernet(Fernet.generate_key())>>> f2 = MultiFernet([key3, key1, key2])>>> rotated = f2.rotate(token)>>> f2.decrypt(rotated)b'Secret message!'

Parameters:

msg (bytes or str) – The token to re-encrypt.

Returns bytes:

A secure message that cannot be read or altered withoutthe key. This is URL-safe base64-encoded. This is referred to as a“Fernet token”.

Raises:

• cryptography.fernet.InvalidToken – If a token is in anyway invalid this exception is raised.

• TypeError – This exception is raised if the msg is notbytes or str.

class cryptography.fernet.InvalidToken[source]

See Fernet.decrypt() for more information.

>>> import base64>>> import os>>> from cryptography.fernet import Fernet>>> from cryptography.hazmat.primitives import hashes>>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC>>> password = b"password">>> salt = os.urandom(16)>>> kdf = PBKDF2HMAC(...  algorithm=hashes.SHA256(),...  length=32,...  salt=salt,...  iterations=480000,... )>>> key = base64.urlsafe_b64encode(kdf.derive(password))>>> f = Fernet(key)>>> token = f.encrypt(b"Secret message!")>>> tokenb'...'>>> f.decrypt(token)b'Secret message!'