Bitrix API

Otp

Constants

REJECT_BY_CODE = 'code'
REJECT_BY_MANDATORY = 'mandatory'
REJECTED_KEY = 'OTP_REJECT_REASON'
SECRET_LENGTH = 20
SKIP_COOKIE = 'OTPH'
TAGGED_CACHE_TEMPLATE = 'USER_OTP_%d'
TYPE_DEFAULT = self::TYPE_HOTP
TYPE_HOTP = 'hotp'
TYPE_TOTP = 'totp'

Methods

__construct() : mixed
activate() : $this: Activates user's OTP.
canSkipMandatory() : bool: Check if current user can skip OTP mandatory using.
canSkipMandatoryByRights() : bool: Check if current user not included to mandatory rights
deactivate() : $this: Deactivate user OTP for a needed number of days or forever
defer() : $this: Defer mandatory user OTP using for a needed number of days or forever
delete() : $this: Delete OTP record from DB
getAlgorithm() : OtpAlgorithm: Return instance of used OtpAlgorithm
getAppSecret() : string: Return mobile application secret, using for manual device initialization
getAttempts() : int: Return verifying attempts count
getAvailableTypes() : array<string|int, mixed>: Return available OtpAlgorithm types
getByType() : static: Return new instance with needed OtpAlgorithm type
getByUser() : static: Return new instance for user provided by user ID
getContext() : Context: Returns context of the current request.
getDeactivateUntil() : DateTime
getDefaultType() : string: Return default OtpAlgorithm type
getDeferredParams() : array<string|int, mixed>|null: Return deferred params (see verifyUser)
getHexSecret() : string: Return hex-encoded secret
getInitialDate() : DateTime: Returns OTP initialization date
getInitParams() : array<string|int, mixed>: Returns initialization parameters for algorithms.
getIssuer() : string: Return issuer.
getLabel() : string: Return label for issuer (if provided) If custom label not available - generate default (see generateLabel)
getMandatoryRights() : array<string|int, mixed>: Return user rights who must use OTP in mandatory way
getParams() : string: Return user params (e.g. counter for HotpAlgorithm)
getProvisioningUri() : string: Return Provision URI according to KeyUriFormat
getSecret() : string: Return binary secret
getSkipMandatoryDays() : int: Return initialization window (in days) for mandatory using checking
getSyncParameters() : string: Return synchronized user params for provided inputs
getType() : string: Return used OtpAlgorithm type
getTypesDescription() : array<string|int, mixed>: Return available OtpAlgorithm types description
getUserId() : int: Return used User ID
getUserLogin() : string: Return user login If custom login not available it will be fetched from DB
isActivated() : bool: Return is OTP activated or not
isAttemptsReached() : bool: Check is verifying attempts reached according to group security policy May be used for show Captcha or what ever you want
isCaptchaRequired() : bool: Return if user must provide captcha code before checking OTP password
isInitialized() : bool
isMandatorySkipped() : bool: Returns true if user can skip mandatory using
isMandatoryUsing() : bool: Return is mandatory OTP using activated
isOtpEnabled() : bool: Returns if OTP enabled
isOtpRequired() : bool: Returns true if user must provide password from device
isOtpRequiredByMandatory() : bool: Returns true if user doesn't use OTP, but it required and grace full period ends
isRecoveryCodesEnabled() : bool: Returns if "Recovery codes" are enabled
isUserActive() : mixed
regenerate() : $this: Reinitialize OTP (generate new secret, set default algo, etc), must be called before connect new device
save() : bool: Save all OTP data to DB
setActive() : $this: Set new activating state
setAppSecret() : $this: Set new mobile application secret
setContext() : $this: Set context of the current request.
setDefaultType() : void: Set default OtpAlgorithm type
setDeferredParams() : void: Set or delete deferred params (see verifyUser)
setHexSecret() : $this: Set new secret in hex-encoded representation
setInitParams() : $this: Sets initialization parameters for algorithms.
setIssuer() : $this: Set custom issuer
setLabel() : $this: Set custom label
setMandatoryRights() : void: Set user rights who must use OTP in mandatory way
setMandatoryUsing() : void: Activate or deactivate mandatory OTP using
setSecret() : $this: Set new secret
setSkipMandatoryDays() : void: Set initialization window (in days) for mandatory using checking
setType() : $this: Set new type of OtpAlgorithm
setUserActive() : mixed
setUserInfo() : $this: Set new user information Mostly used for initialization from DB Now support: - ACTIVE: bool, activating state (see setActive) - USER_ID: integer, User ID (see setUserId) - ATTEMPTS: integer, Attempts counter (see setAttempts) - SECRET: binary, User secret (see setSecret) - PARAMS: string, User params (see setParams and getSyncParameters) - INITIAL_DATE: Type\Date, OTP initial date (see setInitialDate)
setUserLogin() : $this: Set custom user login
syncParameters() : $this: Synchronize user params for provided inputs Must be called after regenerate and before save! If something went wrong - throw OtpException with valid description in message
verify() : bool: Verify provided input
verifyUser() : bool: Most complex method, can check everything:-) ToDo: describe after refactoring

REJECT_BY_CODE


    public
        mixed
    REJECT_BY_CODE
    = 'code'

REJECT_BY_MANDATORY


    public
        mixed
    REJECT_BY_MANDATORY
    = 'mandatory'

REJECTED_KEY


    public
        mixed
    REJECTED_KEY
    = 'OTP_REJECT_REASON'

SECRET_LENGTH


    public
        mixed
    SECRET_LENGTH
    = 20

SKIP_COOKIE


    public
        mixed
    SKIP_COOKIE
    = 'OTPH'

TAGGED_CACHE_TEMPLATE


    public
        mixed
    TAGGED_CACHE_TEMPLATE
    = 'USER_OTP_%d'

TYPE_DEFAULT


    public
        mixed
    TYPE_DEFAULT
    = self::TYPE_HOTP

TYPE_HOTP


    public
        mixed
    TYPE_HOTP
    = 'hotp'

TYPE_TOTP


    public
        mixed
    TYPE_TOTP
    = 'totp'

__construct()


    public
                    __construct([string|null $algorithm = null ]) : mixed

Parameters

$algorithm : string|null = null: Class of needed OtpAlgorithm.

activate()

Activates user's OTP.


    public
                    activate() : $this

OTP must be initialized (have secret, params, etc.) before activate

Return values

$this

canSkipMandatory()

Check if current user can skip OTP mandatory using.


    public
                    canSkipMandatory() : bool

It can skip if:

Otp already activated
User never login before
User not included to mandatory rights
The current date is included in the window initialization

Return values

bool

canSkipMandatoryByRights()

Check if current user not included to mandatory rights


    public
                    canSkipMandatoryByRights() : bool

Return values

bool

deactivate()

Deactivate user OTP for a needed number of days or forever


    public
                    deactivate([int $days = 0 ]) : $this

Parameters

$days : int = 0: Days. 0 means "forever".

Return values

$this

defer()

Defer mandatory user OTP using for a needed number of days or forever


    public
                    defer([int $days = 0 ]) : $this

Parameters

$days : int = 0: Days. 0 means "forever".

Return values

$this

delete()

Delete OTP record from DB


    public
                    delete() : $this

Return values

$this

getAlgorithm()

Return instance of used OtpAlgorithm


    public
                    getAlgorithm() : OtpAlgorithm

Return values

OtpAlgorithm

getAppSecret()

Return mobile application secret, using for manual device initialization


    public
                    getAppSecret() : string

Return values

string

getAttempts()

Return verifying attempts count


    public
                    getAttempts() : int

Return values

int

getAvailableTypes()

Return available OtpAlgorithm types


    public
            static        getAvailableTypes() : array<string|int, mixed>

Return values

array<string|int, mixed>

getByType()

Return new instance with needed OtpAlgorithm type


    public
            static        getByType(string $type) : static

Parameters

$type : string: Type of OtpAlgorithm (see getAvailableTypes).

Return values

static —

New instance

getByUser()

Return new instance for user provided by user ID


    public
            static        getByUser(int $userId) : static

Parameters

$userId : int: User ID.

Return values

static —

New instance, if user does not use OTP - returning NullObject (see Otp::isActivated).

getContext()

Returns context of the current request.


    public
                    getContext() : Context

Return values

Context

getDeactivateUntil()


    public
                    getDeactivateUntil() : DateTime

Return values

DateTime

getDefaultType()

Return default OtpAlgorithm type


    public
            static        getDefaultType() : string

Return values

string

getDeferredParams()

Return deferred params (see verifyUser)


    public
            static        getDeferredParams() : array<string|int, mixed>|null

Return values

array<string|int, mixed>|null

getHexSecret()

Return hex-encoded secret


    public
                    getHexSecret() : string

Return values

string

getInitialDate()

Returns OTP initialization date


    public
                    getInitialDate() : DateTime

Return values

DateTime

getInitParams()

Returns initialization parameters for algorithms.


    public
                    getInitParams() : array<string|int, mixed>

Return values

array<string|int, mixed>

getIssuer()

Return issuer.


    public
                    getIssuer() : string

If custom issuer not available - return default (see getDefaultIssuer).

Return values

string

getLabel()

Return label for issuer (if provided) If custom label not available - generate default (see generateLabel)


    public
                    getLabel([string|null $issuer = null ]) : string

Parameters

$issuer : string|null = null: Issuer.

Return values

string

getMandatoryRights()

Return user rights who must use OTP in mandatory way


    public
            static        getMandatoryRights() : array<string|int, mixed>

Return values

array<string|int, mixed>

getParams()

Return user params (e.g. counter for HotpAlgorithm)


    public
                    getParams() : string

Return values

string

getProvisioningUri()

Return Provision URI according to KeyUriFormat


    public
                    getProvisioningUri([array<string|int, mixed> $opts = array() ]) : string

Parameters

$opts : array<string|int, mixed> = array(): Additional URI parameters, e.g. ['image' => 'http://example.com/my_logo.png'] .

Return values

string

getSecret()

Return binary secret


    public
                    getSecret() : string

Return values

string

getSkipMandatoryDays()

Return initialization window (in days) for mandatory using checking


    public
            static        getSkipMandatoryDays() : int

Return values

int

getSyncParameters()

Return synchronized user params for provided inputs


    public
                    getSyncParameters(string $inputA, string $inputB) : string

Parameters

$inputA : string: First code.
$inputB : string: Second code.

Return values

string

getType()

Return used OtpAlgorithm type


    public
                    getType() : string

Return values

string

getTypesDescription()

Return available OtpAlgorithm types description


    public
            static        getTypesDescription() : array<string|int, mixed>

Return values

array<string|int, mixed>

getUserId()

Return used User ID


    public
                    getUserId() : int

Return values

int

getUserLogin()

Return user login If custom login not available it will be fetched from DB


    public
                    getUserLogin() : string

Return values

string

isActivated()

Return is OTP activated or not


    public
                    isActivated() : bool

Return values

bool

isAttemptsReached()

Check is verifying attempts reached according to group security policy May be used for show Captcha or what ever you want


    public
                    isAttemptsReached() : bool

Return values

bool

isCaptchaRequired()

Return if user must provide captcha code before checking OTP password


    public
            static        isCaptchaRequired() : bool

Return values

bool

isInitialized()


    public
                    isInitialized() : bool

Return values

bool

isMandatorySkipped()

Returns true if user can skip mandatory using


    public
                    isMandatorySkipped() : bool

Return values

bool

isMandatoryUsing()

Return is mandatory OTP using activated


    public
            static        isMandatoryUsing() : bool

Return values

bool

isOtpEnabled()

Returns if OTP enabled


    public
            static        isOtpEnabled() : bool

Return values

bool

isOtpRequired()

Returns true if user must provide password from device


    public
            static        isOtpRequired() : bool

Return values

bool

isOtpRequiredByMandatory()

Returns true if user doesn't use OTP, but it required and grace full period ends


    public
            static        isOtpRequiredByMandatory() : bool

Return values

bool

isRecoveryCodesEnabled()

Returns if "Recovery codes" are enabled


    public
            static        isRecoveryCodesEnabled() : bool

Return values

bool

isUserActive()


    public
                    isUserActive() : mixed

regenerate()

Reinitialize OTP (generate new secret, set default algo, etc), must be called before connect new device


    public
                    regenerate([null $newSecret = null ]) : $this

Parameters

$newSecret : null = null: Using custom secret.

Return values

$this

save()

Save all OTP data to DB


    public
                    save() : bool

Return values

bool

setActive()

Set new activating state


    public
                    setActive(bool $isActive) : $this

Parameters

$isActive : bool: Otp is activated or not.

Return values

$this

setAppSecret()

Set new mobile application secret


    public
                    setAppSecret(string $value) : $this

Parameters

$value : string: Secret.

Return values

$this

setContext()

Set context of the current request.


    public
                    setContext(Context $context) : $this

Parameters

$context : Context: Application context.

Return values

$this

setDefaultType()

Set default OtpAlgorithm type


    public
            static        setDefaultType(string $value) : void

Parameters

$value : string: OtpAlgorithm type (see getAvailableTypes).

setDeferredParams()

Set or delete deferred params (see verifyUser)


    public
            static        setDeferredParams(array<string|int, mixed>|null $params) : void

Parameters

$params : array<string|int, mixed>|null: Params, null means deleting params from storage.

setHexSecret()

Set new secret in hex-encoded representation


    public
                    setHexSecret(string $hexValue) : $this

Parameters

$hexValue : string: Hex-encoded secret.

Return values

$this

setInitParams()

Sets initialization parameters for algorithms.


    public
                    setInitParams(array<string|int, mixed> $params) : $this

Parameters

$params : array<string|int, mixed>

Return values

$this

setIssuer()

Set custom issuer


    public
                    setIssuer(string $issuer) : $this

Parameters

$issuer : string: Issuer.

Return values

$this

setLabel()

Set custom label


    public
                    setLabel(string $label) : $this

Parameters

$label : string: Label.

Return values

$this

setMandatoryRights()

Set user rights who must use OTP in mandatory way


    public
            static        setMandatoryRights(array<string|int, mixed> $rights) : void

Parameters

$rights : array<string|int, mixed>: Needed rights. E.g. ['G1'] for administrators.

setMandatoryUsing()

Activate or deactivate mandatory OTP using


    public
            static        setMandatoryUsing([bool $isMandatory = true ]) : void

Parameters

$isMandatory : bool = true: Active or not.

setSecret()

Set new secret


    public
                    setSecret(string $secret) : $this

Parameters

$secret : string: Binary secret.

Return values

$this

setSkipMandatoryDays()

Set initialization window (in days) for mandatory using checking


    public
            static        setSkipMandatoryDays([int $days = 2 ]) : void

Parameters

$days : int = 2: Days of initialization window. "0" means immediately (on next user authorization).

setType()

Set new type of OtpAlgorithm


    public
                    setType(string $type) : $this

Parameters

$type : string: Type of OtpAlgorithm (see getAvailableTypes).

Return values

$this

setUserActive()


    public
                    setUserActive(mixed $isActive) : mixed

Parameters

$isActive : mixed

setUserInfo()

Set new user information Mostly used for initialization from DB Now support: - ACTIVE: bool, activating state (see setActive) - USER_ID: integer, User ID (see setUserId) - ATTEMPTS: integer, Attempts counter (see setAttempts) - SECRET: binary, User secret (see setSecret) - PARAMS: string, User params (see setParams and getSyncParameters) - INITIAL_DATE: Type\Date, OTP initial date (see setInitialDate)


    public
                    setUserInfo(array<string|int, mixed> $userInfo) : $this

Parameters

$userInfo : array<string|int, mixed>: See above.

Return values

$this

setUserLogin()

Set custom user login


    public
                    setUserLogin(string $login) : $this

Parameters

$login : string: Login.

Return values

$this

syncParameters()

Synchronize user params for provided inputs Must be called after regenerate and before save! If something went wrong - throw OtpException with valid description in message


    public
                    syncParameters(string $inputA[, string|null $inputB = null ]) : $this

Parameters

$inputA : string: First code.
$inputB : string|null = null: Second code.

Return values

$this

verify()

Verify provided input


    public
                    verify(string $input[, bool $updateParams = true ]) : bool

Parameters

$input : string: Input received from user.
$updateParams : bool = true: Update or not user parameters in DB (e.g. counter for HotpAlgorithm).

Return values

bool —

True if input is valid.

verifyUser()

Most complex method, can check everything:-) ToDo: describe after refactoring


    public
            static        verifyUser(array<string|int, mixed> $params) : bool

Parameters

$params : array<string|int, mixed>: Event parameters.

Return values

bool

Otp

Table of Contents

Constants

Methods

Constants

REJECT_BY_CODE

REJECT_BY_MANDATORY

REJECTED_KEY

SECRET_LENGTH

SKIP_COOKIE

TAGGED_CACHE_TEMPLATE

TYPE_DEFAULT

TYPE_HOTP

TYPE_TOTP

Methods

__construct()

Parameters

activate()

Tags

Return values

canSkipMandatory()

Return values

canSkipMandatoryByRights()

Return values

deactivate()

Parameters

Tags

Return values

defer()

Parameters

Tags

Return values

delete()

Return values

getAlgorithm()

Return values

getAppSecret()

Return values

getAttempts()

Return values

getAvailableTypes()

Return values

getByType()

Parameters

Tags

Return values

getByUser()

Parameters

Tags

Return values

getContext()

Return values

getDeactivateUntil()

Return values

getDefaultType()

Return values

getDeferredParams()

Return values

getHexSecret()

Return values

getInitialDate()

Return values

getInitParams()

Return values

getIssuer()

Return values

getLabel()

Parameters

Return values

getMandatoryRights()

Return values

getParams()

Return values

getProvisioningUri()

Parameters

Tags

Return values

getSecret()

Return values

getSkipMandatoryDays()