.\" Man page for accountmanager.
.\" Contact georg@steffers.org.in to correct errors or typos.
.TH man 1 "25 Jan 2017" "0.1" \
"accountmanager.sh: Shell tools for managing account credentials."
.SH NAME
accountmanager.sh \- source all functionality into the current shell

General purpose functions:
 random \- create a non blocking stream of random data on stdout
 rand_printable \- create a random string a printable characters

Database management functions:
 amngrdbinit \- initialize the SQLite account database
 amngrdbdestroy \- remove the SQLite account database

Account management functions:
 amngradd \- add an account credential to the database
 amngrcreate \- create a new account credential to the database
 amngrcrypt \- crypt the given data with GnuPG
 amngrdelete \- delete an account
 amngrgen \- generate a encrypted random passphrase
 amngrgetoldpass \- copy previous password of account to X clipboard
 amngrgetolduser \- copy previous username of account to X clipboard
 amngrgetpass \- copy active password of account to X clipboard
 amngrgetuser \- copy active username of account to X clipboard
 amngrid \- write the database id of a given account name to stdout
 amngrlist \- list all accounts
 amngrrename \- rename an account
 amngrsearch \- pattern search accounts
.SH SYNOPSIS
source
.B ${PATH}/accountmanager.sh

.B random

.B rand_printable
.RI [ len ]

.B amngrdbinit
.RI [ dbfile ]

.B amngrdbdestroy
.RI [ dbfile ]

.B amngradd -u
.I username
.B -p
.I password
.RB [ -d
.IR description ]
.RB [ -D
.IR dbfile ]
.RB [ -r
.IR recipient ]
.I account

.B amngrcreate -u
.I username
.RB [ -d
.IR description ]
.RB [ -D
.IR dbfile ]
.RB [ -r
.IR recipient ]
.I account

.B amngrcrypt
.RB [ -r
.IR recipient ]
.I password

.B amngrdelete
.I account

.B amngrgen
.RB [ -r
.IR recipient ]
.RI [ len ]

.B amngrgetoldpass
.I account

.B amngrgetolduser
.I account

.B amngrgetpass
.I account

.B amngrgetuser
.I account

.B amngrid
.I account

.B amngrlist
.RB [ -s
.IR separator ]

.B amngrrename
.I old_account new_account

.B amngrsearch
.RB [ -s
.IR separator ]
.I pattern
.SH DESCRIPTION
 This file can either be source into the current shell or used as a
standalone shell script via the provided symlinks. When used as standalone
script it will detect the function to call by the content of \fB$0\fR.
 All \fIaccount\fR as well as all \fIusername\fR arguments used below are
limited to 128 characters. The \fIaccount\fR argument is always a unique
string identifier for the account to manage. The \fIusername\fR argument is
the username part of a credential which is a (\fIusername\fR, \fIpassword\fR)
pair.
.TP
\fBrandom\fR
 Takes no arguments and connect a non blocking random source to stdout.
.TP
\fBrand_printable\fR [\fIlen\fR]
 Uses \fBrandom\fR to write a string of random printable characters to
stdout. All control characters ASCII-0 to ASCII-37 as well as
ASCII-177 to 255, single and double quotes are filtered. The single
and double quotes are filtered to prevent problems when they are used
as string separators after shell expansion as in the SQL here
documents used to communicate with the SQLite database.
 The optional \fIlen\fR argument specifies the string length to be written
and defaults to 512.
.TP
\fBamngrdbinit\fR [\fIdbfile\fR]
 Create the SQLite database file. If the optional \fIdbfile\fR argument is
given it specifies the fill path to the file to use, else the value of
\fB$AMNGRDB\fR environment variable is used.
.TP
\fBamngrdbdestroy\fR [\fIdbfile\fR]
 Deletes the SQLite database file. If the optional \fIdbfile\fR argument
is given it specifies the fill path to the file to use, else the value
of \fB$AMNGRDB\fR environment variable is used.
.TP
\fBamngradd\fR \fB-u\fR \fIusername\fR \fB-p\fR \fIpassword\fR \
[\fB-d\fR \fIdescription\fR] [\fB-D\fR \fIdbfile\fR] \
[\fB-r\fR \fIrecipient\fR] \fIaccount\fR
 Adds an account credential and marks it as active. If the account
already exist, the credential (\fIusername\fR and \fIpassword\fR) is added to
that account and the previously added credential is marked as old. If
there was another even older credential that was already marked as old
this will be marked as inactive and this becomes inaccessible with
this tools (except for \fBamngrdelete\fR).
 The necessary option \fB-u\fR specifies the username to be stored with
this credential pair.
 The also necessary option \fB-p\fR specifies the password to be stored
and the length of \fIpassword\fR is not limited at all.
 With option \fB-d\fR one can add a \fIdescription\fR to the account entry.
One can specify the \fIdbfile\fR with the option \fB-D\fR if that option is
not given the \fB$AMNGRDB\fR environment variable is used.
.TP
\fBamngrcreate\fR \fB-u\fR \fIusername\fR [\fB-d\fR \fIdescription\fR] \
[\fB-D\fR \fIdbfile\fR] [\fB-r\fR \fIrecipient\fR] \fIaccount\fR
 This will create a password with \fBamngrgen\fR and use that to add an
credential via \fBamngradd\fR. (See there for options description)
 The added password will be copied to the X clipboard with
\fBamngrgetpass\fR for further use.
.TP
\fBamngrcrypt\fR [\fB-r\fR \fIrecipient\fR] \fIpassword\fR
 Crypt the given plain text \fIpassword\fR with GnuPG and write it to
stdout.
 The option \fB-r\fR specifies the recipient to use with the call to
\fBgpg\fR. If it is not given the value of the \fB$AMNGRID\fR environment
variable is used.
.TP
\fBamngrdelete\fR \fIaccount\fR
 Remove the \fIaccount\fR and all credential associated to it.
.TP
\fBamngrgen\fR [\fB-r\fR \fIreceipient\fR] [\fIlen\fR]
 Generate a password with \fBrand_printable\fR and encrypt it via
\fBamngrcrypt\fR. By default the password will be 10 characters long. That
can be modified by the optional \fIlen\fR argument.
.TP
\fBamngrgetoldpass\fR \fIaccount\fR
 Read and decrypt the password associated with \fIaccount\fR that is
flagged as old and store it into the X clipboard.
.TP
\fBamngrgetolduser\fR \fIaccount\fR
 Read and decrypt the username associated with \fIaccount\fR that is
flagged as old and store it into the X clipboard.
.TP
\fBamngrgetpass\fR \fIaccount\fR
 Read and decrypt the password associated with \fIaccount\fR that is
flagged as active and store it into the X clipboard.
.TP
\fBamngrgetuser\fR \fIaccount\fR
 Read and decrypt the username associated with \fIaccount\fR that is
flagged as active and store it into the X clipboard.
.TP
\fBamngrid\fR \fIaccount\fR
 (This is primarily for internal use.) Get the database id associated
to the given \fIaccount\fR argument.
.TP
\fBamngrlist\fR [\fB-s\fR \fIseparator\fR]
 List all accounts currently stored within the database the output
will contain the name of the account, the username and the description
delimited by a \fIseparator\fR string that can be specified with the
\fB-s\fR option. If the option is omitted the separator is " => ". Each
row is one account.
.TP
\fBamngrrename\fR \fIold_account\fR \fInew_account\fR
 Rename the account specified by \fIold_account\fR to \fInew_account\fR.
.TP
\fBamngrsearch\fR [\fB-s\fR \fIseparator\fR] \fIpattern\fR
 List accounts where \fIpattern\fR exists in either the account name, the
username or the account description. The output is like the one
described with \fBamngrlist\fR.
.SH OPTIONS
 The options are consistent over all sub commands. However not all sub commands
use all options and some sub commands take arguments that other get per option.
(See \fBDESCRIPTION\fR)
.TP
.B -u
The login username of the credential for the account.
.TP
.B -p
The plain text password of the credential for the account.
.TP
.B -d
The description for the account.
.TP
.B -D
Select the database file to use instead of the one defined in the
\fB$AMNGRDB\fR environment variable.
.TP
.B -r
Select a recipient id for GnuPG encryption to use instead of the one
defined in the \fB$AMNGRID\fR environment variable.
.TP
.B -s
The column separator for the \fBamngrlist\fR and \fBamngrsearch\R commands.
.SH ENVIRONMENT
.TP
.B AMNGRDB
 The default SQLite database file to use. This will be created with
\fBamngrdbinit\fR as long as the path to that file exists. This can be
overruled with the \fB-D\fR command line option.
.TP
.B AMNGRID
 The GnuPG recipient id to encrypt against. You should use one where you have
both public and private key. Failure to do so will result in not decipherable
data. This can be overruled with the \fB-r\fR command line option.
.TP
.B AMNGRPWLEN
 The password length to be used when generating new passwords.
.SH DEPENDENCIES
 A set of POSIX compliant shell utilities including a POSIX compliant shell
as well are needed to run this script.

 The functions within this script expect that all the needed tools
can be found by the shell, usually that means that the current \fB$PATH\fR
environment variable is set accordingly or that the tools are
a shell internal.

 The existence of a reliable non blocking random source. By default this
scripts use \fB$(cat /dev/urandom)\fR which can be changed by replacing the
alias \fBrandom\fR with something useful for your system.

 For data storage \fBSqlite >= 3.6.19\fR is required. The version requirement
comes from the use of foreign key constraints.

 To store the data within the X clipboard the \fBxclip\fR is needed.

.SS The tools used are
.PD 0
.IP \[bu] 2
\fBawk\fR
.IP \[bu]
\fBbasename\fR
.IP \[bu]
\fBcat\fR
.IP \[bu]
\fBdnsdomainname\fR
.IP \[bu]
\fBecho\fR
.IP \[bu]
\fBgetopts\fR
.IP \[bu]
\fBgpg\fR
.IP \[bu]
\fBhead\fR
.IP \[bu]
\fBprintf\fR
.IP \[bu]
\fBrm\fR
.IP \[bu]
\fBshift\fR
.IP \[bu]
\fBSQLite3\fR (>= 3.6.19 for foreign key constraints)
.IP \[bu]
\fBtest\fR and \fB[\fR
.IP \[bu]
\fBtr\fR
.IP \[bu]
\fBxclip\fR
.PD
.SH SEE ALSO
gpg2(1), gpg-agent(1)
.SH BUGS
No known bugs.
.SH AUTHOR
Georg Hopp (georg@steffers.org.in)
.SH COPYRIGHT
 Copyright © 2017 Georg Hopp License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it. There is
NO  WARRANTY, to the extent permitted by law.
.\" vim: set ft=groff ts=4 sw=4: