Piwik\
Nonce class.
A cryptographic nonce -- "number used only once" -- is often recommended as part of a robust defense against cross-site request forgery (CSRF/XSRF). This class provides static methods that create and manage nonce values.
Nonces in Matomo (formerly Piwik) are stored as a session variable and have a configurable expiration.
Learn more about nonces here.
The class defines the following methods:
getNonce()
— Returns an existing nonce by ID.verifyNonce()
— Returns if a nonce is valid and comes from a valid request.isReferrerHostValid()
discardNonce()
— Force expiration of the current nonce.getOrigin()
— Returns the Origin HTTP header or false
if not found.getAcceptableOrigins()
— Returns a list acceptable values for the HTTP Origin header.checkNonce()
— Verifies and discards a nonce.getNonce()
Returns an existing nonce by ID. If none exists, a new nonce will be generated.
$id
(string
) —
Unique id to avoid namespace conflicts, e.g., 'ModuleName.ActionName'
.$ttl
(int
) —
Optional time-to-live in seconds; default is 5 minutes. (ie, in 5 minutes, the nonce will no longer be valid).string
value.verifyNonce()
Returns if a nonce is valid and comes from a valid request.
A nonce is valid if it matches the current nonce and if the current nonce has not expired.
The request is valid if the referrer is a local URL (see Url::isLocalUrl()) and if the HTTP origin is valid (see getAcceptableOrigins()).
It accepts the following parameter(s):
$id
(string
) —
The nonce's unique ID. See getNonce().$cnonce
(string
) —
Nonce sent from client.$expectedReferrerHost
(string
) —
The expected referrer host for the HTTP referrer URL.Returns: bool
—
true
if valid; false
otherwise.
isReferrerHostValid()
It accepts the following parameter(s):
$referrer
$expectedReferrerHost
It does not return anything or a mixed result.
discardNonce()
Force expiration of the current nonce.
$id
(string
) —
The unique nonce ID.getOrigin()
Returns the Origin HTTP header or false
if not found.
string
|bool
—getAcceptableOrigins()
Returns a list acceptable values for the HTTP Origin header.
array
value.checkNonce()
Verifies and discards a nonce.
It accepts the following parameter(s):
$nonceName
$nonce
$expectedReferrerHost
It does not return anything or a mixed result.
Exception
— if the nonce is invalid. See {@link verifyNonce()}.