From ceae645e004c8f1548e5f2ab6986ff79398424bd Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Tue, 22 Aug 2017 00:19:41 +0200 Subject: [PATCH] Client: Initial version of the man page TODO: Installation target --- client/Makefile | 9 ++- client/subauth.1.txt | 131 +++++++++++++++++++++++++++++++++++++++++++ configure | 2 + 3 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 client/subauth.1.txt diff --git a/client/Makefile b/client/Makefile index 4ab4e29..91b5da4 100644 --- a/client/Makefile +++ b/client/Makefile @@ -1,9 +1,16 @@ DIRS+=client -PROGS+=$(o)/client/subauth +PROGS+=$(o)/client/subauth $(o)/client/subauth.1 $(o)/client/subauth: $(o)/client/subauth.o +# This is a little bit hacky as a2x cannot produce output +# in a different directory. +$(o)/%.1: $(s)/%.1.txt + $(M)MAN $< + $(Q)cp $< $@.txt + $(Q)a2x -f manpage $@.txt + .PHONY: install-client install:: install-client install-client: diff --git a/client/subauth.1.txt b/client/subauth.1.txt new file mode 100644 index 0000000..6820926 --- /dev/null +++ b/client/subauth.1.txt @@ -0,0 +1,131 @@ +SUBAUTH(1) +========== + +NAME +---- +subauth - A client to the sub-authentication service + + +SYNOPSIS +-------- +*subauth* 'options' 'operation' + + +DESCRIPTION +----------- +The sub-authentication service lets local users define sub-accounts +with different authentication tokens for specific services. + +The system administrator defines one or more authentication zones, +each corresponding to a set of system services. You can use *subauth --zones* +to list all existing zones. + +Each zone can contain an account for each system user. Depending on the +configuration of the zone, accounts can be manager manually by the administrator, +or they can be created automatically when the user sets an authentication +token for the zone. + +Every account can be endowed with one of more authentication tokens +of the following types. Depending on the configuration, all types need +not be available in all zones. + +* *Password:* a user-specified string, usually easy to remember, but hard to + guess. This is useful when authenticating manually. Please note that the + password must not contain a "+-+" (minus) character, because it is used + as a separator in other token types. There may be at most one password + per account. You can use *subauth --passwd* to set a password + and *subauth --delete-passwd* to remove it. + +* *Regular token:* such tokens are generated automatically. They consist + of a public identifier (4 hexadecimal digits) and a random secret string. + Multiple tokens can be defined for the same account, their public identifiers + and optional comments can be listed by the user. This can be useful if you + want to let multiple programs remember your credentials: each program can + get a unique token and when it ceases to be trusted, the token can be simply + removed. Use *subauth --create-token* to have a token generated and *subauth --delete-token* + to have it removed. + +* *Temporary token:* this is a randomly generated cryptographically signed string, + allowing access to the given user in the given zone for a limited time. This + can be useful for services which are used so scarcely that it does not make + sense to remember permanent credentials of any kind. Use *subauth --temp-token* + to obtain a temporary token. + +The sub-accounts are managed by the *subauthd*(8) daemon. +The *subauth*(1) command is a front-end to this daemon, through which +accounts and tokens can be managed from the shell. + + +OPERATIONS +---------- +*User commands* + +*--zones*:: + List all known authentication zones. + +*-l, --list*:: + List all accounts of the current user (this can be the user running the + command, or a different user given as *--user* if ran by the super-user). + +*--passwd*:: + Set or replace a password for the given account. Requires *--zone*. + +*--delete-passwd*:: + Delete password for the given account. Requires *--zone*. + +*--create-token*:: + Create a new token for the given account. Requires *--zone*. + Optionally, a *--comment* can be given. + +*--delete-token*:: + Delete a given token. Requires *--zone* and *--ident*. + +*--temp-token*:: + Create a temporary token. Requires *--zone*. + Optionally, token validity can be set with *--expire* (otherwise, + a default of 5 minutes will be used). + +*--login*:: + Test if a given password or token (read from standard input) is valid + in the given zone. Require *--zone*. + +*Administrator commands* + +*--create-acct*:: + Create an account for the current user in the given zone. Requries *--zone*. + Usually, a *--user* is also given. + +*--delete-acct*:: + Delete an account for the current user in the given zone. Requires *--zone*. + Usually, a *--user* is also given. + +*--delete-user*:: + Deletes all accounts of the current user. Requires *--zone*. + Usually, a *--user* is also given. + +OPTIONS +------- + +*-u, --user=*'login':: + Operate on the given user instead of the user running the command. + Only the super-user can operate on somebody else. + +*-z, --zone=*'zone':: + Specify authentication zone. This is required by most operations. + +*-i, --ident=*'id':: + Specify token identifier. An asterisk can be used for "all tokens". + +*-c, --comment=*'text':: + When creating a token, remember this comment with the token. Comments + make it easier to recognize the intentions behind different tokens. + +*-x, --expire=*'time':: + Set lifetime of a temporary token. The time is followed by a unit, + which is either "*h*", "*m*", or "*s*". Maximum lifetime can be limited + by zone configuration. + + +SEE ALSO +-------- +*subauthd*(8) diff --git a/configure b/configure index 53888b6..4707901 100755 --- a/configure +++ b/configure @@ -56,6 +56,8 @@ if (IsSet("CONFIG_APACHE_MOD")) { Set("INSTALL_APACHE2_CONFIG_DIR" => '$(INSTALL_PREFIX)etc/apache2'); } +require UCW::Configure::Doc; + Finish(); Log "\nConfigured, run `make' to build everything.\n"; -- 2.39.2