Metadata-Version: 2.4
Name: gemato
Version: 20.8
Summary: Gentoo Manifest Tool -- a utility to verify and update Manifest files
Author-email: Michał Górny <mgorny@gentoo.org>
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
License-File: COPYING
Requires-Dist: rich ; extra == "pretty-log"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: pytest ; extra == "test-full"
Requires-Dist: requests ; extra == "test-full"
Requires-Dist: responses ; extra == "test-full"
Requires-Dist: requests ; extra == "wkd-refresh"
Project-URL: Homepage, https://github.com/mgorny/gemato/
Provides-Extra: pretty-log
Provides-Extra: test
Provides-Extra: test-full
Provides-Extra: wkd-refresh

==================================
  gemato -- Gentoo Manifest Tool
==================================
:Author: Michał Górny
:License: 2-clause BSD license


Introduction
============
gemato provides a reference implementation of the full-tree Manifest
checks as specified in GLEP 74 [#GLEP74]_. Originally focused
on verifying the integrity and authenticity of the Gentoo ebuild
repository, the tool can be used as a generic checksumming tool
for any directory trees.


Usage
=====

Verification
------------
The basic purpose of gemato is to verify a directory tree against
Manifest files. In order to do that, run the ``gemato verify`` tool
against the requested directory::

    gemato verify /var/db/repos/gentoo

The tool will automatically locate the top-level Manifest (if any)
and check the specified directory recursively. If a subdirectory
of the Manifest tree is specified, only the specified leaf is checked.


Creating new Manifest tree
--------------------------
Creating a new Manifest tree can be accomplished using the ``gemato
create`` command against the top directory of the new Manifest tree::

    gemato create -p ebuild /var/db/repos/gentoo

Note that for the ``create`` command you always need to specify either
a profile (via ``-p``) or at least a hash set (via ``-H``).


Updating existing Manifests
---------------------------
The ``gemato update`` command is provided to update an existing Manifest
tree::

    gemato update -p ebuild /var/db/repos/gentoo

Alike ``create``, ``update`` also requires specifying a profile (``-p``)
or a hash set (``-H``). The command locates the appropriate top-level
Manifest and updates the specified directory recursively.
If a subdirectory of the Manifest tree is specified, the entries
for the specified leaf and respective Manifest files are updated.


Utility commands
----------------
gemato provides a few other utility commands that provide access to
its crypto backend. These are:

``gemato hash -H <hashes> [<path>...]``
  Print hashes of the specified files in Manifest-like format.

``gemato openpgp-verify [-K <key>] [<path>...]``
  Check OpenPGP cleartext signatures embedded in the specified files.

``gemato openpgp-verify-detached [-K <key>] <sig-file> <data-file>``
  Verify the specified data file against a detached OpenPGP signature.


Requirements
============
gemato is written in Python and compatible with implementations
of Python 3.9+. gemato is currently tested against CPython 3.9
through 3.11 and PyPy3.  gemato core depends only on standard Python
library modules.

Additionally, OpenPGP requires system install of GnuPG 2.2+
and requests_ Python module.  Tests require pytest_, and responses_
for mocking.


References and footnotes
========================
.. [#GLEP74] GLEP 74: Full-tree verification using Manifest files
   (https://www.gentoo.org/glep/glep-0074.html)

.. _requests: https://2.python-requests.org/en/master/
.. _pytest: https://docs.pytest.org/en/stable/
.. _responses: https://github.com/getsentry/responses

