PARAMETER_HASH

Also known as

param (with or without @ prefix)

Hash one parameter value using another parameter as the hash input. This annotation is commonly used to create user registration endpoints that securely store hashed passwords in the database.

Syntax

@param <target_param> is hash of <source_param>
@parameter <target_param> is hash of <source_param>

• target_param: The parameter that will receive the hashed value.
• source_param: The parameter whose value will be hashed.

Examples

Simple User Registration

create function register(_email text, _password text, _hash text)
returns int
language sql as $$
insert into users (email, password_hash) values (_email, _hash) returning id
$$;

comment on function register(text, text, text) is '
@param _hash is hash of _password
';

User Registration with Response

create function create_user(
    _username text,
    _password text,
    _password_hash text
)
returns json
language sql as $$
insert into users (username, password_hash)
values (_username, _password_hash)
returning json_build_object('id', id, 'username', username);
$$;

comment on function create_user(text, text, text) is '
HTTP POST
@param _password_hash is hash of _password
';

When called with {"username": "john", "password": "secret123"}:

• _password receives the plain text "secret123"
• _password_hash receives the hashed value of "secret123"

Behavior

• The hash is computed using the built-in password hasher.
• The source parameter value remains unchanged and can still be used in the function.
• The target parameter receives the hashed value before the function is executed.
• Both parameters must exist in the function signature.
• This is typically used for securely storing passwords without exposing them in plain text in the database.

Built-in Password Hasher

The default password hasher uses PBKDF2 (Password-Based Key Derivation Function 2) with:

• SHA-256 algorithm
• 128-bit salt
• 600,000 iterations (OWASP-recommended as of 2025)

This provides secure password hashing out of the box. A custom IPasswordHasher implementation can be injected in source code if needed.

Complete Registration and Login Flow

The param is hash of annotation works together with the LOGIN annotation to provide a complete authentication flow using the same built-in password hasher:

1. Registration: Use param <target> is hash of <source> to hash passwords before storing them
2. Login: Return the stored hash in a hash column and NpgsqlRest verifies it automatically

Registration Function

create function register(_email text, _password text, _hash text)
returns int
language sql as $$
insert into users (email, password_hash) values (_email, _hash) returning id
$$;

comment on function register(text, text, text) is '
HTTP POST /auth/register
@param _hash is hash of _password
@sensitive
';

Login Function

create function login(_email text, _password text)
returns table(hash text, id int, name text, email text)
language sql as $$
select u.password_hash as hash, u.id, u.name, u.email
from users u where u.email = _email
$$;

comment on function login(text, text) is '
HTTP POST /auth/login
@login
@sensitive
';

Both functions use the same PBKDF2 hasher, ensuring passwords hashed during registration can be verified during login.

Related

• Authentication Options configuration - Configure password hasher
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Related Annotations

• LOGIN - Authentication endpoint that verifies hashed passwords
• BASIC_AUTH - Basic authentication with hashed passwords
• SECURITY_SENSITIVE - Obfuscate parameter values in logs