add readme and manuals
This commit is contained in:
VALLONGOL
parent
4e58904e2d
commit
4c2c866895
50
README.md
50
README.md
@ -1,16 +1,50 @@
|
||||
# PyHasher
|
||||
|
||||
A brief description of PyHasher.
|
||||
|
||||
|
||||
A simple, modern, and cross-platform file hash calculator built with Python and Tkinter.
|
||||
|
||||
PyHasher allows you to quickly calculate the most common checksums and cryptographic hashes for any file, providing a clean and straightforward interface for verifying file integrity and authenticity.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
## Getting Started
|
||||
...
|
||||
- **Wide Range of Algorithms**: Calculates multiple hashes in a single operation.
|
||||
- **Checksums**: CRC32, Adler-32
|
||||
- **Cryptographic Hashes**: MD5, SHA-1, SHA-2 (256, 384, 512), SHA-3 (256), BLAKE2b
|
||||
- **User-Friendly Interface**: A simple GUI to select files and view results.
|
||||
- **Efficient**: Processes large files in chunks, keeping memory usage low.
|
||||
- **Cross-Platform**: Built with standard Python libraries, it runs on Windows, macOS, and Linux without extra dependencies.
|
||||
- **Copy-Paste Ready**: Easily copy any hash value with a simple click and drag.
|
||||
|
||||
## Contributing
|
||||
...
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.6+
|
||||
|
||||
All required libraries (`tkinter`, `hashlib`, `zlib`) are part of the Python standard library, so no external packages need to be installed.
|
||||
|
||||
---
|
||||
|
||||
## Installation & Running
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone [URL_DEL_TUO_REPOSITORY_GITEA]
|
||||
cd pyhasher
|
||||
```
|
||||
|
||||
2. **Run the application:**
|
||||
Navigate to the project's root directory (the one containing the `pyhasher` package) and run the following command:
|
||||
```bash
|
||||
python -m pyhasher
|
||||
```
|
||||
The application window will appear on the screen.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
...
|
||||
|
||||
This project is licensed under the MIT License. See the `LICENSE` file for details.
|
||||
@ -1,24 +1,67 @@
|
||||
# PyHasher - English Manual
|
||||
# PyHasher - User Manual
|
||||
|
||||
## Introduction
|
||||
Welcome to PyHasher. This document provides an overview of how to install, use, and understand the project.
|
||||
Welcome to PyHasher! This guide will help you understand all the application's features.
|
||||
|
||||
## Installation
|
||||
Describe the installation steps here. For example:
|
||||
1. Clone the repository: `git clone <repository_url>`
|
||||
2. Navigate to the project directory: `cd PyHasher`
|
||||
3. Install dependencies: `pip install -r requirements.txt` (if applicable)
|
||||
### Table of Contents
|
||||
1. [What is a Hash?](#1-what-is-a-hash)
|
||||
2. [Quick Start Guide](#2-quick-start-guide)
|
||||
3. [Supported Algorithms](#3-supported-algorithms)
|
||||
4. [Common Use Cases](#4-common-use-cases)
|
||||
5. [Frequently Asked Questions (FAQ)](#5-frequently-asked-questions-faq)
|
||||
|
||||
## Usage
|
||||
Explain how to run and use the application.
|
||||
- To run the application: `python -m pyhasher`
|
||||
- Command-line arguments (if any).
|
||||
- GUI interaction (if any).
|
||||
---
|
||||
|
||||
## Development
|
||||
Information for developers contributing to the project.
|
||||
- Code structure.
|
||||
- How to run tests.
|
||||
### 1. What is a Hash?
|
||||
|
||||
## Troubleshooting
|
||||
Common issues and their solutions.
|
||||
A "hash" (or checksum) is like a digital fingerprint for a file. It's a fixed-length string of text generated by a mathematical algorithm. Even the smallest change to the file (like altering a single character) will produce a completely different hash.
|
||||
|
||||
This makes hashes extremely useful for:
|
||||
- **Verifying Integrity**: Ensuring a file has not been corrupted during a download or transfer.
|
||||
- **Verifying Authenticity**: Checking that a file is exactly what the creator intended to distribute, without any tampering.
|
||||
|
||||
### 2. Quick Start Guide
|
||||
|
||||
Using PyHasher is very simple:
|
||||
|
||||
1. **Launch the application**.
|
||||
2. **Select a File**: Click the **"Browse..."** button. A dialog box will open for you to choose the file you want to analyze.
|
||||
3. **Calculate Hashes**: Once the file is selected, its path will appear in the text box. Click the **"Calculate Hashes"** button.
|
||||
4. **View and Copy Results**: The application will calculate and display all the hashes in their respective boxes. To copy a value, click inside the box, select the text with your mouse, and use `Ctrl+C` (or `Cmd+C` on Mac).
|
||||
|
||||
### 3. Supported Algorithms
|
||||
|
||||
PyHasher supports a wide range of algorithms, divided into two categories:
|
||||
|
||||
- **Checksums**: Excellent for detecting accidental errors.
|
||||
- `CRC32`, `Adler-32`: Very fast and commonly used for data integrity checks (e.g., in ZIP files).
|
||||
|
||||
- **Cryptographic Hashes**: Designed to be secure against intentional modifications.
|
||||
- `MD5`, `SHA-1`: Older algorithms. Useful for compatibility with legacy systems, but **not recommended** for modern security applications.
|
||||
- `SHA-2 (256, 384, 512)`: The current industry standard for security, widely used worldwide.
|
||||
- `SHA-3 (256)`: The newest official standard, designed as a secure alternative to the SHA-2 family.
|
||||
- `BLAKE2b`: A modern, extremely fast, and secure algorithm.
|
||||
|
||||
### 4. Common Use Cases
|
||||
|
||||
**Case 1: Verifying a Software Download**
|
||||
You've downloaded a program from the internet. The website provides an SHA-256 hash for the installation file.
|
||||
1. Use PyHasher to calculate the SHA-256 hash of the file you downloaded.
|
||||
2. Compare the result with the one published on the website.
|
||||
3. If the two hashes match, your download is perfect and has not been altered.
|
||||
|
||||
**Case 2: Checking a Data Backup**
|
||||
You have copied important files to an external drive. You want to be sure that the copy is identical to the original.
|
||||
1. Calculate the hashes (e.g., BLAKE2b) of the original files.
|
||||
2. Calculate the hashes of the files copied to the external drive.
|
||||
3. If the hashes match, the copy was successful and error-free.
|
||||
|
||||
### 5. Frequently Asked Questions (FAQ)
|
||||
|
||||
**Q: Why is the application slow with very large files?**
|
||||
**A:** PyHasher must read the entire file content to calculate the hashes. For a multi-gigabyte file, this operation naturally takes time. However, the process is optimized to use very little RAM, so it will not freeze your computer.
|
||||
|
||||
**Q: Can I hash an entire folder?**
|
||||
**A:** No. The current version of PyHasher is designed to analyze single files only.
|
||||
|
||||
**Q: Why are MD5 and SHA-1 included if they are considered insecure?**
|
||||
**A:** They are kept for compatibility with older systems or software that may still use them. For any new security needs, we strongly recommend using SHA-256 or newer algorithms.
|
||||
@ -1,24 +1,67 @@
|
||||
# PyHasher - Manuale Italiano
|
||||
# PyHasher - Manuale Utente
|
||||
|
||||
## Introduzione
|
||||
Benvenuto in PyHasher. Questo documento fornisce una panoramica su come installare, utilizzare e comprendere il progetto.
|
||||
Benvenuto in PyHasher! Questa guida ti aiuterà a comprendere tutte le funzionalità dell'applicazione.
|
||||
|
||||
## Installazione
|
||||
Descrivi i passaggi di installazione qui. Ad esempio:
|
||||
1. Clona il repository: `git clone <repository_url>`
|
||||
2. Naviga nella directory del progetto: `cd PyHasher`
|
||||
3. Installa le dipendenze: `pip install -r requirements.txt` (se applicabile)
|
||||
### Indice
|
||||
1. [Cos'è un Hash?](#1-cosè-un-hash)
|
||||
2. [Guida Rapida](#2-guida-rapida)
|
||||
3. [Algoritmi Supportati](#3-algoritmi-supportati)
|
||||
4. [Casi d'Uso Comuni](#4-casi-duso-comuni)
|
||||
5. [Domande Frequenti (FAQ)](#5-domande-frequenti-faq)
|
||||
|
||||
## Utilizzo
|
||||
Spiega come eseguire e utilizzare l'applicazione.
|
||||
- Per eseguire l'applicazione: `python -m pyhasher`
|
||||
- Argomenti da riga di comando (se presenti).
|
||||
- Interazione con la GUI (se presente).
|
||||
---
|
||||
|
||||
## Sviluppo
|
||||
Informazioni per gli sviluppatori che contribuiscono al progetto.
|
||||
- Struttura del codice.
|
||||
- Come eseguire i test.
|
||||
### 1. Cos'è un Hash?
|
||||
|
||||
## Risoluzione dei problemi
|
||||
Problemi comuni e relative soluzioni.
|
||||
Un "hash" (o checksum/somma di controllo) è come un'impronta digitale per un file. È una stringa di testo di lunghezza fissa generata da un algoritmo matematico. Anche la più piccola modifica al file (come cambiare un singolo carattere) produrrà un hash completamente diverso.
|
||||
|
||||
Questo rende gli hash estremamente utili per:
|
||||
- **Verificare l'integrità**: Assicurarsi che un file non sia stato danneggiato durante un download o un trasferimento.
|
||||
- **Verificare l'autenticità**: Controllare che un file sia esattamente quello che il creatore intendeva distribuire, senza alterazioni o manomissioni.
|
||||
|
||||
### 2. Guida Rapida
|
||||
|
||||
Usare PyHasher è molto semplice:
|
||||
|
||||
1. **Avvia l'applicazione**.
|
||||
2. **Seleziona un File**: Clicca sul pulsante **"Browse..."**. Si aprirà una finestra di dialogo per scegliere il file che vuoi analizzare.
|
||||
3. **Calcola gli Hash**: Una volta selezionato il file, il suo percorso apparirà nella casella di testo. Clicca sul pulsante **"Calculate Hashes"**.
|
||||
4. **Visualizza e Copia i Risultati**: L'applicazione calcolerà e mostrerà tutti gli hash nelle rispettive caselle. Per copiare un valore, clicca sulla casella, seleziona il testo con il mouse e usa `Ctrl+C` (o `Cmd+C` su Mac).
|
||||
|
||||
### 3. Algoritmi Supportati
|
||||
|
||||
PyHasher supporta un'ampia gamma di algoritmi, suddivisi in due categorie:
|
||||
|
||||
- **Checksums (Somme di Controllo)**: Ottimi per rilevare errori accidentali.
|
||||
- `CRC32`, `Adler-32`: Molto veloci e usati comunemente per la verifica dell'integrità dei dati (es. in file ZIP).
|
||||
|
||||
- **Hash Crittografici**: Progettati per essere sicuri contro modifiche intenzionali.
|
||||
- `MD5`, `SHA-1`: Algoritmi più datati. Utili per compatibilità con sistemi legacy, ma **non raccomandati** per applicazioni di sicurezza moderne.
|
||||
- `SHA-2 (256, 384, 512)`: Lo standard attuale per la sicurezza, ampiamente utilizzato in tutto il mondo.
|
||||
- `SHA-3 (256)`: Il più recente standard ufficiale, progettato per essere un'alternativa sicura alla famiglia SHA-2.
|
||||
- `BLAKE2b`: Un algoritmo moderno, estremamente veloce e sicuro.
|
||||
|
||||
### 4. Casi d'Uso Comuni
|
||||
|
||||
**Caso 1: Verificare il download di un software**
|
||||
Hai scaricato un programma da Internet. Il sito web fornisce un hash SHA-256 per il file di installazione.
|
||||
1. Usa PyHasher per calcolare l'hash SHA-256 del file che hai scaricato.
|
||||
2. Confronta il risultato con quello pubblicato sul sito.
|
||||
3. Se i due hash corrispondono, il tuo download è perfetto e non è stato alterato.
|
||||
|
||||
**Caso 2: Controllare un backup di dati**
|
||||
Hai copiato dei file importanti su un disco esterno. Vuoi essere sicuro che la copia sia identica all'originale.
|
||||
1. Calcola gli hash (es. BLAKE2b) dei file originali.
|
||||
2. Calcola gli hash dei file copiati sul disco esterno.
|
||||
3. Se gli hash corrispondono, la copia è avvenuta senza errori.
|
||||
|
||||
### 5. Domande Frequenti (FAQ)
|
||||
|
||||
**D: Perché l'applicazione impiega del tempo con file molto grandi?**
|
||||
**R:** PyHasher deve leggere l'intero contenuto del file per calcolare gli hash. Per un file di diversi gigabyte, questa operazione richiede tempo. Tuttavia, il processo è ottimizzato per usare pochissima memoria RAM, quindi non bloccherà il tuo computer.
|
||||
|
||||
**D: Posso calcolare l'hash di un'intera cartella?**
|
||||
**R:** No. La versione attuale di PyHasher è progettata per analizzare solo file singoli.
|
||||
|
||||
**D: Perché sono inclusi MD5 e SHA-1 se sono considerati insicuri?**
|
||||
**R:** Sono mantenuti per motivi di compatibilità con sistemi o software più vecchi che potrebbero ancora utilizzarli. Per qualsiasi nuova esigenza di sicurezza, ti consigliamo di usare SHA-256 o algoritmi più recenti.
|
||||
Loading…
Reference in New Issue
Block a user