OpaqueNativeInterface
in
The `libaxiam_opaque_ffi` C ABI, expressed in PHP terms.
An interface rather than the FFI calls themselves, for one reason: it is what a test can implement. CONTRACT.md §23.1 forbids this SDK from implementing OPAQUE, so there is no cryptography here to test — what there is, and what a fake can exercise exhaustively, is the layer above: single-use exchanges, the key-stretching function the server named being the one used, and which failure means what.
The methods take and return PHP strings rather than pointers. Pointer ownership — who frees a
returned char *, when a state handle is spent — is real but is entirely
FfiOpaqueNative's, because it is the only implementation that has pointers at all. That
keeps the untestable-without-the-real-library part as small as it can be.
A null return always means the library refused; self::lastError() says why.
Table of Contents
Methods
- available() : bool
- Whether this build can perform OPAQUE.
- ksfArgon2id() : object|int|null
- Builds an Argon2id key-stretching handle.
- ksfFree() : void
- Releases a key-stretching handle.
- ksfScrypt() : object|int|null
- Builds a scrypt key-stretching handle.
- lastError() : string
- The library's description of the last failure, or an empty string.
- loginFinish() : string|null
- Completes a login, CONSUMING `$state`.
- loginFree() : void
- Releases login state that was never finished.
- loginStart() : array{0: mixed, 1: string}|null
- Begins a login.
- registrationFinish() : string|null
- Completes an enrolment, CONSUMING `$state` whether it succeeds or fails.
- registrationFree() : void
- Releases enrolment state that was never finished.
- registrationStart() : array{0: mixed, 1: string}|null
- Begins an enrolment.
Methods
available()
Whether this build can perform OPAQUE.
public
available() : bool
Return values
boolksfArgon2id()
Builds an Argon2id key-stretching handle.
public
ksfArgon2id(int $memoryKib, int $iterations, int $parallelism) : object|int|null
Parameters
- $memoryKib : int
- $iterations : int
- $parallelism : int
Return values
object|int|null —an opaque handle the caller passes back, or null when refused
ksfFree()
Releases a key-stretching handle.
public
ksfFree(mixed $ksf) : void
Parameters
- $ksf : mixed
ksfScrypt()
Builds a scrypt key-stretching handle.
public
ksfScrypt(int $logN, int $r, int $p) : object|int|null
Parameters
- $logN : int
- $r : int
- $p : int
Return values
object|int|null —an opaque handle the caller passes back, or null when refused
lastError()
The library's description of the last failure, or an empty string.
public
lastError() : string
Return values
stringloginFinish()
Completes a login, CONSUMING `$state`.
public
loginFinish(mixed $state, string $password, string $ke2, mixed $ksf) : string|null
A null return is the whole of the client's authentication check, and it covers both halves
of the mutual authentication: the envelope only opens under the right password, and KE2's
MAC only verifies if the server actually holds the record. Per CONTRACT.md §23.4 rule 7
nothing may be sent to login/finish after it.
Parameters
- $state : mixed
- $password : string
- $ke2 : string
- $ksf : mixed
Return values
string|null —the hex KE3, or null
loginFree()
Releases login state that was never finished.
public
loginFree(mixed $state) : void
Parameters
- $state : mixed
loginStart()
Begins a login.
public
loginStart(string $password) : array{0: mixed, 1: string}|null
Parameters
- $password : string
Return values
array{0: mixed, 1: string}|null —the state handle and the hex KE1, or null when
refused
registrationFinish()
Completes an enrolment, CONSUMING `$state` whether it succeeds or fails.
public
registrationFinish(mixed $state, string $password, string $registrationResponse, mixed $ksf) : string|null
Parameters
- $state : mixed
- $password : string
- $registrationResponse : string
- $ksf : mixed
Return values
string|null —the hex RegistrationRecord, or null when refused
registrationFree()
Releases enrolment state that was never finished.
public
registrationFree(mixed $state) : void
Parameters
- $state : mixed
registrationStart()
Begins an enrolment.
public
registrationStart(string $password) : array{0: mixed, 1: string}|null
Parameters
- $password : string
Return values
array{0: mixed, 1: string}|null —the state handle and the hex RegistrationRequest,
or null when refused