NAME

otpme-token - manage OTPme authentication tokens

SYNOPSIS

otpme-token [--type token_type] command [options] [token]

DESCRIPTION

otpme-token manages authentication tokens in the OTPme system. Tokens are credentials assigned to users. They are identified by their path: user/token_name (e.g. alice/login).

TOKEN TYPES

hotp
HMAC-based One-Time Password (RFC 4226).

totp
Time-based One-Time Password (RFC 6238).

password
Static password authentication.

ssh
SSH public key authentication.

fido2
FIDO2/WebAuthn hardware authentication.

u2f
U2F hardware authentication.

yubikey_hmac
YubiKey HMAC-SHA1 challenge-response authentication.

yubikey_hotp
YubiKey OATH HOTP authentication.

yubikey_gpg
YubiKey GPG applet authentication.

motp
Mobile OTP (mOTP).

otp_push
Push notification-based OTP.

script_otp
OTP generation via external script.

link
Link to another user's token.

COMMANDS

Token Management

add [-r] token
Add a new token. Requires --type before the command.

For hotp and totp tokens the following extra options are available:

--mode mode
Token mode. Defaults to mode2. In mode2 neither the OTP secret nor the PIN are stored in the token object; the effective OTP secret is derived from the server-side secret together with the PIN. This mode is compatible with the SSO portal, but changing the PIN requires redeploying the token (a new QR code must be scanned). In mode1 the OTP secret is stored directly in the token object, so PIN changes do not require redeployment.

--no-qrcode
Do not display the QR code on token creation.

del token
Delete a token.

show [token]
Display token information.

list [regex]
List tokens, optionally filtered by regex pattern.

enable token
Enable a disabled token.

disable token
Disable a token without deleting it.

rename token new_name
Rename a token.

move [-r] token new_token_path
Move token to another user. Use -r to replace existing token keeping its UUID.

touch token
Re-index the object to fix potential index problems.

Token Configuration

config [-d] token parameter [value]
Set a configuration parameter. Use -d to delete (reset to default).

show_config token [parameter]
Show all configuration parameters.

auto_disable [-u] token time
Set auto-disable time (e.g. "1d" or "09:53 13.06.2023"). Use -u to disable if unused for the given time.

description token [description]
Set token description.

info token [info]
Set free-form info text. If info is omitted, the current info text is opened in the editor specified by the EDITOR environment variable.

dump_info token
Dump the info text to stdout.

test token [otp|password]
Test if given OTP/password can be verified by the token.

temp_password [--generate] [--duration time] [--remove] token [password]
Set, generate or remove a temporary password.

Offline Configuration

enable_offline token
Enable offline usage (caching) of token.

disable_offline token
Disable offline usage (caching) of token.

offline_expiry token expiry
Set offline expiry timeout.

offline_unused_expiry token expiry
Set offline unused expiry timeout.

Session

enable_session_keep token
Enable keeping of login session (e.g. on shutdown).

disable_session_keep token
Disable keeping of login session.

Auth Script

auth_script token script
Change token authorization script.

enable_auth_script token
Enable token authorization script.

disable_auth_script token
Disable token authorization script.

Deploy

Hardware tokens must be deployed before use. Deployment configures the physical device and registers the token in OTPme. Use --type before the command to specify the token type.

deploy --list-token-types****
List deployable token types.

Deploy - FIDO2 and U2F

deploy [-d] [-r] token
Register a FIDO2 or U2F hardware key. The device must be connected and will prompt for a touch.

-r
Replace existing token (keep UUID).

-d
Enable debug output.

Deploy - YubiKey HMAC-SHA1

deploy [-d] [-r] [-n] [-s slot] [token]
Write HMAC-SHA1 configuration to a YubiKey slot.

-s slot
Write configuration to the given YubiKey slot.

-n
Do not reconfigure the YubiKey hardware — only register token data in OTPme.

-r
Replace existing token (keep UUID).

-d
Enable debug output.

Deploy - YubiKey OATH HOTP

deploy [-d] [-r] [-s slot] [token]
Write OATH HOTP configuration to a YubiKey slot.

-s slot
Write configuration to the given YubiKey slot.

-r
Replace existing token (keep UUID).

-d
Enable debug output.

Deploy - YubiKey GPG Applet

deploy [-d] [-r] [-n] [--backup file] [--restore file] [token]
Initialize the GPG applet on a YubiKey and generate RSA keys. Prompts for real name, email, PIN and Admin PIN. Default backup path: /dev/shm/\<username>.gpg.

--backup file
Write GPG backup to file.

--restore file
Restore GPG configuration from backup file.

-n
Do not initialize the GPG applet — only register token data in OTPme.

-r
Replace existing token (keep UUID).

-d
Enable debug output.

Deploy - YubiKey PIV Applet

deploy [-d] [-r] [-n] [--key-len bits] [--backup file] [--restore file] [--restore-from-server] [--backup-key-file file] [--add-user-key] [token]
Initialize the PIV applet on a YubiKey and generate an RSA key. Default backup path: /dev/shm/\<username>_\<token>.pem.

--key-len bits
Generate RSA key with the given key length in bits.

--backup file
Write key backup to file.

--restore file
Restore key from backup file.

--restore-from-server
Restore key from an existing token on the server. Requires --backup-key-file.

--backup-key-file file
Backup key file used to decrypt the private key backup when restoring from server.

--add-user-key
Register the token's RSA public key as the user's public key.

-n
Do not initialize the PIV applet — only register token data in OTPme.

-r
Replace existing token (keep UUID).

-d
Enable debug output.

Dynamic Groups

add_dynamic_group token group
Add a dynamic group to the token.

remove_dynamic_group token group
Remove a dynamic group from the token.

list_dynamic_groups token
List dynamic groups of the token.

Listing

list_roles [-r] token
List roles assigned to the token. Use -r for recursive listing.

list_hosts token
List hosts this token is assigned to.

list_nodes token
List nodes this token is assigned to.

list_groups token
List groups this token is assigned to.

list_accessgroups token
List access groups this token is assigned to.

Policy Management

add_policy token policy
Attach a policy to the token.

remove_policy token policy
Remove a policy from the token.

list_policies token
List policies attached to the token.

ACL Management

add_acl token owner_type owner acl
Add an access control entry.

del_acl token acl
Remove an access control entry.

show_acls token
Display all ACLs for the token.

enable_acl_inheritance token
Enable ACL inheritance from parent objects.

disable_acl_inheritance token
Disable ACL inheritance.

Import/Export

export token
Export token configuration to stdout.

remove_orphans token
Remove orphaned object references.

TOKEN TYPE COMMANDS

The following commands require --type before the command.

HOTP / TOTP / mOTP (OTP Tokens)

secret token [secret]
Change token secret.

show_secret token
Show token secret.

pin [--generate] token [pin]
Change token PIN.

show_pin token
Show token PIN.

enable_pin token
Enable token PIN. (HOTP/TOTP only)

disable_pin token
Disable token PIN. (HOTP/TOTP only)

gen token
Generate token OTP.

gen_mschap token
Generate MSCHAP challenge/response from token OTP.

gen_qrcode token
Generate QR code for token configuration. (HOTP/TOTP only)

mode token mode
Change token operation mode. (HOTP/TOTP only)

HOTP Specific

counter_check_range token [range]
Change OTP counter check range.

resync token [otp]
Resync counter-based token.

get_token_counter token
Get token counter value.

mOTP Specific

validity_time token [time]
Change OTP validity time.

timedrift_tolerance token [tolerance]
Change OTP timedrift tolerance.

Password Token

password [--generate] token [password]
Change token password.

2f_token token second_factor_token
Change second factor token.

enable_2f token
Enable second factor token.

disable_2f token
Disable second factor token.

enable_mschap token
Enable MSCHAP authentication.

disable_mschap token
Disable MSCHAP authentication.

remove_nt_hash token
Remove NT hash used for MSCHAP authentication.

dump_pass_hash token
Dump password hash.

set_pass_hash token file
Set password hash from file.

upgrade_pass_hash token [hash_type] [args]
Upgrade password hash.

SSH Token

ssh_public_key token [ssh_public_key]
Change token SSH public key.

card_type token [card_type]
Set card type of SSH token (e.g. gpg).

key_type token key_type
Set SSH key type (e.g. rsa).

password [--generate] token [password]
Change token password.

2f_token token second_factor_token
Change second factor token.

enable_2f / disable_2f token
Enable/disable second factor token.

SSH tokens also support signature commands: sign, resign, verify_sign, get_sign, add_sign, del_sign.

Link Token

add token destination_token
Add a link token pointing to destination_token.

YubiKey HMAC

otp_format token [format]
Change token OTP format.

validity_time token [time]
Change OTP validity time.

timedrift_tolerance token [tolerance]
Change OTP timedrift tolerance.

mode token mode
Change token operation mode.

OPTIONS

--type TYPE
Specify the token type. Required for the add command and for all type-specific commands. Must be placed before the command.

Display Options

-a
Show all tokens.

-z SIZE
Limit output size.

--fields FIELD1,FIELD2
Display only specified fields.

--role-limit N
Limit number of roles shown.

--policy-limit N
Limit number of policies shown.

General Options

-r
Replace existing token and keep its UUID (for add, move, deploy).

-u
Disable if unused for the given time (auto_disable).

Global options are available for all commands. See otpme(1) for details.

CONFIG PARAMETERS

Configuration parameters can be set with the config command und displayed with show_config. For a complete description of all available parameters and their applicable object types, see otpme(7).

EXAMPLES

otpme-token --type totp add alice/totp
Create a TOTP token for user alice

otpme-token --type fido2 deploy alice/fido2
Deploy a FIDO2 token

otpme-token test alice/totp
Test token authentication

otpme-token --type link add root/admin_link alice/login
Create a link token

FILES

/var/lib/otpme/
OTPme data directory

AUTHOR

the2nd \<the2nd@otpme.org>

NOTE

This manual page was created with AI assistance.

NAME

SYNOPSIS

DESCRIPTION

TOKEN TYPES

COMMANDS

Token Management

Token Configuration

Offline Configuration

Session

Auth Script

Deploy

Deploy - FIDO2 and U2F

Deploy - YubiKey HMAC-SHA1

Deploy - YubiKey OATH HOTP

Deploy - YubiKey GPG Applet

Deploy - YubiKey PIV Applet

Dynamic Groups

Listing

Policy Management

ACL Management

Import/Export

TOKEN TYPE COMMANDS

HOTP / TOTP / mOTP (OTP Tokens)

HOTP Specific

mOTP Specific

Password Token

SSH Token

Link Token

YubiKey HMAC

OPTIONS

Display Options

General Options

CONFIG PARAMETERS

EXAMPLES

FILES

SEE ALSO

AUTHOR

NOTE

COPYRIGHT