head     1.2;
access   bayes danm geli hal jch jws brad;
symbols  ;
locks    geli:1.2; strict;
comment  @# @;


1.2
date     86.07.04.13.14.46;  author bayes;  state Exp;
branches ;
next     1.1;

1.1
date     86.07.04.11.04.03;  author bayes;  state Exp;
branches ;
next     ;


desc
@First Rev of setpasswords ERS for HFSDAM
@


1.2
log
@Added catpasswords specification
@
text
@	    ERS--Setpasswords and Catpasswords in HFSDAM
			    Scott Bayes


Setpasswords supports "subcalls" in hfsdam.

These subcalls are:

Volume class
============
login
umask

File class
==========
open
chmod
chown
chgrp
atime
ctime
mtime

For all calls, a FIB is passed in, and fwindow points at an array of
passentry (see MISC). Fpeof is the number of valid entries in fwindow^,
and fpos is 0. The DAM processes all passentries till it gets an error,
or completes successfully. If it completes, then effects of all subcalls
remain. If it gets an error, ioresult is set, inode and DAM state are
unchanged. The FIB may be modified whether or not there is an error, 
so BEWARE.

For all subcalls, the pword is the call name (eg 'chown'), and pbits is
an integer that the call may use.

Only notable failure conditions are given. Ie things like failure to traverse
path are not specified here; do what other DAM calls do.

All effects of all calls happen "simultaneously", or not at all if there is
an error. That means that for example chown BEFORE chmod will not cause
chmod to fail due to chown removing the permissions needed for chmod. 

Permissions needed for each operation will be defined by the implementor and 
noted in this ERS.

The class of the first pword sets the class of the setpasswords call. If
a passentry in the array is not in this class, ioresult := ibadvalue, and
the call is exited. This happens because volume and file class calls have 
different FIB setups which are not compatible with each other.

If an unrecognized pword is encountered, the call exits with ioresult := 
ibadvalue.

If (fvid <> unitable^[funit].uvid) and (fvid <> rootname(unit))
then ioresult := zmediumchanged (for removable media protection)



Volume class calls
==================

These don't deal with specific files, but instead set up information on
how the DAM should handle the unit or all files on it.

FIB conditions: The FIB need not be open (it can be, but be careful, ffpw has
	part of the filename for an open FIB). Funit is the unit to which the 
	DAM applies the call, and fvid should be the name of funit.

login :	Ftitle is reserved for user logname, ffpw is the passwd you wish 
	to use (/etc/passwd unsupported in 3.2), the pbits is the user number.
	
	Version specifics:
	
	3.2--There is one "secret" password that works, and pbits is
	ignored. If the password matches the ffpw, "superuser" mode is
	set. If ffpw is '' or does not match the secret word, then default 
	uid/gid are set. In superuser mode, you have uid=0, gid=1, and 
	permissions are completely ignored. Default (the only state other
	than "superuser" in 3.2) is uid=paws_uid, and gid=ws_gid (paws_uid
	and ws_gid are 17 and 9 respectively and are exported from HFSTUFF). 

	If future versions support /etc/passwd, then ftitle is treated as 
	user name (if we support login by name), pbits is NOT ignored if 
	we support login by user number, and gid is set from /etc/passwd 
	if login is successful.

	Failure conditions:

	3.2-- (ffpw <> '') and (ffpw <> secretpassword)
	      --> ioresult := ibadpass

umask :	pbits is the lower 9 bits of umask (in decimal) for the unit.
	
	Umask in the DAM gets set to pbits binand 511.



File class calls
================

These deal with specific files and inodes, and can modify the inodes of the
files as below.

FIB conditions: except for the open call, the FIB is expected to be open
	on a file or directory. Openfile, createfile, overwritefile, and
	opendirectory all are adequate. Openparentdir prepares the FIB for
	setpasswords calls on the parent directory.
	The pathid is the file inode, foldfileid is the parent inode of the
	file, ftid+ffpw is the basename of the file, funit is the unit
	number. If pathid = no_inode, or pathid = raw_inode, the FIB is
	considered closed, and ioresult := inotopen, otherwise an error
	could occur during get_inode(pathid), which causes exit from DAM.
	If foldfileid = no_inode or foldfileid = raw_inode, set ioresult
	:= ilostfile and exit. At exit the FIB may have been changed.

	For open, ftitle is a path, and pathid, foldfileid are ignored.
	The FIB is prepared for other file class calls on the file or
	directory represented by the ftitle, if there is no traversal
	error. The only permissions needed for open are x permissions
	down to but not including the target file/dir. The FIB will
	be left not freadable, not fwriteable after open. Open can be used
	on any file type (eg pipes, etc).

open :	pbits is ignored.

chmod :	pbits is the lower 12 bits of the inode mode. The FILER should mask
	to only the lower 9 bits before calling chmod. Mode is set to
	pbits binand 4095.

chown :	pbits is the owner number. It is valid in the range 0..65535. Other
	values generate ioresult := ibadvalue.

chgrp :	pbits is the group number. It is valid in the range 0..65535. Other
	values generate ioresult := ibadvalue.

atime : pbits is the time in seconds since midnight 1-Jan-70 to which 
	di_atime is to be set. No illegal values.

ctime : pbits is the time in seconds since midnight 1-Jan-70 to which 
	di_ctime is to be set. No illegal values.

mtime : pbits is the time in seconds since midnight 1-Jan-70 to which 
	di_mtime is to be set. No illegal values.



Catpasswords returns information on the current "login" state in HFSDAM.
Specifically, it returns information that is complementary to the 2
"volume class" subcalls of setpasswords, login and umask.

Catpasswords takes a FIB that has been set up in the same way as for
setpasswords volume related calls. Fwindow is a pointer to an array
of passentries. As in setpasswords, fpeof indicates the number of
passentries pointed to by fwindowp. These passentries will be modified 
by catpasswords as follows:

If fpeof <=0 then the call exits immediately, with no (?) error, and
no modifications to fwindowp^.

If fpeof >= 1 then
	passentry[1].pword := 'uid'
	passentry[1].pbits := the current uid for this unit

If fpeof >= 2 then
	passentry[2].pword := 'gid'
	passentry[2].pbits := the current gid for this unit

If fpeof >= 3 then
	passentry[3].pword := 'umask'
	passentry[3].pbits := the current umask for this unit

Catpasswords will not change the fib. 
@


1.1
log
@Initial revision
@
text
@d1 2
a2 2
	    ERS--Setpasswords in HFSDAM
		Scott Bayes
d144 28
@
