tessl/pypi-pycryptodome

PyCryptodome is a self-contained Python package of low-level cryptographic primitives

—

Pending

Overview

Eval results

Files

Symmetric Encryption

Name: tessl/pypi-pycryptodome
Author: tessl

Comprehensive symmetric encryption capabilities including block ciphers and stream ciphers with support for multiple modes of operation. PyCryptodome provides modern algorithms like AES and ChaCha20 alongside legacy algorithms for compatibility.

Capabilities

AES (Advanced Encryption Standard)

The most widely used symmetric encryption algorithm, supporting 128, 192, and 256-bit keys with multiple modes of operation including authenticated encryption modes.

def new(key, mode, *args, **kwargs):
    """
    Create a new AES cipher object.
    
    Parameters:
    - key (bytes): The secret key (16, 24, or 32 bytes for AES-128/192/256)
    - mode (int): Cipher mode (MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR, 
                  MODE_GCM, MODE_CCM, MODE_EAX, MODE_SIV, MODE_OCB, MODE_KW, MODE_KWP)
    - iv (bytes): Initialization vector for modes that require it
    - nonce (bytes): Number used once for authenticated modes
    
    Returns:
    AES cipher object with encrypt/decrypt methods
    """

# Mode constants
MODE_ECB: int  # Electronic Codebook
MODE_CBC: int  # Cipher Block Chaining  
MODE_CFB: int  # Cipher Feedback
MODE_OFB: int  # Output Feedback
MODE_CTR: int  # Counter Mode
MODE_GCM: int  # Galois/Counter Mode (authenticated)
MODE_CCM: int  # Counter with CBC-MAC (authenticated)  
MODE_EAX: int  # EAX mode (authenticated)
MODE_SIV: int  # Synthetic IV (authenticated)
MODE_OCB: int  # Offset Codebook (authenticated)
MODE_KW: int   # Key Wrap
MODE_KWP: int  # Key Wrap with Padding

block_size: int  # AES block size (16 bytes)
key_size: tuple  # Valid key sizes (16, 24, 32)

Usage example:

from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
from Crypto.Util.Padding import pad, unpad

# Generate a random 256-bit key
key = get_random_bytes(32)

# Encrypt with CBC mode
cipher = AES.new(key, AES.MODE_CBC)
plaintext = b"This is a secret message"
padded = pad(plaintext, AES.block_size)
ciphertext = cipher.encrypt(padded)

# Decrypt
decipher = AES.new(key, AES.MODE_CBC, cipher.iv)
decrypted_padded = decipher.decrypt(ciphertext)
decrypted = unpad(decrypted_padded, AES.block_size)

# Authenticated encryption with GCM
cipher = AES.new(key, AES.MODE_GCM)
ciphertext, tag = cipher.encrypt_and_digest(plaintext)

ChaCha20

Modern stream cipher providing high performance and security, designed as an alternative to AES for applications requiring fast software implementation.

def new(**kwargs):
    """
    Create a new ChaCha20 cipher object.
    
    Parameters:
    - key (bytes): 32-byte secret key
    - nonce (bytes): 8 or 12-byte nonce (default: random)
    
    Returns:
    ChaCha20 cipher object
    """

class ChaCha20Cipher:
    def encrypt(self, plaintext: bytes) -> bytes: ...
    def decrypt(self, ciphertext: bytes) -> bytes: ...
    
    nonce: bytes  # The nonce used
    key_size: int  # Key size (32 bytes)

ChaCha20-Poly1305

Authenticated encryption combining ChaCha20 stream cipher with Poly1305 message authentication code, providing both confidentiality and authenticity.

def new(**kwargs):
    """
    Create a new ChaCha20-Poly1305 AEAD cipher.
    
    Parameters:
    - key (bytes): 32-byte secret key
    - nonce (bytes): 8 or 12-byte nonce
    
    Returns:
    ChaCha20-Poly1305 cipher object with encrypt_and_digest/decrypt_and_verify
    """

Salsa20

High-speed stream cipher designed for software implementations, predecessor to ChaCha20 with similar performance characteristics.

def new(key, nonce=None):
    """
    Create a new Salsa20 cipher object.
    
    Parameters:
    - key (bytes): 16 or 32-byte secret key
    - nonce (bytes): 8-byte nonce (default: random)
    
    Returns:
    Salsa20 cipher object
    """

Block Ciphers

Additional block cipher algorithms for legacy compatibility and specialized use cases.

# DES3 (Triple DES)
def DES3.new(key, mode, *args, **kwargs):
    """
    Create Triple DES cipher.
    
    Parameters:
    - key (bytes): 16 or 24-byte key (2DES or 3DES)
    - mode (int): Cipher mode
    """

def DES3.adjust_key_parity(key_in):
    """Adjust DES key parity bits."""

# Blowfish  
def Blowfish.new(key, mode, *args, **kwargs):
    """
    Create Blowfish cipher.
    
    Parameters:
    - key (bytes): Variable length key (4-56 bytes)
    - mode (int): Cipher mode
    """

# CAST-128
def CAST.new(key, mode, *args, **kwargs):
    """Create CAST cipher with variable key length."""

# ARC2 (RC2)
def ARC2.new(key, mode, *args, **kwargs):
    """Create ARC2 cipher with effective key length control."""

# DES (legacy)
def DES.new(key, mode, *args, **kwargs):
    """Create DES cipher (64-bit key, 56-bit effective)."""

Stream Ciphers

# ARC4 (RC4) - legacy stream cipher
def ARC4.new(key, *args, **kwargs):
    """
    Create ARC4 stream cipher.
    
    Parameters:
    - key (bytes): Variable length key
    
    Returns:
    ARC4 cipher object
    """

RSA Encryption

Public key encryption using RSA with OAEP or PKCS#1 v1.5 padding schemes.

# RSA-OAEP (recommended)
def PKCS1_OAEP.new(key, hashAlgo=None, mgfunc=None, label=b'', randfunc=None):
    """
    Create RSA-OAEP cipher for public key encryption.
    
    Parameters:
    - key: RSA key object (public or private)
    - hashAlgo: Hash algorithm for OAEP (default: SHA-1)
    - mgfunc: Mask generation function
    - label (bytes): Optional label
    
    Returns: 
    PKCS1OAEP_Cipher with encrypt/decrypt methods
    """

# RSA PKCS#1 v1.5 (legacy)
def PKCS1_v1_5.new(key, randfunc=None):
    """Create RSA PKCS#1 v1.5 cipher."""

Cipher Mode Patterns

All block ciphers follow consistent patterns for mode usage:

Basic Modes (ECB, CBC, CFB, OFB):

cipher = Algorithm.new(key, mode, iv)  # IV required except ECB
ciphertext = cipher.encrypt(plaintext)

Counter Mode (CTR):

cipher = Algorithm.new(key, Algorithm.MODE_CTR, nonce=nonce)
ciphertext = cipher.encrypt(plaintext)

Authenticated Modes (GCM, CCM, EAX, OCB, SIV):

cipher = Algorithm.new(key, mode)
cipher.update(associated_data)  # Optional additional authenticated data
ciphertext, tag = cipher.encrypt_and_digest(plaintext)

# Decryption with verification
cipher = Algorithm.new(key, mode, nonce=nonce)
cipher.update(associated_data)
plaintext = cipher.decrypt_and_verify(ciphertext, tag)