BSD 4_4_Lite2 development

Work on file usr/src/kerberosIV/man/acl_check.3
Work on file usr/src/kerberosIV/man/krb_sendauth.3

Synthesized-from: CSRG/cd3/4.4BSD-Lite2

diff --git a/usr/src/kerberosIV/man/acl_check.3 b/usr/src/kerberosIV/man/acl_check.3
new file mode 100644 (file)
index 0000000..4e165ce
--- /dev/null
+++ b/usr/src/kerberosIV/man/acl_check.3
@@ -0,0 +1,184 @@
+.\" $Source: /mit/kerberos/src/man/RCS/acl_check.3,v $
+.\" $Author: jtkohl $
+.\" $Header: acl_check.3,v 4.1 89/01/23 11:06:54 jtkohl Exp $
+.\" Copyright 1989 by the Massachusetts Institute of Technology.
+.\"
+.\" For copying and distribution information,
+.\" please see the file <mit-copyright.h>.
+.\"
+.TH ACL_CHECK 3 "Kerberos Version 4.0" "MIT Project Athena"
+.SH NAME
+acl_canonicalize_principal, acl_check, acl_exact_match, acl_add,
+acl_delete, acl_initialize \- access control list routines
+.SH SYNOPSIS
+.nf
+.nj
+.ft B
+cc <files> \-lacl \-lkrb
+.PP
+.ft B
+#include <krb.h>
+.PP
+.ft B
+acl_canonicalize_principal(principal, buf)
+char *principal;
+char *buf;
+.PP
+.ft B
+acl_check(acl, principal)
+char *acl;
+char *principal;
+.PP
+.ft B
+acl_exact_match(acl, principal)
+char *acl;
+char *principal;
+.PP
+.ft B
+acl_add(acl, principal)
+char *acl;
+char *principal;
+.PP
+.ft B
+acl_delete(acl, principal)
+char *acl;
+char *principal;
+.PP
+.ft B
+acl_initialize(acl_file, mode)
+char *acl_file;
+int mode;
+.fi
+.ft R
+.SH DESCRIPTION
+.SS Introduction
+.PP
+An access control list (ACL) is a list of principals, where each
+principal is represented by a text string which cannot contain
+whitespace.  The library allows application programs to refer to named
+access control lists to test membership and to atomically add and
+delete principals using a natural and intuitive interface.  At
+present, the names of access control lists are required to be Unix
+filenames, and refer to human-readable Unix files; in the future, when
+a networked ACL server is implemented, the names may refer to a
+different namespace specific to the ACL service.
+.PP
+.SS Principal Names
+.PP
+Principal names have the form
+.nf
+.in +5n
+<name>[.<instance>][@<realm>]
+.in -5n
+e.g.:
+.in +5n
+asp
+asp.root
+asp@ATHENA.MIT.EDU
+asp.@ATHENA.MIT.EDU
+asp.root@ATHENA.MIT.EDU
+.in -5n
+.fi
+It is possible for principals to be underspecified.  If an instance is
+missing, it is assumed to be "".  If realm is missing, it is assumed
+to be the local realm as determined by
+.IR krb_get_lrealm (3).
+The canonical form contains all of name, instance,
+and realm; the acl_add and acl_delete routines will always
+leave the file in that form.  Note that the canonical form of
+asp@ATHENA.MIT.EDU is actually asp.@ATHENA.MIT.EDU.
+.SS Routines
+.PP
+.I acl_canonicalize_principal
+stores the canonical form of 
+.I principal
+in 
+.IR buf .
+.I Buf
+must contain enough
+space to store a principal, given the limits on the sizes of name,
+instance, and realm specified as ANAME_SZ, INST_SZ, and REALM_SZ,
+respectively, in
+.IR /usr/include/krb.h .
+.PP
+.I acl_check
+returns nonzero if
+.I principal
+appears in 
+.IR acl .
+Returns 0 if principal
+does not appear in acl, or if an error occurs.  Canonicalizes
+principal before checking, and allows the ACL to contain wildcards.  The
+only supported wildcards are entries of the form
+name.*@realm, *.*@realm, and *.*@*.  An asterisk matches any value for
+its component field.  For example, "jtkohl.*@*" would match principal
+jtkohl, with any instance and any realm.
+.PP
+.I acl_exact_match
+performs like 
+.IR acl_check ,
+but does no canonicalization or wildcard matching.
+.PP
+.I acl_add
+atomically adds 
+.I principal
+to 
+.IR acl .
+Returns 0 if successful, nonzero otherwise.  It is considered a failure
+if
+.I principal
+is already in 
+.IR acl .
+This routine will canonicalize
+.IR principal ,
+but will treat wildcards literally.
+.PP
+.I acl_delete
+atomically deletes 
+.I principal
+from 
+.IR acl .
+Returns 0 if successful,
+nonzero otherwise.  It is considered a failure if 
+.I principal
+is not
+already in 
+.IR acl .
+This routine will canonicalize 
+.IR principal ,
+but will treat wildcards literally.
+.PP
+.I acl_initialize
+initializes
+.IR acl_file .
+If the file 
+.I acl_file
+does not exist,
+.I acl_initialize
+creates it with mode
+.IR mode .
+If the file
+.I acl_file
+exists,
+.I acl_initialize
+removes all members.  Returns 0 if successful,
+nonzero otherwise.  WARNING: Mode argument is likely to change with
+the eventual introduction of an ACL service.  
+.SH NOTES
+In the presence of concurrency, there is a very small chance that
+.I acl_add
+or
+.I acl_delete
+could report success even though it would have
+had no effect.  This is a necessary side effect of using lock files
+for concurrency control rather than flock(2), which is not supported
+by NFS.
+.PP
+The current implementation caches ACLs in memory in a hash-table
+format for increased efficiency in checking membership; one effect of
+the caching scheme is that one file descriptor will be kept open for
+each ACL cached, up to a maximum of 8.
+.SH SEE ALSO
+kerberos(3), krb_get_lrealm(3)
+.SH AUTHOR
+James Aspnes (MIT Project Athena)

diff --git a/usr/src/kerberosIV/man/krb_sendauth.3 b/usr/src/kerberosIV/man/krb_sendauth.3
new file mode 100644 (file)
index 0000000..d8b0be6
--- /dev/null
+++ b/usr/src/kerberosIV/man/krb_sendauth.3
@@ -0,0 +1,349 @@
+.\" $Source: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v $
+.\" $Author: kfall $
+.\" $Header: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v 4.2 90/06/25 21:12:26 kfall Exp $
+.\" Copyright 1988 by the Massachusetts Institute of Technology.
+.\"
+.\" For copying and distribution information,
+.\" please see the file <mit-copyright.h>.
+.\"
+.TH KRB_SENDAUTH 3 "Kerberos Version 4.0" "MIT Project Athena"
+.SH NAME
+krb_sendauth, krb_recvauth, krb_net_write, krb_net_read \-
+Kerberos routines for sending authentication via network stream sockets
+.SH SYNOPSIS
+.nf
+.nj
+.ft B
+#include <kerberosIV/krb.h>
+#include <kerberosIV/des.h>
+#include <netinet/in.h>
+.PP
+.fi
+.HP 1i
+.ft B
+int krb_sendauth(options, fd, ktext, service, inst, realm, checksum,
+msg_data, cred, schedule, laddr, faddr, version)
+.nf
+.RS 0
+.ft B
+long options;
+int fd;
+KTEXT ktext;
+char *service, *inst, *realm;
+u_long checksum;
+MSG_DAT *msg_data;
+CREDENTIALS *cred;
+Key_schedule schedule;
+struct sockaddr_in *laddr, *faddr;
+char *version;
+.PP
+.fi
+.HP 1i
+.ft B
+int krb_recvauth(options, fd, ktext, service, inst, faddr, laddr,
+auth_data, filename, schedule, version)
+.nf
+.RS 0
+.ft B
+long options;
+int fd;
+KTEXT ktext;
+char *service, *inst;
+struct sockaddr_in *faddr, *laddr;
+AUTH_DAT *auth_data;
+char *filename;
+Key_schedule schedule;
+char *version;                 
+.PP
+.ft B
+int krb_net_write(fd, buf, len)
+int fd;
+char *buf;
+int len;
+.PP
+.ft B
+int krb_net_read(fd, buf, len)
+int fd;
+char *buf;
+int len;
+.fi
+.SH DESCRIPTION
+.PP
+These functions,
+which are built on top of the core Kerberos library,
+provide a convenient means for client and server
+programs to send authentication messages
+to one another through network connections.
+The
+.I krb_sendauth
+function sends an authenticated ticket from the client program to
+the server program by writing the ticket to a network socket.
+The
+.I krb_recvauth
+function receives the ticket from the client by
+reading from a network socket.
+
+.SH KRB_SENDAUTH
+.PP
+This function writes the ticket to
+the network socket specified by the
+file descriptor
+.IR fd,
+returning KSUCCESS if the write proceeds successfully,
+and an error code if it does not.
+
+The
+.I ktext
+argument should point to an allocated KTEXT_ST structure.
+The
+.IR service,
+.IR inst,
+and
+.IR realm
+arguments specify the server program's Kerberos principal name,
+instance, and realm.
+If you are writing a client that uses the local realm exclusively,
+you can set the
+.I realm
+argument to NULL.
+
+The
+.I version
+argument allows the client program to pass an application-specific
+version string that the server program can then match against
+its own version string.
+The
+.I version
+string can be up to KSEND_VNO_LEN (see 
+.IR <krb.h> )
+characters in length.
+
+The
+.I checksum
+argument can be used to pass checksum information to the
+server program.
+The client program is responsible for specifying this information.
+This checksum information is difficult to corrupt because
+.I krb_sendauth
+passes it over the network in encrypted form.
+The
+.I checksum
+argument is passed as the checksum argument to
+.IR krb_mk_req .
+
+You can set
+.IR krb_sendauth's
+other arguments to NULL unless you want the
+client and server programs to mutually authenticate
+themselves.
+In the case of mutual authentication,
+the client authenticates itself to the server program,
+and demands that the server in turn authenticate itself to
+the client.
+
+.SH KRB_SENDAUTH AND MUTUAL AUTHENTICATION
+.PP
+If you want mutual authentication,
+make sure that you read all pending data from the local socket
+before calling
+.IR krb_sendauth.
+Set
+.IR krb_sendauth's
+.I options
+argument to
+.BR KOPT_DO_MUTUAL
+(this macro is defined in the
+.IR krb.h
+file);
+make sure that the
+.I laddr
+argument points to
+the address of the local socket,
+and that
+.I faddr
+points to the foreign socket's network address.
+
+.I Krb_sendauth
+fills in the other arguments--
+.IR msg_data ,
+.IR cred ,
+and
+.IR schedule --before
+sending the ticket to the server program.
+You must, however, allocate space for these arguments
+before calling the function.
+
+.I Krb_sendauth
+supports two other options:
+.BR KOPT_DONT_MK_REQ,
+and
+.BR KOPT_DONT_CANON.
+If called with
+.I options
+set as KOPT_DONT_MK_REQ,
+.I krb_sendauth
+will not use the
+.I krb_mk_req
+function to retrieve the ticket from the Kerberos server.
+The
+.I ktext
+argument must point to an existing ticket and authenticator (such as
+would be created by 
+.IR krb_mk_req ),
+and the
+.IR service,
+.IR inst,
+and
+.IR realm
+arguments can be set to NULL.
+
+If called with
+.I options
+set as KOPT_DONT_CANON,
+.I krb_sendauth
+will not convert the service's instance to canonical form using 
+.IR krb_get_phost (3).
+
+If you want to call
+.I krb_sendauth
+with a multiple
+.I options
+specification,
+construct
+.I options
+as a bitwise-OR of the options you want to specify.
+
+.SH KRB_RECVAUTH
+.PP
+The
+.I krb_recvauth
+function
+reads a ticket/authenticator pair from the socket pointed to by the
+.I fd
+argument.
+Set the
+.I options
+argument
+as a bitwise-OR of the options desired.
+Currently only KOPT_DO_MUTUAL is useful to the receiver.
+
+The
+.I ktext
+argument
+should point to an allocated KTEXT_ST structure.
+.I Krb_recvauth
+fills
+.I ktext
+with the
+ticket/authenticator pair read from
+.IR fd ,
+then passes it to
+.IR krb_rd_req .
+
+The
+.I service
+and
+.I inst
+arguments
+specify the expected service and instance for which the ticket was
+generated.  They are also passed to
+.IR krb_rd_req.
+The
+.I inst
+argument may be set to "*" if the caller wishes
+.I krb_mk_req
+to fill in the instance used (note that there must be space in the
+.I inst
+argument to hold a full instance name, see 
+.IR krb_mk_req (3)).
+
+The
+.I faddr
+argument
+should point to the address of the peer which is presenting the ticket.
+It is also passed to
+.IR krb_rd_req .
+
+If the client and server plan to mutually authenticate
+one another,
+the
+.I laddr
+argument
+should point to the local address of the file descriptor.
+Otherwise you can set this argument to NULL.
+
+The
+.I auth_data
+argument
+should point to an allocated AUTH_DAT area.
+It is passed to and filled in by
+.IR krb_rd_req .
+The checksum passed to the corresponding
+.I krb_sendauth
+is available as part of the filled-in AUTH_DAT area.
+
+The
+.I filename
+argument
+specifies the filename
+which the service program should use to obtain its service key.
+.I Krb_recvauth
+passes
+.I filename
+to the
+.I krb_rd_req
+function.
+If you set this argument to "",
+.I krb_rd_req
+looks for the service key in the file
+.IR /etc/kerberosIV/srvtab.
+
+If the client and server are performing mutual authentication,
+the
+.I schedule
+argument
+should point to an allocated Key_schedule.
+Otherwise it is ignored and may be NULL.
+
+The
+.I version
+argument should point to a character array of at least KSEND_VNO_LEN
+characters.  It is filled in with the version string passed by the client to
+.IR krb_sendauth.
+.PP
+.SH KRB_NET_WRITE AND KRB_NET_READ
+.PP
+The
+.I krb_net_write
+function
+emulates the write(2) system call, but guarantees that all data
+specified is written to
+.I fd
+before returning, unless an error condition occurs.
+.PP
+The
+.I krb_net_read
+function
+emulates the read(2) system call, but guarantees that the requested
+amount of data is read from
+.I fd
+before returning, unless an error condition occurs.
+.PP
+.SH BUGS
+.IR krb_sendauth,
+.IR krb_recvauth,
+.IR krb_net_write,
+and
+.IR krb_net_read
+will not work properly on sockets set to non-blocking I/O mode.
+
+.SH SEE ALSO
+
+krb_mk_req(3), krb_rd_req(3), krb_get_phost(3)
+
+.SH AUTHOR
+John T. Kohl, MIT Project Athena
+.SH RESTRICTIONS
+Copyright 1988, Massachusetts Instititute of Technology.
+For copying and distribution information,
+please see the file <mit-copyright.h>.