273 lines
5.3 KiB
Text
273 lines
5.3 KiB
Text
.TH KEYFS 4
|
|
.SH NAME
|
|
keyfs, warning \- authentication database files
|
|
.SH SYNOPSIS
|
|
.B auth/keyfs
|
|
[
|
|
.B -p
|
|
]
|
|
[
|
|
.B -w
|
|
.RB [ np ]
|
|
]
|
|
[
|
|
.BI -m mntpt
|
|
]
|
|
[
|
|
.B -r
|
|
]
|
|
[
|
|
.I keyfile
|
|
]
|
|
.PP
|
|
.B auth/warning
|
|
[
|
|
.B -n
|
|
]
|
|
[
|
|
.B -p
|
|
]
|
|
.SH DESCRIPTION
|
|
.I Keyfs
|
|
serves a two-level file tree for manipulating authentication information.
|
|
It runs on the machine providing authentication service for the local
|
|
Plan 9 network, which may be a dedicated authentication server or
|
|
a CPU server.
|
|
The programs described in
|
|
.IR auth (8)
|
|
use
|
|
.I keyfs
|
|
as their interface to the authentication database.
|
|
.PP
|
|
.I Keyfs
|
|
reads and decrypts file
|
|
.I keyfile
|
|
(default
|
|
.BR /adm/keys )
|
|
using the DES or AES key,
|
|
which is by default read from
|
|
.B #r/nvram
|
|
(see
|
|
.IR rtc (3)).
|
|
With option
|
|
.BR -p ,
|
|
.I keyfs
|
|
prompts for a password from which the key is derived.
|
|
.I Keyfile
|
|
holds a 41-byte (57-byte for AES) record for each user in the database.
|
|
Each record contains the user's name,
|
|
DES key,
|
|
status,
|
|
warning status,
|
|
expiration date,
|
|
secret password
|
|
and AES key.
|
|
The name is a
|
|
null-terminated
|
|
.SM UTF
|
|
string
|
|
.B NAMELEN
|
|
bytes long.
|
|
The status is a byte containing
|
|
binary 0 if the account is enabled,
|
|
1 if it is disabled.
|
|
Warning status is a byte containing
|
|
the number of user expiration notifications.
|
|
The expiration date is four-byte little-endian integer
|
|
which represents the time in seconds since the epoch
|
|
(see
|
|
.IR date (1))
|
|
at which the account will expire.
|
|
The secret password is a null-terminated
|
|
.SM UTF
|
|
string
|
|
.B SECRETLEN
|
|
bytes long.
|
|
If any changes are made to the database that affect the information stored in
|
|
.IR keyfile ,
|
|
a new version of the file is written.
|
|
.PP
|
|
If the
|
|
.B -r
|
|
option is given, the database is mounted `read-only' and no changes are permitted.
|
|
.PP
|
|
There are two authentication databases,
|
|
one for Plan 9 user information,
|
|
and one for SecureNet user information.
|
|
A user need not be installed in both databases
|
|
but must be installed in the Plan 9 database to connect to a Plan 9 server.
|
|
.PP
|
|
.I Keyfs
|
|
serves an interpretation of the
|
|
.I keyfile
|
|
in the file tree rooted at
|
|
.I mntpt
|
|
(default
|
|
.BR /mnt/keys ).
|
|
Each user
|
|
.I user
|
|
in
|
|
.I keyfile
|
|
is represented as the directory
|
|
.IR mntpt / user .
|
|
.PP
|
|
Making a new directory in
|
|
.I mntpt
|
|
creates a new user entry in the database.
|
|
Removing a directory removes the user entry,
|
|
and renaming it changes the name in the entry.
|
|
Such changes are reflected immediately in
|
|
.IR keyfile .
|
|
.I Keyfs
|
|
does not allow duplicate names when creating or renaming user entries.
|
|
.PP
|
|
All files in the user directories except for
|
|
.B key
|
|
and
|
|
.B aeskey
|
|
contain
|
|
.SM UTF
|
|
strings with a trailing newline when read,
|
|
and should be written as
|
|
.SM UTF
|
|
strings with or without a trailing newline.
|
|
.B Key
|
|
contains the
|
|
.BR DESKEYLEN -byte
|
|
encryption key for the user.
|
|
.B Aeskey
|
|
contains the
|
|
.BR AESKEYLEN -byte
|
|
encryption key.
|
|
.PP
|
|
The following files appear in the user directories.
|
|
.TF expire
|
|
.TP
|
|
.B key
|
|
The authentication key for the user.
|
|
If the user's account is disabled or expired,
|
|
reading this file returns an error.
|
|
Writing
|
|
.I key
|
|
changes the key in the database.
|
|
.TP
|
|
.B aeskey
|
|
The AES encryption key for the user.
|
|
.TP
|
|
.B secret
|
|
The secret password.
|
|
.TP
|
|
.B log
|
|
The number of consecutive failed authentication attempts for the user.
|
|
Writing the string
|
|
.B bad
|
|
increments this number; writing
|
|
.B good
|
|
resets it to 0.
|
|
This number is not stored in
|
|
.IR keyfile ,
|
|
and is initialized to 0 when
|
|
.I keyfs
|
|
starts.
|
|
When the number reaches a multiple of ten,
|
|
.I keyfs
|
|
temporarily disables the account for that many seconds.
|
|
Reads from the
|
|
.B key
|
|
or
|
|
.B secret
|
|
files during this time return the error
|
|
``user in purgatory.''
|
|
.TP
|
|
.B status
|
|
The current status of the account, either
|
|
.B ok
|
|
or
|
|
.BR disabled .
|
|
Writing
|
|
.B ok
|
|
enables the account;
|
|
writing
|
|
.B disabled
|
|
disables it.
|
|
.TP
|
|
.B expire
|
|
The expiration time for the account.
|
|
When read, it contains either the string
|
|
.B never
|
|
or the time in seconds since the epoch
|
|
that the account will expire.
|
|
When written with strings of the same form,
|
|
it sets the expiration date for the user.
|
|
If the expiration date is reached,
|
|
the account is not disabled,
|
|
but
|
|
.I key
|
|
cannot be read without an error.
|
|
.PD
|
|
.PP
|
|
If the
|
|
.B -w
|
|
option is on,
|
|
.I keyfs
|
|
runs the command
|
|
.I warning
|
|
once every 24 hours to mail people about expiring keys.
|
|
Warnings are sent 14 days and 7 days prior to expiration.
|
|
The argument to
|
|
.BR -w ,
|
|
either
|
|
.B p
|
|
or
|
|
.BR n ,
|
|
is passed to
|
|
.I warning
|
|
to restrict the warnings to
|
|
the Plan 9 or SecureNet database.
|
|
The default for
|
|
.I keyfs
|
|
is not to call
|
|
.I warning
|
|
at all;
|
|
.I warning's
|
|
own default is to warn about both.
|
|
The files
|
|
.B /adm/netkeys.who
|
|
and
|
|
.B /adm/keys.who
|
|
are used to find the mail addresses to send to.
|
|
The first word on each line identifies
|
|
a user.
|
|
Any subsequent strings on the line delimited '<' and '>' are considered mail
|
|
addresses to send warnings to.
|
|
If multiple lines match a user, the last in the file is used.
|
|
.B Changeuser
|
|
(see
|
|
.IR auth (8))
|
|
adds lines to these files.
|
|
.SH FILES
|
|
.TF /adm/netkeys.who
|
|
.TP
|
|
.B /adm/keys
|
|
Encrypted key file for the Plan 9 database.
|
|
.TP
|
|
.B /adm/netkeys
|
|
Encrypted key file for the SecureNet database.
|
|
.TP
|
|
.B /adm/keys.who
|
|
List of users in the Plan 9 database.
|
|
.TP
|
|
.B /adm/netkeys.who
|
|
List of users in the SecureNet database.
|
|
.TP
|
|
.B #r/nvram
|
|
The non-volatile RAM on the server, which holds the key used
|
|
to decrypt key files.
|
|
.SH SOURCE
|
|
.B /sys/src/cmd/auth/keyfs.c
|
|
.br
|
|
.B /sys/src/cmd/auth/warning.c
|
|
.SH "SEE ALSO"
|
|
.IR authsrv (6),
|
|
.IR namespace (6),
|
|
.IR auth (8)
|