Hashing
=======

Compute cryptographic hashes and password KDF hashes.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-compute-hash
---------------------

Compute a cryptographic digest hash of a given input string. Returns the
hex-encoded hash and input length.

**Credit cost:** 1 credit per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``input``
     - string
     - yes
     - The string to hash.
   * - ``algorithm``
     - string
     - yes
     - Hash algorithm. One of: ``md5``, ``sha1``, ``sha256``, ``sha512``.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-compute-hash",
     "arguments": {
       "input": "hello",
       "algorithm": "sha256"
     }
   }

Response:

.. code-block:: json

   {
     "algorithm": "sha256",
     "hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
     "input_length": 5
   }

Errors
^^^^^^

- **Unknown algorithm** -- only ``md5``, ``sha1``, ``sha256``, and ``sha512``
  are supported. Any other value is rejected.
- **Input too long** -- extremely large input strings are rejected to prevent
  abuse. Keep inputs within reasonable bounds.


apicrate-hash-password
----------------------

Hash a password using a slow key derivation function (KDF). These algorithms are
intentionally slow to resist brute-force attacks. Use this for storing passwords
securely -- not for general-purpose hashing (use ``apicrate-compute-hash`` for
that).

**Credit cost:** 2 credits per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``password``
     - string
     - yes
     - The password to hash.
   * - ``algorithm``
     - string
     - yes
     - KDF algorithm. One of: ``bcrypt``, ``scrypt``, ``argon2id``.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-hash-password",
     "arguments": {
       "password": "s3cr3t",
       "algorithm": "bcrypt"
     }
   }

Response:

.. code-block:: json

   {
     "algorithm": "bcrypt",
     "hash": "$2b$12$LJ3m4ys3Lg2dCMkwNYKRce8XQGbHwMEQ7RZsG6H9NKPw0aBvf5KxW",
     "parameters": {
       "rounds": 12
     }
   }

Errors
^^^^^^

- **Unknown algorithm** -- only ``bcrypt``, ``scrypt``, and ``argon2id`` are
  supported. These are KDF algorithms, not digest algorithms -- do not pass
  ``sha256`` or similar here (use ``apicrate-compute-hash`` instead).
- **Input too long** -- very long passwords are rejected. Note that ``bcrypt``
  has a built-in 72-byte input limit; inputs exceeding this are truncated or
  rejected depending on the implementation.