spass-tools

Encrypt and decrypt Samsung Pass .spass files. Convert passwords between .spass and CSV formats.

Table of Contents

• Quick Start
• Exporting from Samsung Pass
• Usage
• Importing into Samsung Pass
• CSV Format
• .spass Format Reference
• Troubleshooting
• Contributing
• Acknowledgments
• License

Quick Start

Prerequisites

• Python 3.8+ (check "Add to PATH" during install on Windows)

Download

git clone https://github.com/VictorLavalle/spass-tools.git
cd spass-tools

Or download as ZIP from the releases page.

---

Exporting from Samsung Pass

1. Open the Samsung Wallet app on your phone

   

2. Tap the ⋮ (three dots) button in the top-right corner

   

3. Tap Settings

   

4. Tap Import and export Samsung Pass data

   

5. Select Export and set a password — this generates the .spass file

   

6. Transfer the .spass file to your computer

   

---

Usage

macOS / Linux

Run the unified tool:

./spass_tools.sh

Or run encrypt/decrypt directly:

./decrypt.sh    # .spass → CSV
./encrypt.sh    # CSV → .spass

Windows

Double-click spass_tools.bat

Or run individually: decrypt.bat / encrypt.bat

All scripts will:

1. Check that Python is installed
2. Auto-install dependencies if needed
3. Auto-detect files in the current folder
4. Open a file browser if you need to pick a different file
5. Ask for the password securely (hidden input)

Advanced (command line)

pip3 install -r requirements.txt

python3 spass_to_csv.py backup.spass passwords.csv "mypassword"
python3 csv_to_spass.py passwords.csv backup.spass "mypassword"

If you omit the password argument, it will be prompted interactively.

---

Importing into Samsung Pass

1. Transfer the generated .spass file to your phone
2. Open the Samsung Wallet app
3. Tap the ⋮ (three dots) button in the top-right corner
4. Tap Settings
5. Tap Import and export Samsung Pass data
6. Select Import and choose the .spass file
7. Enter the password you used during encryption

---

CSV Format

The tool auto-detects columns from the most common password managers:

Source	Columns
Apple Passwords (Mac)	Title,URL,Username,Password,Notes,OTPAuth
Google Passwords	name,url,username,password,note
Chrome / Brave	name,url,username,password,note
LastPass	url,username,password,extra,name,grouping,fav
Bitwarden	folder,favorite,type,name,notes,fields,reprompt,login_uri,login_username,login_password,login_totp
1Password	Title,Url,Username,Password,Notes,Type

Any CSV with similar column names will work — the tool matches columns case-insensitively.

---

.spass Format Reference

See docs/FORMAT.md for the full .spass file format specification, including encryption parameters, internal structure, and all 35 password record fields.

---

Troubleshooting

Problem	Solution
Wrong password or corrupted file	Double-check the password. It must match exactly what was used during export/encryption.
Python not found	Install Python 3.8+. On Windows, check "Add to PATH" during install.
No module named 'cryptography'	Run pip3 install -r requirements.txt or let the scripts auto-install dependencies.
No .spass/.csv files found	Place the file in the same folder as the scripts, or use the file browser when prompted.
Password must include at least 3 of...	Samsung Pass requires 8+ characters with at least 3 of: uppercase, lowercase, numbers, special characters.

---

Contributing

See CONTRIBUTING.md for guidelines on how to contribute, report bugs, and submit pull requests.

For security vulnerabilities, see SECURITY.md.

This project follows a Code of Conduct.

---

Acknowledgments

Huge thanks to 0xdeb7ef and their spass-manager project. Their reverse engineering of the .spass format and decryption logic was essential to building these tools. Without their work, this project wouldn't exist.

License

MIT