feat: README

README.md

@@ -0,0 +1,122 @@
+# libft_ssl
+
+A C library implementing cryptographic hash functions from scratch.
+
+Each algorithm exposes a uniform streaming API — `init` / `update` / `final`
+
+## Algorithms
+
+| Algorithm  | Digest | Block | Notes |
+|------------|--------|-------|-------|
+| MD5        | 128-bit | 512-bit | RFC 1321 - broken, non-security use only |
+| SHA-256    | 256-bit | 512-bit | SHA-2 family, NSA/NIST - widely used in TLS, Bitcoin |
+| Whirlpool  | 512-bit | 512-bit | ISO/IEC 10118-3 - Miyaguchi-Preneel construction |
+
+## API
+
+The public interface lives in `<libft_ssl/libft_ssl.h>`.
+
+```c
+struct digest_algo {
+    const char  *name;
+    size_t       digest_size;   /* bytes */
+    size_t       block_size;    /* bytes */
+    void (*init)  (void *ctx);
+    void (*update)(void *ctx, const uint8_t *data, size_t len);
+    void (*final) (void *ctx, uint8_t *out);
+};
+
+union digest_ctx { /* one allocation covers all algorithm contexts */
+    struct md5_ctx       md5;
+    struct sha256_ctx    sha256;
+    struct whirlpool_ctx whirlpool;
+};
+```
+
+One global instance is provided per algorithm: `g_md5`, `g_sha256`,
+`g_whirlpool`.
+
+### Example
+
+```c
+#include <libft_ssl/libft_ssl.h>
+#include <stdio.h>
+
+int main(void)
+{
+    const struct digest_algo *algo = &g_sha256;
+    union digest_ctx          ctx;
+    uint8_t                   digest[32];
+
+    algo->init(&ctx);
+    algo->update(&ctx, (const uint8_t *)"hello", 5);
+    algo->final(&ctx, digest);
+
+    for (size_t i = 0; i < algo->digest_size; i++)
+        printf("%02x", digest[i]);
+    puts("");
+}
+```
+
+Compile with:
+
+```sh
+cc example.c -lft_ssl -o example
+# or with pkg-config:
+cc example.c $(pkg-config --cflags --libs libft_ssl) -o example
+```
+
+## Building
+
+### Dependencies
+
+- C99 compiler
+- autoconf
+- automake
+- libtool
+- `pdflatex` — only if building documentation (`--enable-doc`)
+
+### Steps
+
+```sh
+./autogen.sh          # generate the build system (first checkout only)
+./configure
+make
+make install          # installs to /usr/local by default
+```
+
+Common `configure` options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--prefix=PATH` | `/usr/local` | Installation prefix |
+| `--enable-debug` | no | Build with `-g -O0` instead of `-O2` |
+| `--enable-doc` | no | Build PDF documentation (requires `pdflatex`) |
+
+### pkg-config
+
+After installation the library registers itself with pkg-config:
+
+```sh
+pkg-config --cflags --libs libft_ssl
+```
+
+## Project structure
+
+```
+include/          public and internal headers
+src/
+  md5/            MD5 init / update / compress / final
+  sha256/         SHA-256 init / update / compress / final
+  whirlpool/      Whirlpool init / update / compress / final
+  libft_ssl.c     algorithm descriptor table (X-macro generated)
+doc/              LaTeX source for the technical documentation
+```
+
+## Documentation
+
+The full technical write-up is available at <https://lohic.dev/libft_ssl.html> ([PDF](https://lohic.dev/libft_ssl.pdf)).
+
+## License
+
+GPLv3 — see [LICENSE](LICENSE).