auth.h File Reference

RFC 2617 Digest authentication for RTSP. More...

#include <compy/types/header_map.h>
#include <stdbool.h>
#include <stddef.h>
#include <slice99.h>
#include <compy/priv/compiler_attrs.h>
#include <compy/types/request.h>

Include dependency graph for auth.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct Compy_Context	Compy_Context
typedef bool(*	Compy_CredentialLookup) (const char *username, char *password_out, size_t password_max, void *user_data)
	Credential lookup callback.
typedef struct Compy_Auth	Compy_Auth
	Digest authentication context.

Functions
Compy_Auth *	Compy_Auth_new (const char *realm, Compy_CredentialLookup lookup, void *user_data) COMPY_PRIV_MUST_USE
	Creates a new Digest authentication context.
void	Compy_Auth_free (Compy_Auth *self)
	Frees an authentication context.
int	compy_auth_check (Compy_Auth *self, Compy_Context *ctx, const Compy_Request *req) COMPY_PRIV_MUST_USE
	Validates the request's Authorization header.
void	compy_digest_response (char out[restrict 33], const char *username, const char *realm, const char *password, const char *nonce, const char *method, const char *uri)
	Computes the MD5 Digest response hash per RFC 2617 Section 3.2.2.

Detailed Description

RFC 2617 Digest authentication for RTSP.

Provides server-side Digest authentication as required by ONVIF and most NVR/VMS systems. The application supplies a credential lookup function; the library handles nonce generation, digest validation, and 401 challenge responses.

Typical usage in a Controller's before() hook:

if (compy_auth_check(auth, ctx, req) != 0) {
    return Compy_ControlFlow_Break;  // 401 already sent
}
return Compy_ControlFlow_Continue;

Typedef Documentation

Compy_CredentialLookup

typedef bool(* Compy_CredentialLookup) (const char *username, char *password_out, size_t password_max, void *user_data)

Credential lookup callback.

Given a username, writes the corresponding password into password_out (up to password_max bytes including null terminator).

Parameters

[in]	username	The username to look up.
[out]	password_out	Buffer to write the password into.
[in]	password_max	Size of password_out.
[in]	user_data	Application-provided context pointer.

Returns

true if the user exists and password_out was written, false if the user is not found.

Function Documentation

compy_auth_check()

int compy_auth_check	(	Compy_Auth *	self,
		Compy_Context *	ctx,
		const Compy_Request *	req
	)

Validates the request's Authorization header.

If no Authorization header is present or the credentials are invalid, sends a 401 Unauthorized response with a WWW-Authenticate challenge header and returns -1. The caller should then return Compy_ControlFlow_Break from the before() hook.

If the credentials are valid, returns 0 and the caller should return Compy_ControlFlow_Continue.

Parameters

[in]	self	The auth context.
[in]	ctx	The RTSP request context (used to send 401 if needed).
[in]	req	The incoming RTSP request.

Precondition

self != NULL

ctx != NULL

req != NULL

Returns

0 if authenticated, -1 if not (401 already sent).

Compy_Auth_free()

void Compy_Auth_free

(

Compy_Auth *

self

)

Frees an authentication context.

Precondition

self != NULL

Compy_Auth_new()

Compy_Auth * Compy_Auth_new	(	const char *	realm,
		Compy_CredentialLookup	lookup,
		void *	user_data
	)

Creates a new Digest authentication context.

Parameters

[in]	realm	The authentication realm (e.g., "IP Camera").
[in]	lookup	The credential lookup callback.
[in]	user_data	Opaque pointer passed to lookup.

Precondition

realm != NULL

lookup != NULL

compy_digest_response()

void compy_digest_response	(	char	out[restrict 33],
		const char *	username,
		const char *	realm,
		const char *	password,
		const char *	nonce,
		const char *	method,
		const char *	uri
	)

Computes the MD5 Digest response hash per RFC 2617 Section 3.2.2.

response = MD5(MD5(username:realm:password):nonce:MD5(method:uri))

Parameters

[out]	out	Output buffer, must be at least 33 bytes (32 hex + null).
[in]	username	The username.
[in]	realm	The authentication realm.
[in]	password	The password.
[in]	nonce	The server-generated nonce.
[in]	method	The RTSP method (e.g., "DESCRIBE").
[in]	uri	The request URI.