{"id":8628,"library":"securetar","title":"SecureTar","description":"SecureTar is a Python library designed for handling encrypted tarfile backups. It acts as a streaming wrapper around Python's standard `tarfile` module, providing robust encryption capabilities. The library is actively maintained with frequent updates, often introducing significant breaking changes related to its file format and API, notably driven by advancements in cryptographic standards and its use in projects like Home Assistant.","status":"active","version":"2026.4.1","language":"en","source_language":"en","source_url":"https://github.com/pvizeli/securetar","tags":["encryption","backup","tarfile","security","cryptography","home-assistant"],"install":[{"cmd":"pip install securetar","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides modern cryptographic primitives (XChaCha20-Poly1305) for SecureTar v3, though not a direct PyPI dependency, it's essential for utilizing the latest encryption features.","package":"PyNaCl","optional":true}],"imports":[{"note":"Primary class for creating and reading secure tar archives.","symbol":"SecureTarFile","correct":"from securetar import SecureTarFile"},{"note":"Helper function for adding contents to a SecureTarFile in an atomic manner.","symbol":"atomic_contents_add","correct":"from securetar import atomic_contents_add"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom securetar import SecureTarFile, atomic_contents_add\n\n# Create a dummy file for backup\ndummy_file_path = Path(\"my_data.txt\")\ndummy_file_path.write_text(\"This is some sensitive data.\")\n\n# Define backup path and a password\nbackup_file_path = Path(\"my_secure_backup.tar\")\nbackup_password = os.environ.get('SECURETAR_PASSWORD', 'a_very_secret_password_123')\n\nprint(f\"Creating secure backup to {backup_file_path}...\")\n\n# Create a secure tar archive\nwith SecureTarFile(backup_file_path, 'w', password=backup_password) as tar_file:\n    atomic_contents_add(tar_file, dummy_file_path, arcname=dummy_file_path.name)\n\nprint(f\"Backup created: {backup_file_path}\")\n\n# Verify by attempting to read it\nprint(f\"Attempting to read from {backup_file_path}...\")\ntry:\n    with SecureTarFile(backup_file_path, 'r', password=backup_password) as tar_file:\n        members = tar_file.getnames()\n        print(f\"Contents of backup: {members}\")\n        # Example of extracting a file\n        extracted_path = Path(\"extracted_data.txt\")\n        tar_file.extract(dummy_file_path.name, path=\".\")\n        print(f\"Extracted '{dummy_file_path.name}' to '{extracted_path}'\")\n        extracted_path.unlink() # Clean up\nexcept Exception as e:\n    print(f\"Error reading backup: {e}\")\nfinally:\n    dummy_file_path.unlink() # Clean up original dummy file\n    backup_file_path.unlink() # Clean up backup file","lang":"python","description":"This quickstart demonstrates how to create an encrypted tar archive using `SecureTarFile` and add a file to it using `atomic_contents_add`. It then shows how to open and extract content from the created secure archive, requiring the correct password."},"warnings":[{"fix":"Ensure your application is updated to handle the new file format and cryptographic primitives. Old backups remain readable, but new ones will use the v3 format. Consult the release notes for detailed migration steps.","message":"Version 2026.2.0 introduced a new file format (version 3) using Argon2 for key derivation, Blake2 for subkey derivation, and ChaCha13Poly1305 for encryption. This was a major rewrite breaking most existing implementations.","severity":"breaking","affected_versions":">=2026.2.0"},{"fix":"Adopt the library's internal key derivation mechanisms. Review your code for custom key derivation and update to use `SecureTarFile`'s integrated password handling.","message":"Version 2025.12.0 moved the key derivation function into the library itself, requiring a breaking change in the API. Any custom password-to-key derivation logic outside the library will no longer be compatible.","severity":"breaking","affected_versions":">=2025.12.0"},{"fix":"Be aware that backups created with 2025.1.3+ cannot be read by older versions of `securetar`. Plan upgrades carefully to maintain compatibility with your backup/restore processes. Old formats can still be read by newer versions of the library.","message":"Version 2025.1.3 added a new file header for encrypted tar files, making the file format *not* backwards compatible for writing new archives, although the library retains the ability to read older formats.","severity":"breaking","affected_versions":">=2025.1.3"},{"fix":"Upgrade your Python environment to 3.11 or newer if you are using `securetar` versions 2025.12.0 or later.","message":"The minimum required Python version was bumped to 3.11 in release 2025.12.0.","severity":"breaking","affected_versions":">=2025.12.0"},{"fix":"Ensure you are using the latest `securetar` version (2026.2.0+) for the most robust and secure backup handling. Regenerate existing encryption keys if you suspect past issues.","message":"Some earlier versions had potential issues with non-random IVs or padding, which could lead to backup corruption or make decryption less secure. These issues were addressed in later versions, particularly with the introduction of v3.","severity":"gotcha","affected_versions":"<2026.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the password is correct. Ensure the `securetar` library version used for decryption is compatible with the version used for encryption. If using custom scripts, update them to reflect the latest `securetar` API and file format changes.","cause":"Attempting to decrypt an encrypted `securetar` archive with an incorrect password, an outdated decryption script, or a version of `securetar` that doesn't support the specific file format (e.g., v3 introduced in 2026.2.0).","error":"ReadError: not a gzip file"},{"fix":"Always use the `securetar` Python library itself for decrypting and extracting contents from a `securetar` archive. Standard archive tools will not recognize the encrypted stream as a valid archive before decryption.","cause":"SecureTar creates a custom encrypted format that is not directly compatible with standard `.tar.gz` or `.zip` tools like 7-Zip for decryption or extraction.","error":"Cannot open, not an archive (when using 7-Zip or standard tools)"},{"fix":"Review the API changes in `securetar` versions 2025.12.0 and later. Ensure your application uses the `SecureTarFile` class directly with the password parameter, allowing the library to handle key derivation internally according to the current format specification.","cause":"The key derivation function was moved into the library in version 2025.12.0, causing API changes for how passwords are processed into encryption keys. This can lead to incompatibility with older methods of deriving keys or with backups created using older library versions that processed passwords differently.","error":"Key derivation failed or 'invalid password' for existing backups after library upgrade."}]}