client/subauth.1.txt

   1 SUBAUTH(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 subauth - A client to the sub-authentication service
   7
   8
   9 SYNOPSIS
  10 --------
  11 *subauth* 'options' 'operation'
  12
  13
  14 DESCRIPTION
  15 -----------
  16 The sub-authentication service lets local users define sub-accounts
  17 with different authentication tokens for specific services.
  18
  19 The system administrator defines one or more authentication zones,
  20 each corresponding to a set of system services. You can use *subauth --zones*
  21 to list all existing zones.
  22
  23 Each zone can contain an account for each system user. Depending on the
  24 configuration of the zone, accounts can be manager manually by the administrator,
  25 or they can be created automatically when the user sets an authentication
  26 token for the zone.
  27
  28 Every account can be endowed with one of more authentication tokens
  29 of the following types. Depending on the configuration, all types need
  30 not be available in all zones.
  31
  32 * *Password:* a user-specified string, usually easy to remember, but hard to
  33   guess. This is useful when authenticating manually. Please note that the
  34   password must not contain a "+-+" (minus) character, because it is used
  35   as a separator in other token types. There may be at most one password
  36   per account. You can use *subauth --passwd* to set a password
  37   and *subauth --delete-passwd* to remove it.
  38
  39 * *Regular token:* such tokens are generated automatically. They consist
  40   of a public identifier (4 hexadecimal digits) and a random secret string.
  41   Multiple tokens can be defined for the same account, their public identifiers
  42   and optional comments can be listed by the user. This can be useful if you
  43   want to let multiple programs remember your credentials: each program can
  44   get a unique token and when it ceases to be trusted, the token can be simply
  45   removed. Use *subauth --create-token* to have a token generated and *subauth --delete-token*
  46   to have it removed.
  47
  48 * *Temporary token:* this is a randomly generated cryptographically signed string,
  49   allowing access to the given user in the given zone for a limited time. This
  50   can be useful for services which are used so scarcely that it does not make
  51   sense to remember permanent credentials of any kind. Use *subauth --temp-token*
  52   to obtain a temporary token.
  53
  54 The sub-accounts are managed by the *subauthd*(8) daemon.
  55 The *subauth*(1) command is a front-end to this daemon, through which
  56 accounts and tokens can be managed from the shell.
  57
  58
  59 OPERATIONS
  60 ----------
  61 *User commands*
  62
  63 *--zones*::
  64         List all known authentication zones.
  65
  66 *-l, --list*::
  67         List all accounts of the current user (this can be the user running the
  68         command, or a different user given as *--user* if ran by the super-user).
  69
  70 *--passwd*::
  71         Set or replace a password for the given account. Requires *--zone*.
  72
  73 *--delete-passwd*::
  74         Delete password for the given account. Requires *--zone*.
  75
  76 *--create-token*::
  77         Create a new token for the given account. Requires *--zone*.
  78         Optionally, a *--comment* can be given.
  79
  80 *--delete-token*::
  81         Delete a given token. Requires *--zone* and *--ident*.
  82
  83 *--temp-token*::
  84         Create a temporary token. Requires *--zone*.
  85         Optionally, token validity can be set with *--expire* (otherwise,
  86         a default of 5 minutes will be used).
  87
  88 *--login*::
  89         Test if a given password or token (read from standard input) is valid
  90         in the given zone. Require *--zone*.
  91
  92 *Administrator commands*
  93
  94 *--create-acct*::
  95         Create an account for the current user in the given zone. Requries *--zone*.
  96         Usually, a *--user* is also given.
  97
  98 *--delete-acct*::
  99         Delete an account for the current user in the given zone. Requires *--zone*.
 100         Usually, a *--user* is also given.
 101
 102 *--delete-user*::
 103         Deletes all accounts of the current user. Requires *--zone*.
 104         Usually, a *--user* is also given.
 105
 106 OPTIONS
 107 -------
 108
 109 *-u, --user=*'login'::
 110         Operate on the given user instead of the user running the command.
 111         Only the super-user can operate on somebody else.
 112
 113 *-z, --zone=*'zone'::
 114         Specify authentication zone. This is required by most operations.
 115
 116 *-i, --ident=*'id'::
 117         Specify token identifier. An asterisk can be used for "all tokens".
 118
 119 *-c, --comment=*'text'::
 120         When creating a token, remember this comment with the token. Comments
 121         make it easier to recognize the intentions behind different tokens.
 122
 123 *-x, --expire=*'time'::
 124         Set lifetime of a temporary token. The time is followed by a unit,
 125         which is either "*h*", "*m*", or "*s*". Maximum lifetime can be limited
 126         by zone configuration.
 127
 128
 129 SEE ALSO
 130 --------
 131 *subauthd*(8)