MQLArticles/Utils/Encrypt/README.md

# Encrypt

Este modulo integra una clase CEncryptor, clase warppers con funciones utiles para encryptar y desencriptar archivos y texto se basa en las funciones nativas que proporciona MQL5  (`CryptEncode` / `CryptDecode`).


## Métodos soportados

| Método | Key requerida |
|---|---|
| `CRYPT_AES128` | 16 chars |
| `CRYPT_AES256` | 32 chars |
| `CRYPT_DES` | 7 chars |

> Los métodos de hash (`CRYPT_HASH_SHA1`, `CRYPT_HASH_SHA256`, `CRYPT_HASH_MD5`) y `CRYPT_BASE64` no son métodos de encriptación y no están soportados por esta clase.

 ---

## Funcion EncryptFile 
### Firma:
```cpp
bool EncryptFile(const string& file_name, bool common_flag, ENUM_CRYPT_METHOD method, bool delete_prev_file, string ext_encrypt = "")
```
### Parametros

| Parámetro | Descripción |
|---|---|
| `file_name` | Ruta del archivo encriptado |
| `common_flag` | `true` = carpeta Common, `false` = `MQL5\Files` del terminal |
| `method` | Método usado al encriptar (ver tabla de métodos) |
| `delete_prev_file` | `true` = elimina el archivo encriptado original tras encriptar |
| `ext_encrypt` | `true` = Extension para el archivo encryptado por defecto nada ("") |
 
### Ejemplos
```cpp
 enc.EncryptFile("file.txt", false, CRYPT_AES256, false, ".enc");
```

---

## Funcion DecryptFile

### Firma
```cpp
// Versión 1 — resultado en archivo
bool DecryptFile(const string& file_name, bool common_flag, ENUM_CRYPT_METHOD method, bool delete_prev_file, string ext_decrypt = "")

// Versión 2 — resultado en memoria
bool DecryptFile(const string& file_name, bool common_flag, ENUM_CRYPT_METHOD method, bool delete_prev_file, uchar& res_data[])
```

### Parámetros comunes

| Parámetro | Descripción |
|---|---|
| `file_name` | Ruta del archivo encriptado |
| `common_flag` | `true` = carpeta Common, `false` = `MQL5\Files` del terminal |
| `method` | Método usado al encriptar (ver tabla de métodos) |
| `delete_prev_file` | `true` = elimina el archivo encriptado original tras desencriptar |

### Parámetro `ext_decrypt` (Versión 1)

Controla el nombre del archivo de salida:

| Valor | Comportamiento | Ejemplo |
|---|---|---|
| `""` | Sobreescribe el mismo archivo | `file.enc` a `file.enc` |
| `".ext"` | Agrega extensión al nombre | `file.enc` a `file.enc.ext` |
| `"-"` | Quita la última extensión | `file.enc` a `file` |
| `".ext-"` | Reemplaza la última extensión | `file.enc` a `file.ext` |

> **Nota:** Si `delete_prev_file = false` y `ext_decrypt = ""`, el archivo encriptado (solo si este no tiene extension, si tiene eg .enc el archivo original no sera sobreescrito solo el encriptado) es sobreescrito con el contenido desencriptado.

### Ejemplos
```cpp
// Versión 1 — quitar extensión .enc
enc.DecryptFile("data.csv.enc", true, CRYPT_AES256, true, "-");
// Resultado: data.csv  (data.csv.enc eliminado)

// Versión 1 — reemplazar extensión
enc.DecryptFile("data.csv.enc", true, CRYPT_AES256, false, ".csv-");
// Resultado: data.csv  (data.csv.enc conservado)

// Versión 2 — resultado en memoria
uchar buffer[];
enc.DecryptFile("data.csv.enc", true, CRYPT_AES256, false, buffer);
// buffer contiene el contenido desencriptado
```

---

## SetAleatoryKey

### Firma
```cpp
bool SetAleatoryKey(ENUM_CRYPT_METHOD method, FuncGenerateRandomUchar f_generate_char, void* ptr = NULL, uchar chart_start = 32, uchar chart_stop = 255)
```

### Parámetros

| Parámetro | Descripción |
|---|---|
| `method` | Método de encriptación (determina el largo de la key) |
| `f_generate_char` | Función que genera un `uchar` aleatorio |
| `ptr` | Puntero al generador (se pasa a `f_generate_char`, esto es opcional solo si la funcion trabaja con clases) |
| `chart_start` | Valor mínimo del carácter generado (default: 32) |
| `chart_stop` | Valor máximo del carácter generado (default: 255) |

> **Nota:** El largo de la key se determina automáticamente según el método: AES128 = 16, AES256 = 32, DES = 7. La key generada queda almacenada internamente y puede recuperarse con `Key()`.

### Ejemplo
```cpp
CRandomSimple random;
enc.SetAleatoryKey(CRYPT_AES256, RandomSimpleGenerateRandomUchar, &random);
Print(enc.Key()); // key de 32 chars generada
```

---

## EncryptText / DecryptText

### Firma
```cpp
bool EncryptText(const string& initial_text, ENUM_CRYPT_METHOD method, string& encrypted_text)
bool DecryptText(const string& encrypted_text, ENUM_CRYPT_METHOD method, string& decrypted_text)
```

### Parámetros

| Parámetro | Descripción |
|---|---|
| `initial_text` | Texto plano a encriptar |
| `encrypted_text` | String encriptado en BASE64 (entrada en Decrypt, salida en Encrypt) |
| `decrypted_text` | Texto plano recuperado (salida en Decrypt) |
| `method` | Método de encriptación (ver tabla de métodos) |

> **Nota:** El texto encriptado se convierte automáticamente a BASE64 para poder almacenarse como `string`. Al desencriptar se revierte el proceso: BASE64 → bytes → texto original.

### Ejemplo
```cpp
string encrypted, decrypted;

enc.EncryptText("texto secreto", CRYPT_AES256, encrypted);
// encrypted contiene el texto en BASE64

enc.DecryptText(encrypted, CRYPT_AES256, decrypted);
// decrypted == "texto secreto"
```