Aspose.Cells FOSS
Python
Encryption

Encryption — Aspose.Cells FOSS for Python API Reference

aspose-cells-foss supports AES encryption and decryption of XLSX files via the module-level functions encrypt_xlsx and decrypt_xlsx. Two parameter classes configure the cipher algorithm, hash algorithm, and PBKDF2 spin count. The recommended default is AgileEncryptionParameters with AES-256 and SHA-512.

Package: aspose.cells_foss

from aspose.cells_foss import (
    CipherAlgorithm, HashAlgorithm,
    AgileEncryptionParameters, StandardEncryptionParameters,
    encrypt_xlsx, decrypt_xlsx, get_default_encryption_params,
)

CipherAlgorithm

CipherAlgorithm is an IntEnum specifying the AES key length. All variants use AES in CBC mode with a 16-byte block size.

MemberKey bitsalg_id
AES_128128—
AES_192192—
AES_256256—

Properties

PropertyTypeDescription
algorithm_namestrAlways "AES".
key_bitsintAES key length in bits (128, 192, or 256).
alg_idintNumeric algorithm identifier used in the OOXML encryption record.
key_bytesintKey length in bytes (key_bits // 8).
block_sizeintAlways 16 (AES block size in bytes).

HashAlgorithm

HashAlgorithm is an IntEnum specifying the hash function used for PBKDF2 key derivation.

MemberHash bytesalg_id
SHA120—
SHA25632—
SHA38448—
SHA51264—

Properties

PropertyTypeDescription
algorithm_namestrHash function name (e.g., "SHA-512").
hash_bytesintDigest length in bytes.
alg_idintNumeric algorithm identifier used in the OOXML encryption record.

AgileEncryptionParameters

AgileEncryptionParameters configures the Agile Encryption scheme (ECMA-376, part 4), which is the default and recommended format for modern Excel files (Excel 2010+).

Constructor 

AgileEncryptionParameters(
    cipher_algorithm=CipherAlgorithm.AES_256,
    hash_algorithm=HashAlgorithm.SHA512,
    spin_count=100000
)
ParameterTypeDefaultDescription
cipher_algorithmCipherAlgorithmAES_256AES key length to use.
hash_algorithmHashAlgorithmSHA512Hash function for PBKDF2 key derivation.
spin_countint100000Number of PBKDF2 iterations. Higher values increase brute-force resistance at the cost of open/save time.

Properties

PropertyTypeDescription
encryption_typestrAlways "agile".
cipher_algorithmCipherAlgorithmConfigured cipher.
hash_algorithmHashAlgorithmConfigured hash function.
spin_countintPBKDF2 iteration count.
salt_sizeintSalt length in bytes (derived from cipher block size).
block_sizeintCipher block size in bytes (always 16 for AES).
key_bitsintKey length in bits.

StandardEncryptionParameters

StandardEncryptionParameters configures the Standard Encryption scheme for compatibility with Excel 2007. Prefer AgileEncryptionParameters for new files.

Constructor 

StandardEncryptionParameters(
    cipher_algorithm=CipherAlgorithm.AES_128,
    hash_algorithm=HashAlgorithm.SHA1,
    spin_count=50000
)

The properties mirror those of AgileEncryptionParameters. The encryption_type property is "standard".

Module Functions

encrypt_xlsx 

encrypt_xlsx(
    input_path: str,
    output_path: str,
    password: str,
    encryption_params=None
) -> None

Reads the XLSX file at input_path, encrypts it with password using the specified encryption_params, and writes the encrypted file to output_path.

ParameterTypeDescription
input_pathstrPath to the source XLSX file.
output_pathstrDestination path for the encrypted file. May be the same as input_path for in-place encryption.
passwordstrEncryption password.
encryption_paramsAgileEncryptionParameters | StandardEncryptionParameters | NoneEncryption configuration. When None, get_default_encryption_params() is used (AES-256/SHA-512, 100000 iterations).

decrypt_xlsx 

decrypt_xlsx(
    input_path: str,
    output_path: str,
    password: str
) -> bool

Decrypts the XLSX file at input_path using password and writes the plaintext XLSX to output_path. Returns True if decryption succeeded, False if the password was incorrect or the file was not encrypted.

get_default_encryption_params 

get_default_encryption_params() -> AgileEncryptionParameters

Returns an AgileEncryptionParameters instance configured with AES_256, SHA512, and spin_count=100000. Use this to inspect or clone the library defaults before customizing.

Examples

Encrypt a Workbook 

from aspose.cells_foss import Workbook, encrypt_xlsx, AgileEncryptionParameters, CipherAlgorithm, HashAlgorithm

# 1. Build and save an unencrypted workbook
wb = Workbook()
ws = wb.worksheets[0]
ws.cells["A1"].put_value("Confidential data")
wb.save("report.xlsx")

# 2. Encrypt with default AES-256/SHA-512 settings
encrypt_xlsx("report.xlsx", "report_secure.xlsx", password="MyP@ssw0rd!")

# 3. Alternatively, use a lower spin count for faster open/save cycles during development
params = AgileEncryptionParameters(
    cipher_algorithm=CipherAlgorithm.AES_256,
    hash_algorithm=HashAlgorithm.SHA256,
    spin_count=10000,
)
encrypt_xlsx("report.xlsx", "report_dev.xlsx", password="dev_only", encryption_params=params)

Decrypt a Workbook 

from aspose.cells_foss import decrypt_xlsx, Workbook

success = decrypt_xlsx("report_secure.xlsx", "report_decrypted.xlsx", password="MyP@ssw0rd!")

if success:
    wb = Workbook("report_decrypted.xlsx")
    print(wb.worksheets[0].cells["A1"].value)
else:
    print("Incorrect password or file is not encrypted.")

Open an Encrypted File Directly

The Workbook constructor also accepts a password parameter to open encrypted files without a separate decryption step:

from aspose.cells_foss import Workbook

wb = Workbook("report_secure.xlsx", password="MyP@ssw0rd!")
print(wb.worksheets[0].cells["A1"].value)
wb.save("report_updated_secure.xlsx", password="MyP@ssw0rd!")

See Also