DOCSEARCHbyAlgolia
Submit Docs

PyCryptodome Documentation

repository·master·Indexed 25 days ago

https://github.com/legrandin/pycryptodome

A self-contained Python package providing low-level cryptographic primitives. A fork of PyCrypto, it includes modern algorithms and improved performance across several sub-packages: Crypto.Cipher for confidentiality (AES, ChaCha20-Poly1305), Crypto.Signature for authenticity, Crypto.Hash for digests and HMAC, Crypto.PublicKey for RSA and ECC, Crypto.Protocol for secure communications, Crypto.IO for encodings, Crypto.Random for random data, and Crypto.Util for general purpose routines.

Tokens
42K
Snippets
111
Records
227
Agent score
84%

What's inside PyCryptodome

  1. Overview of PyCryptodome sub-packages

    master

    PyCryptodome organizes its cryptographic functionalities into specialized sub-packages. Each package is dedicated to a specific class of cryptographic problems:

    • Crypto.Cipher: Modules for protecting confidentiality (e.g., AES, GCM).
    • Crypto.Signature: Modules for assuring authenticity via digital signatures (e.g., PKCS#1 v1.5).
    • Crypto.Hash: Modules for creating cryptographic digests (e.g., SHA-256) and Message Authentication Codes like HMAC.
    • Crypto.PublicKey: Modules for generating, exporting, or importing public keys (e.g., RSA, ECC).
    • Crypto.Protocol: Modules for facilitating secure communications between parties (e.g., Shamir's Secret Sharing).
    • Crypto.IO: Modules for handling common cryptographic encodings (e.g., PEM).
    • Crypto.Random: Modules for generating random data.
    • Crypto.Util: General purpose routines (e.g., XOR for byte strings, ASN.1).

  2. Overview of PyCryptodome cryptographic primitives

    master

    PyCryptodome provides a wide range of low-level cryptographic primitives.

    Warning: Users are expected to have a solid understanding of cryptography and security engineering. Some primitives are provided for backward compatibility only and are considered obsolete (e.g., TDES) or insecure (e.g., RC4).

    Available primitives include:

    • Symmetric Ciphers: AES, Single and Triple DES (legacy), CAST-128 (legacy), RC2 (legacy).
    • Symmetric Modes of Operation: ECB, CBC, CFB, OFB, CTR, OpenPGP (CFB variant).
    • Authenticated Encryption: CCM (AES only), EAX, GCM (AES only), SIV (AES only), OCB (AES only), ChaCha20-Poly1305.
    • Stream Ciphers: Salsa20, ChaCha20, XChaCha20, RC4 (legacy).
    • Cryptographic Hashes: SHA-1, SHA-2 (224, 256, 384, 512, 512/224, 512/256), SHA-3 (224, 256, 384, 512) and XOFs (SHAKE128, SHAKE256), Keccak, BLAKE2b, BLAKE2s, RIPE-MD160 (legacy), MD5 (legacy), and KangarooTwelve/TurboSHAKE.
    • Message Authentication Codes (MAC): HMAC, CMAC, KMAC128, KMAC256, Poly1305.
    • Asymmetric Key Generation: RSA, ECC (NIST P-curves, Ed25519, Ed448, Curve25519, Curve448), DSA, ElGamal (legacy).
    • Asymmetric Ciphers: RSA (PKCS#1) including RSAES-PKCS1-v1_5 and RSAES-OAEP.
    • Asymmetric Digital Signatures: RSA (RSASSA-PKCS1-v1_5, RSASSA-PSS), (EC)DSA (Nonce-based and Deterministic), and EdDSA.
    • Key Derivation: PBKDF2, scrypt, HKDF, PBKDF1 (legacy).
    • Other Protocols: HPKE, Shamir Secret Sharing, and Padding (PKCS#7, ISO-7816, X.923).

  4. Manage public and private keys with Crypto.PublicKey

    master

    The Crypto.PublicKey package provides tools for managing asymmetric key pairs. In these systems, a key pair consists of a confidential private key and a non-confidential public key.

    Usage Patterns:

    • Encryption: The sender uses the receiver's Public key; the receiver uses their Private key.
    • Signature: The sender uses their Private key; the receiver uses the sender's Public key.

    Key objects can be compared using == and != operators. Note that a private key and its corresponding public key are treated as two different objects during comparison.

  5. Encapsulate binary data using the PEM format

    master
    Use the Crypto.IO.PEM module to encapsulate binary cryptographic objects (such as keys and certificates) into text using the PEM (Privacy Enhanced Mail) format. Although the original RFC 1421-1424 standard for securing emails is abandoned, this module provides the widely used method for encoding binary data into a text-based format.

  6. Understand Symmetric Cipher types

    master

    Symmetric ciphers use the same key for both encryption and decryption. They are categorized into two types:

    • Stream ciphers: Encrypt data one byte at a time (e.g., chacha20, salsa20).
    • Block ciphers: Operate on fixed-size blocks of data (e.g., aes with a 128-bit/16-byte block size). Block ciphers typically require a mode of operation to handle variable amounts of data.

    Security Note: It is recommended to use primitives that provide both confidentiality and authentication (MAC), such as modern modes of operation (e.g., GCM) or stream ciphers paired with a MAC (e.g., chacha20_poly1305).

  7. Use the Crypto.IO package for cryptographic data I/O

    master

    The Crypto.IO package provides modules for reading and writing cryptographic data in various formats. It primarily includes support for:

    • PEM format: For handling Privacy Enhanced Mail (PEM) encoded data.
    • PKCS#8 format: For handling Public-Key Cryptography Standards #8 (PKCS#8) encoded data.

  8. Use ARC4 for legacy purposes

    master

    ARC4 (Alleged RC4) is a symmetric stream cipher.

    WARNING: ARC4 is not secure. It is provided in PyCryptodome for legacy purposes only. For modern applications, use chacha20_poly1305 or aes (in AEAD modes like GCM) instead.

    Key characteristics:

    • Key lengths can vary from 8 to 2048 bits.
    • It does not support a nonce or an IV natively.

  10. Understand HPKE authentication modes

    master

    HPKE (RFC 9180) supports several modes to provide different levels of authentication:

    • Basic Mode: Provides confidentiality and integrity but the receiver does not receive proof of the sender's identity.
    • Auth Mode: The sender contributes their own private key to the encryption. The receiver must possess the matching public key to verify the sender's identity.
    • PSK Mode: The sender and receiver use a pre-shared secret key (at least 32 random bytes) contributed to both encryption and decryption.
    • AuthPSK Mode: Combines both the sender's private key (Auth) and a pre-shared secret (PSK) for enhanced authentication.

  11. Use cSHAKE256 for extendable-output hashing

    master

    cSHAKE256 is an extendable-output function (XOF) from the SHA-3 family (specified in NIST SP 800-185). Unlike standard hash functions that produce fixed-length digests, cSHAKE256 can produce digests of any requested length and can function as a Pseudo Random Generator (PRG). The output bits do not depend on the requested output length.

    To use cSHAKE256, use Crypto.Hash.cSHAKE256.new(). You can provide a custom parameter to allow for domain separation. Using different customization strings ensures that different applications using the same input data will produce different digests.

  12. Use DES for legacy encryption

    master

    DES (Data Encryption Standard) is a symmetric block cipher with a fixed data block size of 8 bytes.

    Warning: This module is provided for legacy purposes only. For all new applications, use AES instead. DES is considered insecure by modern standards because its effective key length is only 56 bits, making it vulnerable to brute-force attacks.