Files
zeekay 45126f763c hanzo_iam: an OAuth validator that admits hanzo-sql tokens
A connection that chooses the oauth method presents a token signed RS256 by
the sql key. Trust is the <kid>.pem public files in hanzo_iam.dir, read on
every connection, so a removed file revokes its key at once; nothing here
calls IAM. The key must be RSA of 2048 bits or more, in a file of at most
16 KiB.

The token is at most 8192 bytes, and each of its three parts decodes into a
buffer with its own capacity, so the size check is not the only bound. iss is
https://hanzo.id, aud holds hanzo-sql, typ is sql (a claim; the JOSE header's
typ is not read), act is absent, sub is sql:<role>, exp and iat are required,
exp is at most 60 s past, iat and nbf (optional) at most 60 s ahead, and
exp - iat is at most 600 s. The claims are not parsed until the signature
verifies. JSON is read with PostgreSQL's jsonapi, escapes decoded, and a
member a check names may appear once however it is spelled.

authn_id is the role, and the connection is authorized only when it equals the
role requested (delegate_ident_mapping=1). A refusal logs one reason from a
fixed list and never names the client's role; a key file that cannot be read
is also named by its path, for the operator.

Built with PGXS against PostgreSQL 18 and copied into the image. The TAP test
signs tokens with keys it makes and checks each refusal by the reason logged:
the size bound at 8192 and 8193 bytes, the key rules (EC, DSA, 1024-bit RSA,
private key, certificate, empty, directory, 16 KiB and over), and JSON escapes
in member names and values. make fuzz builds a libFuzzer target over the
parser, run with -max_len=9500 from seeds on the bound. CI does not run
either; LLM.md says so.

Claude-Session: https://claude.ai/code/session_01SCPMGSQsLNF2YtHFL4bwyp
2026-10-09 10:19:04 -07:00

61 lines
1.9 KiB
C

/*-------------------------------------------------------------------------
*
* token.h
* Check a hanzo-sql token: a compact JWS signed RS256 by the sql key.
*
* The three entry points are pure: they read their arguments and nothing
* else, so the server module and the fuzz target share them. Each returns
* NULL when the input is acceptable and otherwise a static string naming the
* first rule it broke.
*
* Include postgres.h or postgres_fe.h first: int64 comes from it.
*
* contrib/hanzo_iam/token.h
*
*-------------------------------------------------------------------------
*/
#ifndef HANZO_IAM_TOKEN_H
#define HANZO_IAM_TOKEN_H
#include <openssl/evp.h>
#define HANZO_IAM_ISSUER "https://hanzo.id"
#define HANZO_IAM_AUDIENCE "hanzo-sql"
#define HANZO_IAM_TYPE "sql"
#define HANZO_IAM_PREFIX "sql:"
#define HANZO_IAM_MAX_TOKEN 8192 /* bytes of the whole token */
#define HANZO_IAM_MAX_KID 64
#define HANZO_IAM_MAX_ROLE 63
#define HANZO_IAM_SKEW 60 /* seconds of clock difference */
#define HANZO_IAM_LIFETIME 600 /* seconds from iat to exp */
/*
* Returns a new reference to the public key named kid, or NULL. The caller
* frees it.
*/
typedef EVP_PKEY *(*hanzo_iam_keys) (const char *kid, void *arg);
/*
* Check the JOSE header: alg is RS256 and kid names a key file. Copies kid
* into kid[HANZO_IAM_MAX_KID + 1].
*/
extern const char *hanzo_iam_header(const char *json, size_t len, char *kid);
/*
* Check the claims against the time now (seconds since the epoch). Copies
* the role the subject names into role[HANZO_IAM_MAX_ROLE + 1].
*/
extern const char *hanzo_iam_claims(const char *json, size_t len, int64 now,
char *role);
/*
* Check a whole token: its size and shape, the header, the key, the
* signature, and only then the claims.
*/
extern const char *hanzo_iam_check(const char *token, size_t len, int64 now,
hanzo_iam_keys keys, void *arg,
char *role);
#endif /* HANZO_IAM_TOKEN_H */