Subversion Repositories planix.SVN

.TH KEYFS 4

.SH NAME

keyfs, warning \- authentication database files

.SH SYNOPSIS

.B auth/keyfs

[

.B -p

]

[

.B -w

.RB [ np ]

]

[

.BI -m mntpt

]

[

.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 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 record for each user in the database.

Each record is encrypted separately

and contains the user's name,

DES key,

status,

host status,

and expiration date.

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.

Host status is a byte containing

binary 1 if the user is a host,

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.

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

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

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.

.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 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)