Hacking on gisp
===============

This file is for people building gisp from a git checkout or working on the
code.  Users building from a release tarball should read INSTALL instead.

Requirements
------------

  * a C compiler (gcc or clang)
  * libsodium (with its development headers)
  * GNU Autotools: autoconf, automake, and gettext/autopoint
  * texinfo (makeinfo) for the manual
  * clang, for the optional libFuzzer harnesses

On Debian/Ubuntu:

    sudo apt-get install autoconf automake autopoint gettext \
                         libsodium-dev texinfo clang

Building from git
-----------------

The tarball ships a generated ./configure; a git checkout does not, so bootstrap
it first:

    ./autogen.sh          # runs autoreconf --install
    ./configure
    make

Hardening flags (PIE, RELRO/BIND_NOW, stack protector, stack-clash and CET
protection, FORTIFY, non-exec stack) are probed and enabled by default.  Turn
them off with:

    ./configure --disable-hardening

Testing
-------

    make check

runs the whole suite:

  * test_runner    -- unit tests that link libgispcore.a directly
                      (round-trips, header/ciphertext tampering, truncation,
                      the KDF/size DoS ceilings, symlink and same-file guards)
  * test_cli.sh    -- end-to-end CLI and pipe/stream behaviour
  * test_vectors.sh-- known-answer decrypts of the pinned tests/vectors/*.gisp
                      (these also detect any accidental on-disk-format or
                      byte-order change)
  * test_faults.sh -- LD_PRELOAD fault injection on write/read/fsync/rename
                      (skips itself where the preload is unavailable)

The full pre-release gate -- a clean bootstrap, build, make check, distcheck,
an AddressSanitizer + UndefinedBehaviorSanitizer run, and a short libFuzzer
smoke run -- lives in one script and is what CI executes:

    sh ci/run.sh

Maintainer warnings
-------------------

The everyday build stays quiet.  To build with the full warning set promoted to
errors (this is what the CI "maintainer warnings" pass does):

    ./configure --enable-gcc-warnings
    make CFLAGS='-g -O2 -Werror'

The flags are individually probed, so an unsupported one is skipped rather than
breaking the build.  -Werror is used only here and while probing, never in a
normal ./configure && make.

Fuzzing and formal checks
-------------------------

  * fuzz/        -- three libFuzzer harnesses (container parser, round-trip
                    property, passphrase reader).  See fuzz/README.md.
  * proof/       -- overflow_proof.c, a CBMC harness proving the checked size
                    arithmetic in src/common.c matches a 128-bit reference over
                    all inputs; tests/overflow_diff.c is the compiler-based
                    differential equivalent.
  * audit/       -- adversarial scripts and byte-flip tooling.

Source layout
-------------

  src/main.c      command-line interface and passphrase acquisition
  src/crypto.c    encrypt/decrypt state machines and atomic output
  src/common.c    secure memory, checked arithmetic, I/O helpers, hardening
  src/terminal.c  signal handling and passphrase reading
  include/gisp.h  crypto constants, on-disk layout, prototypes
  doc/            Texinfo manual (gisp.texi) and process docs
  gisp.1.in       man-page template (version/date filled in at build time)

Coding style
------------

GNU C style.  A .clang-format (BasedOnStyle: GNU) is included; format a file
with:

    clang-format -i src/whatever.c

Every source file carries a GPLv3-or-later notice.  Cryptography is delegated
to libsodium -- do not hand-roll primitives.  Secrets must live in
secure_malloc() memory and be wiped on every path; see the existing code.

Releasing
---------

See doc/RELEASING.md.  Security reports: see SECURITY.md.

--------------------------------------------------------------------------------

Copyright (C) 2026 Uladzislau Bolbas <cmrtumilovic@gmail.com>

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved.  This file is offered as-is, without any warranty.
