AiWriteConfirmation Class Reference

Class AiWriteConfirmation. More...

Collaboration diagram for AiWriteConfirmation:

Public Member Functions
	__construct ($db)
	Constructor.
	issue ($user, $toolName, array $args, $preview)
	Issue a state for a pending write.
	consume ($user, $toolName, array $args, $state)
	Validate a state presented on the confirming call, and consume it.
	purge ($keepdays=30)
	Remove expired states that were never confirmed.

Public Attributes
const	DEFAULT_TTL_MINUTES = 10
	Minutes a state stays valid, long enough to read a preview.

Private Member Functions
	signingSecret ()
	Secret used to sign states.
	stateHash ($state, $secret)
	Keyed hash of a state, so the database never holds the state itself.
	argsHash (array $args)
	Stable hash of the arguments a state was issued for.
	ksortRecursive (array &$arr)
	Sort an array by key at every level, so argument order cannot change the hash.

Detailed Description

Class AiWriteConfirmation.

A write tool does not execute on the first call: it answers with a preview and an opaque requestState, and executes only when the caller comes back with that state. The state is signed with an instance secret, expires, is single use and is bound to the arguments it was issued for, so a caller can neither forge a confirmation nor confirm one set of arguments and send another.

Definition at line 33 of file writeconfirmation.class.php.

Constructor & Destructor Documentation

__construct()

AiWriteConfirmation::__construct

(

$db

)

Constructor.

Parameters

DoliDB

$db

Database handler.

Definition at line 55 of file writeconfirmation.class.php.

Member Function Documentation

argsHash()

AiWriteConfirmation::argsHash ( array $args )

private

Stable hash of the arguments a state was issued for.

Parameters

array<string,mixed>

$args Tool arguments.

Returns

string Hash.

Definition at line 249 of file writeconfirmation.class.php.

References dol_hash(), and ksortRecursive().

Referenced by issue().

consume()

AiWriteConfirmation::consume	(		$user,
			$toolName,
		array	$args,
			$state )

Validate a state presented on the confirming call, and consume it.

Everything is checked before the write runs: the signature, that the state belongs to this user, this tool and these arguments, that it has not expired and that it was never used before.

Parameters

User	$user	User confirming.
string	$toolName	Tool being confirmed.
	array<string,mixed>	$args Arguments presented now.
string	$state	State the caller echoed back.

Returns

bool True when the write may proceed.

Definition at line 128 of file writeconfirmation.class.php.

References $conf, dol_now(), dol_syslog(), signingSecret(), and stateHash().

issue()

AiWriteConfirmation::issue	(		$user,
			$toolName,
		array	$args,
			$preview )

Issue a state for a pending write.

Parameters

User	$user	User asking for the write.
string	$toolName	Tool that would run.
	array<string,mixed>	$args Arguments it would run with.
string	$preview	Human readable description of what would be written.

Returns

string Opaque state to hand to the caller, '' on failure.

Definition at line 69 of file writeconfirmation.class.php.

References $conf, argsHash(), DEFAULT_TTL_MINUTES, dol_hash(), dol_now(), dol_syslog(), dol_trunc(), getDolGlobalInt(), getUserRemoteIP(), purge(), signingSecret(), and stateHash().

ksortRecursive()

AiWriteConfirmation::ksortRecursive ( array & $arr )

private

Sort an array by key at every level, so argument order cannot change the hash.

Parameters

array<string,mixed>

$arr Array to sort in place.

Returns

void

Definition at line 264 of file writeconfirmation.class.php.

References ksortRecursive().

Referenced by argsHash(), and ksortRecursive().

purge()

AiWriteConfirmation::purge

(

$keepdays = 30

)

Remove expired states that were never confirmed.

Parameters

int

$keepdays

Days of history to keep for audit.

Returns

int Rows deleted, -1 on error.

Definition at line 196 of file writeconfirmation.class.php.

References dol_now().

Referenced by issue().

signingSecret()

AiWriteConfirmation::signingSecret ( )

private

Secret used to sign states.

Derived from the instance id Dolibarr already uses for session prefixes, so there is nothing to generate and the value stays in conf.php rather than in the database. Empty when the installation predates it, in which case no state is issued at all.

Returns

string Secret, '' when the installation has none.

Definition at line 219 of file writeconfirmation.class.php.

References dol_hash().

Referenced by consume(), and issue().

stateHash()

AiWriteConfirmation::stateHash ( $state, $secret )

private

Keyed hash of a state, so the database never holds the state itself.

Parameters

string	$state	State handed to the caller.
string	$secret	Instance secret.

Returns

string Hash stored and looked up.

Definition at line 238 of file writeconfirmation.class.php.

References dol_hash().

Referenced by consume(), and issue().

---

The documentation for this class was generated from the following file:

• dolibarr_dev/htdocs/ai/class/writeconfirmation.class.php