diff --git a/MACOS_BUILD_INSTRUCTIONS.md b/MACOS_BUILD_INSTRUCTIONS.md new file mode 100644 index 0000000..565de01 --- /dev/null +++ b/MACOS_BUILD_INSTRUCTIONS.md @@ -0,0 +1,123 @@ +# Building Picocrypt on macOS + +This guide provides instructions on how to build Picocrypt from source on a macOS system. + +## Prerequisites + +1. **Xcode Command Line Tools:** + If you haven't already, install the Xcode Command Line Tools. Open Terminal and run: + ```bash + xcode-select --install + ``` + Follow the on-screen prompts. + +2. **Homebrew:** + Homebrew is a package manager for macOS. If you don't have it, install it by following the instructions at [brew.sh](https://brew.sh/). + +3. **Go Programming Language:** + * **Installation:** It's recommended to install the latest stable version of Go. You can download it from the [official Go website](https://golang.org/dl/) or install it via Homebrew: + ```bash + brew install go + ``` + * **Environment Setup (if not using Homebrew's Go):** Ensure your `GOPATH` and `GOROOT` environment variables are set up correctly, and that `$GOPATH/bin` and `$GOROOT/bin` are in your `PATH`. If you installed Go via Homebrew, this is usually handled automatically. You can check your Go environment with `go env`. + +4. **Git:** + If not already installed (usually comes with Xcode Command Line Tools), install Git: + ```bash + brew install git + ``` + +5. **Required Libraries (GLFW & GLEW):** + Picocrypt's GUI depends on GLFW and GLEW. Install them using Homebrew: + ```bash + brew install glfw glew + ``` + +## Build Steps + +1. **Clone the Repository:** + Open Terminal and navigate to the directory where you want to store the Picocrypt source code. Then clone the repository: + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +2. **Navigate to the Source Directory:** + The main Go source code is located in the `src` directory. + ```bash + cd src + ``` + +3. **Download Dependencies:** + Picocrypt uses Go modules to manage its dependencies. Download them using: + ```bash + go mod download + ``` + This command inspects the `go.mod` file and downloads all necessary libraries. + +4. **Compile the Application:** + Build the Picocrypt application. The `-ldflags="-s -w"` flags help reduce the binary size by stripping debug symbols. `CGO_ENABLED=1` is necessary as Picocrypt uses Cgo for its GUI components. + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `-v` flag enables verbose output, showing the packages as they are compiled. The `-o Picocrypt` flag specifies the output file name. + + Upon successful compilation, you will find an executable file named `Picocrypt` in the `src` directory. + +## Packaging (Optional - Creating a .app Bundle and .dmg) + +The following steps replicate the process used in the GitHub Actions workflow to create a standard macOS application bundle (`.app`) and a disk image (`.dmg`). + +1. **Prepare the .app Bundle Structure:** + The Picocrypt repository includes a template for the `.app` bundle. + * Go back to the root directory of the cloned repository: + ```bash + cd .. + ``` + * The template `Picocrypt.app.zip` is usually located in `dist/macos/`. For a manual build, you might need to ensure this path is correct or download/copy this template if it's not present directly. Assuming it's in `dist/macos/`: + ```bash + cp dist/macos/Picocrypt.app.zip . + unzip -d Picocrypt.app Picocrypt.app.zip + rm Picocrypt.app.zip + ``` + This creates a `Picocrypt.app` directory with the necessary bundle structure. + +2. **Move the Compiled Binary:** + Move the `Picocrypt` executable you compiled in the `src` directory into the `.app` bundle: + ```bash + mv src/Picocrypt Picocrypt.app/Contents/MacOS/Picocrypt + ``` + +3. **Create the .dmg Disk Image:** + * Create a temporary directory to hold the `.app` bundle for DMG creation: + ```bash + mkdir out + cp -R Picocrypt.app out/ + ``` + * Use `hdiutil` to create the DMG: + ```bash + hdiutil create Picocrypt.dmg -volname Picocrypt -fs APFS -format UDZO -srcfolder out + ``` + This will create `Picocrypt.dmg` in the root of the repository. + + * Clean up the temporary directory: + ```bash + rm -rf out + rm -rf Picocrypt.app + ``` + +You should now have a `Picocrypt.dmg` file ready for distribution or installation. The standalone `Picocrypt` executable (from `src/Picocrypt`) can also be run directly if you don't need the `.app` bundle. + +## Running Picocrypt + +* **Directly:** You can run the compiled binary from the `src` directory: + ```bash + ./src/Picocrypt + ``` +* **From .app Bundle:** If you created the `.app` bundle, you can run it by double-clicking `Picocrypt.app` in Finder, or from Terminal: + ```bash + open Picocrypt.app + ``` +* **From .dmg:** Open `Picocrypt.dmg`, and then drag `Picocrypt.app` to your Applications folder. Run it from there. + +This completes the build process for Picocrypt on macOS. diff --git a/Picocrypt_Security_Review_Report.md b/Picocrypt_Security_Review_Report.md new file mode 100644 index 0000000..5bf835b --- /dev/null +++ b/Picocrypt_Security_Review_Report.md @@ -0,0 +1,108 @@ +# Picocrypt v1.48 Security Code Review Report + +## 1. Introduction + +This report summarizes the findings of a security code review conducted on the Picocrypt v1.48 application. The review focused on the Go source code (`src/Picocrypt.go`) and associated build/distribution files available in the repository. The goal was to identify potential security vulnerabilities, assess the soundness of cryptographic implementations, and provide recommendations for improvement. + +## 2. Overall Security Posture + +Picocrypt demonstrates a strong commitment to security in its design and implementation. The core cryptographic operations are generally sound, leveraging modern, robust algorithms and practices. The code is self-contained in a single Go file for its core logic, which aids review. Error handling is present, and the lack of verbose file logging is a plus. The Plausible Deniability and Reed-Solomon features are notable additions with specific security characteristics. + +No critical vulnerabilities that would allow for immediate compromise of the core encryption under typical usage were identified in the reviewed code. The recommendations primarily focus on defense-in-depth, supply chain security for the build process, and clarification of advanced feature behavior. + +## 3. Key Findings by Area + +### 3.1. Cryptographic Primitives & Usage +* **Strong Choices:** Uses Argon2id for key derivation, ChaCha20 and Serpent (optional "Paranoid" mode) for encryption, HMAC-SHA3-512 or Keyed BLAKE2b for MAC, SHA3 for hashing, and HKDF for subkey derivation. These are excellent, modern choices. +* **Parameters:** Salts (16-byte Argon2, 32-byte HKDF), nonces (24-byte ChaCha20), and IVs (16-byte Serpent) are generated using `crypto/rand` and are of appropriate lengths. Argon2 parameters are robust (1GiB memory, 4-8 iterations). +* **Nonce/IV Rekeying:** For large files (>60GiB), nonces/IVs for the main encryption are updated using HKDF from the master key, which is a sound approach. The Plausible Deniability layer uses a different SHA3-based nonce update for its outer encryption if the volume is large; while non-standard, it's likely secure in context given the unique key and initial random nonce for that layer. +* **Temporary Zip Encryption:** Uses unauthenticated ChaCha20 for an intermediate zip file during multi-file operations. The risk is likely low as it's a local temporary file and the main subsequent encryption is authenticated. + +### 3.2. Key Management +* Keys are derived on-the-fly from passwords (Argon2id) and optional keyfiles; they are not stored persistently. +* Keyfiles are processed by hashing their content with SHA3-256 and then XORing the resulting hash (or a combination of hashes if multiple keyfiles) with the password-derived key. This combination method is sound. Checks for all-zero effective keyfile contributions (e.g., from duplicate unordered keyfiles) are present. +* Password handling includes UI masking, clearing from memory via a comprehensive `resetUI()` function, and strength estimation with `zxcvbn-go`. Clipboard copy/paste of passwords is a user-initiated action with inherent OS-level risks. +* Necessary salts and verification hashes (`keyHashRef` for password, `keyfileHashRef` for keyfiles) are stored in the file header to enable decryption and verification. + +### 3.3. Input Validation & Handling +* User comments have a defined length limit. Numeric inputs (e.g., `splitSize` for file chunking) are validated. +* Zip file extraction (`unpackArchive` function) includes a `strings.Contains(f.Name, "..")` check on archive member names to prevent basic Zip Slip path traversal vulnerabilities. + +### 3.4. File I/O Operations +* The use of `.incomplete` temporary files for output and subsequent `os.Rename` on success promotes atomicity for write operations, reducing risk of data corruption from interruptions. +* Temporary files created during intermediate steps (e.g., temporary zip, plausible deniability processing) are generally cleaned up correctly on success, error, or cancellation. +* File handles are mostly closed explicitly. More consistent use of `defer file.Close()` could improve code robustness for future modifications. + +### 3.5. Error Handling & Logging +* User-facing error messages, displayed in the UI status area, are generally clear and do not appear to leak sensitive cryptographic data or excessive system details. +* No file-based logging was found within `Picocrypt.go`, which is positive from a security standpoint as it avoids persistent storage of potentially sensitive operational data. +* `panic()` is used for conditions deemed fatal by the application, primarily unexpected errors from cryptographic libraries or critical I/O operations. Panic messages are generally generic. + +### 3.6. Plausible Deniability +* Implemented as an outer encryption layer (Argon2/ChaCha20 with its own unique random salt and nonce) applied over a standard Picocrypt volume. +* If the correct password for this outer layer is not supplied, the file content (after the initial salt/nonce) will appear as random data, thus providing deniability against casual observation or tools that expect specific file signatures. +* **Limitation:** The current implementation uses the *same user-provided password* to decrypt the outer Plausible Deniability layer and subsequently to derive the key for the inner (actual) volume. It does not support a distinct "hidden volume password" separate from the "outer volume password". The UI tooltip appropriately warns users about this feature. + +### 3.7. Reed-Solomon Erasure Coding +* Effectively utilized with high redundancy (e.g., 1 data byte to 3 total bytes for comments, 5 data to 15 total for version) to protect all critical header fields against corruption. This significantly enhances volume robustness. +* Optionally, it can be applied to the ciphertext of the main file data with lower redundancy (128 data bytes, 8 parity bytes, correcting up to 4 corrupted bytes per 136-byte block). +* The `fastDecode` optimization (skipping RS decoding if MAC verifies) is a sensible performance enhancement. PKCS#7 padding for the final data block (if RS coding is active for data) is correctly handled. + +### 3.8. Dependency Review +* Core cryptographic operations leverage Go's standard `crypto/*` packages and the supplementary `golang.org/x/crypto` library (v0.38.0 at the time of review, which is reasonably recent). +* Several custom libraries from `github.com/Picocrypt/*` are used for: + * **Serpent cipher:** `github.com/Picocrypt/serpent` (critical for confidentiality). + * **Reed-Solomon:** `github.com/Picocrypt/infectious`. + * **GUI:** `github.com/Picocrypt/giu` (and its underlying `imgui-go` bindings). + * **Dialogs:** `github.com/Picocrypt/dialog`. + * **Password Strength:** `github.com/Picocrypt/zxcvbn-go`. +* The security of Picocrypt is inherently tied to the security and correctness of these custom dependencies. + +### 3.9. Concurrency and Goroutines +* Goroutines are employed for background tasks (file scanning, encryption/decryption) to maintain UI responsiveness. +* Synchronization primarily relies on disabling UI elements during operations, cooperative cancellation checks (via the `working` flag), and the `giu.Update()` mechanism (assumed to handle thread-safe UI updates). +* While explicit Go mutexes are not used for most global state variables shared between worker goroutines and the main GUI thread, the typical immediate-mode GUI update pattern likely mitigates many direct data race potentials for UI data. +* Recursive operations correctly scope their operational parameters, reducing risks of self-interference. No critical race conditions directly compromising cryptographic integrity were found. + +### 3.10. GUI Interaction and State Management +* Sensitive inputs like passwords are appropriately masked in UI fields by default. +* The `resetUI()` function is critical and implemented diligently to clear sensitive global variables (passwords, keyfiles, operational state) after operations or on user request. This is key to preventing state leakage. +* The clipboard copy feature for passwords, while a common usability function, carries inherent OS-level risks that users should be aware of. + +### 3.11. Build and Distribution +* Builds are automated via GitHub Actions for Linux, macOS, and Windows. +* CodeQL static analysis is integrated into CI, a positive security measure. +* Official releases include SHA256 checksums for artifact verification by users. +* **Supply Chain Concern:** Build-time tools (Resource Hacker, UPX) and a .deb packaging skeleton are downloaded from `github.com/user-attachments` URLs during CI builds. This practice poses a supply chain risk if the content at these URLs is compromised. + +## 4. Security Recommendations + +### 4.1. High Priority +* **Audit Custom Serpent Implementation (`github.com/Picocrypt/serpent`):** + * **Recommendation:** Given that Serpent is a less common cipher than AES, and cryptographic implementations are notoriously difficult to get right, the custom `github.com/Picocrypt/serpent` library should ideally undergo a dedicated, expert cryptographic audit. This is paramount for ensuring the confidentiality provided by Picocrypt when Serpent is in use (Paranoid mode). + * **Rationale:** Flaws in cipher implementations can lead to catastrophic vulnerabilities. + +### 4.2. Medium Priority +* **Build Process Hardening - Vendor/Verify Build Tools:** + * **Recommendation:** Modify the GitHub Actions workflows to avoid downloading build-time dependencies (Resource Hacker, UPX, .deb skeleton ZIP) from `user-attachments` URLs. Instead: + 1. Commit these tools/templates directly into the Picocrypt repository (e.g., under a `build_tools/` directory). + 2. Alternatively, if fetching from official sources, ensure their checksums are programmatically verified within the build script immediately after download and before execution/use. + * **Rationale:** This mitigates the supply chain risk of the build process being compromised if the externally hosted files are tampered with. + +### 4.3. Low Priority / Considerations +* **Plausible Deniability Password Clarification:** + * **Recommendation:** Enhance documentation to explicitly state that the current Plausible Deniability feature uses the *same* password for the outer decoy layer and the inner volume's decryption. This manages user expectations, as it differs from "hidden volume with a separate password" schemes found in some other tools. + * **Rationale:** Clear documentation prevents user misunderstanding of the feature's capabilities. +* **Clipboard Interaction Risks:** + * **Recommendation:** Briefly remind users in the documentation about the general security risks associated with using the clipboard for sensitive data like passwords. + * **Rationale:** User education on a common but potentially risky OS feature. +* **File Closing Consistency:** + * **Recommendation:** Consider more consistent use of `defer file.Close()` immediately after `os.Open` or `os.Create` calls, particularly in the `work()` function and its helper routines. + * **Rationale:** While current explicit `Close()` calls appear to cover necessary paths, `defer` simplifies logic, reduces the chance of missed closes if new code paths are added, and is idiomatic Go. +* **Zip Slip Defense-in-Depth (Minor Enhancement):** + * **Recommendation:** In the `unpackArchive` function, after `outPath := filepath.Join(extractDir, f.Name)`, consider adding an explicit check to ensure that the cleaned, absolute `outPath` is still a child of (or prefixed by) the cleaned, absolute `extractDir`. + * **Rationale:** Provides an additional layer of defense against more sophisticated or unusual Zip Slip path traversal attempts that might bypass the current `strings.Contains(f.Name, "..")` check. + +## 5. Conclusion + +Picocrypt v1.48 is a thoughtfully designed piece of encryption software with a strong emphasis on modern cryptographic practices. The core encryption and key derivation logic appears sound. The provided recommendations aim to further enhance its security, particularly in the areas of dependency trust and build process integrity. diff --git a/README.md b/README.md index 74292ab..5b5c08c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Picocrypt

-Picocrypt is a very small (hence Pico), very simple, yet very secure encryption tool that you can use to protect your files. It's designed to be the go-to tool for encryption, with a focus on security, simplicity, and reliability. Picocrypt uses the secure XChaCha20 cipher and the Argon2id key derivation function to provide a high level of security, even from three-letter agencies like the NSA. Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt. +Picocrypt is a very small (hence Pico), very simple, yet very secure encryption tool that you can use to protect your files. It'sdesigned to be the go-to tool for encryption, with a focus on security, simplicity, and reliability. Picocrypt uses the secure XChaCha20 cipher and the Argon2id key derivation function to provide a high level of security, even from three-letter agencies like the NSA. Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt.

Picocrypt

@@ -45,6 +45,141 @@ A functionally limited web app is available PicoGo is a community-developed port of Picocrypt to platforms like Android and iOS using the Fyne GUI library. Feel free to try it out, but keep in mind that it is *not* part of the official core Picocrypt project (like the platforms listed above) and thus not subject to the same scrutiny and standards that the core project is. So, **use it with caution and diligence** during its experimental phase. +# Building from Source + +This section provides guidance on how to build Picocrypt from source on various operating systems. The build process requires Go version 1.24 or newer. + +### Linux + +1. **Install Prerequisites:** + You'll need Go and several C libraries for the GUI components. + ```bash + sudo apt update + sudo apt install -y golang-go gcc xorg-dev libgtk-3-dev libgl1-mesa-dev libglu1-mesa + ``` + *(Note: Ensure the `golang-go` package from your distribution provides Go >=1.24. If not, install Go manually from [go.dev/dl](https://go.dev/dl/))* + +2. **Clone the Repository:** + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + Navigate to the source directory and download the module dependencies. + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt:** + Compile the application. `CGO_ENABLED=1` is required. + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `Picocrypt` executable will be created in the `src` directory. You can move it to a directory in your system's `$PATH` (e.g., `~/.local/bin` or `/usr/local/bin`) for easier access. + +### macOS + +1. **Install Prerequisites:** + * **Xcode Command Line Tools:** If not already installed, open Terminal and run: + ```bash + xcode-select --install + ``` + * **Homebrew:** Install from [brew.sh](https://brew.sh/) if you don't have it. + * **Go:** Install Go (>=1.24) via Homebrew or from [go.dev/dl](https://go.dev/dl/): + ```bash + brew install go + ``` + * **Git:** + ```bash + brew install git + ``` + * **Required Libraries (GLFW & GLEW):** + ```bash + brew install glfw glew + ``` + +2. **Clone the Repository:** + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt:** + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `Picocrypt` executable will be in the `src` directory. + +5. **(Optional) Create .app Bundle and .dmg:** + To create a standard macOS application bundle and disk image: + * Navigate to the repository root: `cd ..` + * Copy and unzip the app template (ensure `dist/macos/Picocrypt.app.zip` exists): + ```bash + cp dist/macos/Picocrypt.app.zip . + unzip -d Picocrypt.app Picocrypt.app.zip + rm Picocrypt.app.zip + ``` + * Move the compiled binary into the bundle: + ```bash + mv src/Picocrypt Picocrypt.app/Contents/MacOS/Picocrypt + ``` + * Create the DMG: + ```bash + mkdir TempDMGFolder + cp -R Picocrypt.app TempDMGFolder/ + hdiutil create Picocrypt.dmg -volname Picocrypt -fs APFS -format UDZO -srcfolder TempDMGFolder + rm -rf TempDMGFolder Picocrypt.app + ``` + +### Windows + +1. **Install Prerequisites:** + * **Go:** Install Go (>=1.24) from [go.dev/dl](https://go.dev/dl/). + * **C Compiler (for CGO):** MSYS2 with MinGW-w64 is recommended. + * Install MSYS2 from [www.msys2.org](https://www.msys2.org/). + * From an MSYS2 MINGW64 shell, install GCC: + ```bash + pacman -Syu + pacman -S mingw-w64-x86_64-gcc + ``` + * Ensure the MinGW-w64 `bin` directory (e.g., `C:\msys64\mingw64in`) is in your system `PATH`. + * **Git:** Install Git from [git-scm.com/download/win](https://git-scm.com/download/win). + +2. **Clone the Repository:** + Use Git Bash or Command Prompt with Git: + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt (Basic Executable):** + In Command Prompt or PowerShell (ensure GCC is in PATH): + ```cmd + set CGO_ENABLED=1 + go build -v -ldflags="-s -w -H=windowsgui" -o Picocrypt.exe Picocrypt.go + ``` + This creates `Picocrypt.exe` in the `src` directory. This version lacks the embedded icon and manifest. + +5. **(Optional) Embedding Resources and Compressing:** + To replicate the official release builds, you'll need: + * **Resource Hacker:** Download from its official website (e.g., angusj.com/resourcehacker). + * **UPX:** Download from [upx.github.io](https://upx.github.io/). + The GitHub Actions workflow file `.github/workflows/build-windows.yml` contains specific command-line examples for using Resource Hacker to embed the icon (`images/key.ico`), manifest (`dist/windows/manifest.xml`), and version information (`dist/windows/versioninfo.rc`), and then UPX for compression. These steps are complex and require careful execution. Always download these tools from their official sources. + # Why Picocrypt? Why should you use Picocrypt instead of VeraCrypt, 7-Zip, BitLocker, or Cryptomator? Here are a few reasons why you should choose Picocrypt: