.. /*
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * SPDX-License-Identifier: CC-BY-SA-4.0
    *
    * For more information, please contact Datraverse B.V. at this
    * address: info@datraverse.com
    */

.. _ch-security-document-signature:

Document Signature
------------------

|PRODUCT_NAME| generates a digital signature for every document
printed-out or downloaded. Digital signatures are generated using a
cryptographic technique called Hash-based Message Authentication Code
(HMAC) [1]_. The algorithm takes various output job attributes such as
job time, user name, document name and UUID, and combines them with a
secret key. The result is then passed through the MD5 digest algorithm.
The resulting signature is unique to the document instance [2]_. The
applied secret key ensures the *authenticity* of the signature.

The algorithm used is:

-  ``Digest = Hash(date time || user name || document name || document UUID)``

-  ``Signature = Hash(Digest || Key)``

where

-  ``Key`` is a random string generated by |PRODUCT_NAME| at initial
   installation. It is stored as ``hmac.key`` property in the
   ``/opt/savapage/server/data/encryption.properties`` file, which is
   also used for :ref:`Encrypted Secrets <ch-security-encrypted-secrets>`.

-  ``Hash`` is the MD5 function.

-  ``date time`` is formatted in ``ISO 8601`` basic format from year to
   second (``yyyyMMddTHHmmss``). The time is local time (not UTC). E.g.
   ``20120906T151231``.

.. note::

   The signature is stored in the database for future use.

.. [1]
   https://en.wikipedia.org/wiki/HMAC.

.. [2]
   The SHA1 digest algorithm is a stronger alternative, but MD5 is
   secure enough for our application and generates shorter signatures,
   which are easier to enter as argument to find the matching document.