\begindata{text, 268649924}
\textdsversion{11}
\define{italic
menu:[Font,Italic]
attr:[FontFace Italic Int Set]}
\define{bold
menu:[Font,Bold]
attr:[FontFace Bold Int Set]}
\define{chapter
menu:[Title,Chapter]
attr:[Justification Centered Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{section
menu:[Title,Section]
attr:[Justification Centered Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{subsection
menu:[Title,Subsection]
attr:[Justification LeftJustified Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{paragraph
menu:[Title,Paragraph]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Italic Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{bigger
menu:[Font,Bigger]
attr:[FontSize PreviousFontSize Point 2]}
\define{indent
menu:[Region,Indent]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]}
\define{typewriter
menu:[Font,Typewriter]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{display
menu:[Region,Display]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[Justification LeftJustified Point 0]}
\define{example
menu:[Region,Example]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Justification LeftJustified Point 0]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{description
menu:[Region,Description]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Indent LeftEdge Inch -32768]}
\define{quotation
menu:[Region,Quotation]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[FontFace Italic Int Set]}
\define{subscript
menu:[Font,Subscript]
attr:[Script PreviousScriptMovement Point 131072]
attr:[FontSize PreviousFontSize Point -2]}
\define{superscript
menu:[Font,Superscript]
attr:[Script PreviousScriptMovement Point -393216]
attr:[FontSize PreviousFontSize Point -2]}
\define{smaller
menu:[Font,Smaller]
attr:[FontSize PreviousFontSize Point -2]}
\define{heading
menu:[Title,Heading]
attr:[LeftMargin LeftMargin Inch -13107]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{majorheading
menu:[Title,MajorHeading]
attr:[Justification Centered Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{formatnote
menu:[Region,FormatNote]
attr:[Flags PassThru Int Set]}
\define{subheading
menu:[Title,Subheading]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{center
menu:[Justify,Center]
attr:[Justification Centered Point 0]}
\define{flushleft
menu:[Justify,FlushLeft]
attr:[Justification LeftJustified Point 0]}
\define{flushright
menu:[Justify,FlushRight]
attr:[Justification RightJustified Point 0]}
\define{leftindent
menu:[Region,LeftIndent]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{article
menu:[Title,Article]
attr:[Justification Centered Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize ConstantFontSize Point 24]}
\define{subpara
menu:[Title,Subpara]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{subsubpara
menu:[Title,Subsubpara]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Italic Int Set]}

\subsection{The Authentication Package}


\paragraph{Overview}

This package consists of routines to deal with authenticationin Andrew.  The routines are divided roughly into three groups: routines used by programs such as login to get tokens and other information from the Andrew Authentication Manager, routines that are PIOCTLs to the Andrew Cache Manager, and routines used by the Andrew File Manager to communicate with the Authentication Manager.


\paragraph{Description}

The login program provides an example of how to use this package.  To authenticate a user in the Andrew File System, the login program first calls U_InitRPC to initialize the remote procedure call package.  Login then gets the user name and password and calls U_Authenticate, passing in the user name and password and receiving a pair of tokens in return, a secret token and an encrypted token.  A U_SetLocalTokens call is made to inform the Andrew Cache Manager about this user, with the SetPag parameter set to true.  The SetPag system call associates the tokens with the user's process group.  This prevents a malicious user from stealing someone else's tokens and masquerading as that person, since each user is in a different process group.  If a call fails at any step along the way, the Authentication Manager fails and the user is limited to logging in locally, without being authenticated in the Andrew File System.  This means that the user has the privileges associated with System:Anyuser only; if a file is protected against System:Anyuser, the user will not be able to access it, even if he or she is the owner, since the server does not know who he or she really is.


\paragraph{Interface specification}

\subpara{Data Structures}
These structures are defined in rauth.h, which is created from rauth.xg.

The secret and clear tokens are both used in authenticating users.

\example{struct SecretToken \{
	AuthMagic MagicString;
	long AuthHandle;
	long Noise1;
	long ViceId;
	long BeginTimestamp;
	long Noise2;
	long EndTimestamp;
	long Noise3;
	auth_EncryptionKey HandShakeKey;
	long Noise4;
\};
typedef struct SecretToken SecretToken;}

\example{struct EncryptedSecretToken \{
	char data[56];
\};
typedef struct EncryptedSecretToken EncryptedSecretToken;}

\example{struct ClearToken \{
	long AuthHandle;
	auth_EncryptionKey HandShakeKey;
	long ViceId;
	long BeginTimestamp;
	long EndTimestamp;
\};
typedef struct ClearToken ClearToken;}

\subpara{User-Level Authentication Routines}
These routines are used by user-level  processes (such as login, su, etc) to do authentication.

\subsubpara{U_Authenticate}
Talks to an Authentication Manager and obtains tokens on behalf of user \italic{uName}, who claims to have password \italic{uPasswd}.  Gets back and the clear and secret tokens for this user.

\example{int \bold{U_Authenticate}(uName, uPasswd, cToken, sToken)
char			*uName;
char			*uPasswd;
EncryptedSecretToken	*sToken;
ClearToken		*cToken;}

\italic{U_CellAuthenticate}
Talks to an Authentication Manager for administrative cell \italic{cellID} on behalf of user \italic{uName}, who claims to have password \italic{uPasswd}.  Gets back the clear and secret tokens for this user.

\example{int \bold{U_CellAuthenticate}(uName, uPasswd, cellID, cToken, sToken)
char			*uName;
char			*uPasswd;
char			*cellID;
EncryptedSecretToken	*sToken;
ClearToken		*cToken;}

\italic{U_CellAuthenticateComm}
Talks to an Authentication Manager for administrative cell \italic{cellID} on behalf of user \italic{uName}, who claims to have password \italic{uPasswd}.  Gets back the clear and secret tokens for this user, as well as the name of the base common directory for the given cell (under which such things as the White Pages can be found).  Parameter \italic{commDirectory} is expected to point to a character array with room for at least 128 characters.

\example{int \bold{U_CellAuthenticateComm}(uName, uPasswd, cellID, cToken, sToken,
					commDirectory)
char			*uName;
char			*uPasswd;
char			*cellID;
EncryptedSecretToken	*sToken;
ClearToken		*cToken;
char			*commDirectory;

}\italic{U_CellGetCommonDir}
Talks to an Authentication Manager for administrative cell \italic{cellID} and gets back the name of the base common directory for the given cell (under which such things as the White Pages can be found).  Parameter \italic{commDirectory} is expected to point to a character array with room for at least 128 characters.

\example{int \bold{U_CellGetCommonDir}(cellID, commDirectory)
char *cellID;
char *commDirectory;}

\subsubpara{U_ChangePasswd}
Talks to the Authentication Manager on the control server and changes the password for \italic{uName} to \italic{newPasswd} if \italic{myName} is the same as \italic{uName} or user \italic{uName} is a system administrator.  \italic{myPasswd} is used to validate \italic{myName}.

\example{int \bold{U_ChangePassword}(uName, newPasswd, myName, myPasswd)
char	*uName;
char	*newPasswd;
char	*myName;
char	*myPasswd;}

\subsubpara{U_InitRPC}
Initializes the RPC package, which is used to communicate with the Authentication Manager.

\example{\bold{U_InitRPC}()}

\subsubpara{U_AuthErrorMsg}
Returns a string that describes the  authentication error that corresponds to return code \italic{rc}.

\example{char *\bold{U_AuthErrorMsg}(rc)
int rc;}

\subsubpara{U_BindToServer}
Binds to the Authentication Manager on behalf of \italic{uName} using \italic{uPasswd} as the password.  Sets \italic{RPCid} to the value of the connection ID.  If \italic{write} is true, the Authentication Server on the System Control Machine (SCM) is chosen.

\example{int \bold{U_BindToServer}(write, uName, uPasswd, RPCid)
int			  write;
char			 *uName;
char			 *uPasswd;
struct r_connection	**RPCid;}

\subsubpara{U_CellBindToServer}
Binds to the Authentication Manager in administrative cell \italic{cellID} on behalf of \italic{uName} using \italic{uPasswd} as the password.  Sets \italic{RPCid} to the value of the connection ID.  If \italic{write} is true, the Authentication Server on the System Control Machine (SCM) is chosen.

\example{int \bold{U_CellBindToServer}(write, uName, uPasswd, cellID, RPCid)
int			  write;
char			 *uName;
char			 *uPasswd;
char			 *cellID;
struct r_connection	**RPCid;

}
\subpara{Andrew Cache Manager Routines}
These routines are used by user-level processes to deal with the Andrew Cache Manager.

\subsubpara{U_SetLocalTokens}
Tells the Andrew Cache Manager about the clear and secret tokens obtained from the Authentication Manager.  If setPag is true, a setpag system call is made.  Returns 0 on success, -1 on failure.

\example{int \bold{U_SetLocalTokens}(IN setPag, IN cToken, IN sToken)
int			 setPag;
ClearToken		*cToken;
EncryptedSecretToken	*sToken;}

\subsubpara{U_CellSetLocalTokens}
Tells the Andrew Cache Manager about the clear and secret tokens obtained from an Authentication Manager in administrative cell \italic{cellID}.  If \italic{setPag} is true, a SetPag system call is made.  If \italic{primaryFlag} is true, the tokens are marked as representing the primary identity for the user.  Returns 0 on success, -1 on failure.

\example{int \bold{U_CellSetLocalTokens}(IN setPag, IN cToken, IN sToken, IN cellID,
					IN primaryFlag)
int			 setPag;
ClearToken		*cToken;
EncryptedSecretToken	*sToken;
char			*cellID;
int			 primaryFlag;
}
\subsubpara{U_GetLocalTokens}
Obtains the clear and secret tokens from the Andrew Cache Manager, which it places in \italic{cToken} and \italic{sToken}.  (Note: at the present time these are fixed-length data structures).  Returns 0 on success, -1 on failure.

\example{int \bold{U_GetLocalTokens}(OUT cToken, OUT sToken)
ClearToken		*cToken;
EncryptedSecretToken	*sToken;}

\subsubpara{U_CellGetLocalTokens}
Obtains the clear and secret tokens from the Andrew Cache Manager, which it places in \italic{cToken} and \italic{sToken}.  If \italic{useCellEntry} is true, the Cache Manager returns additional information relating to administrative cells.  Specifically, the tokens returned by the Cache Manager correspond to the \italic{cellEntry}'th cell associated with the caller, where \italic{cellEntry} >= 0.  Also, \italic{cellID} is filled with the string name for the cell the tokens are valid in and \italic{pIsPrimary }is set to true if the tokens represent the user's primary identity. (Note: At the present time, ClearToken and EncryptedSecretToken are fixed-length data structures).  Returns 0 on success, \typewriter{EDOM} if the Cache Manager's \italic{cellEntry'}th mapping is unused (or \italic{cellEntry} < 0), and -1 on failure.

\example{int \bold{U_CellGetLocalTokens}(IN useCellEntry, IN cellentry, OUT cToken,
					OUT sToken, OUT cellID, OUT pIsPrimary)
int			 useCellEntry;
int			 cellEntry;
ClearToken		*cToken;
EncryptedSecretToken	*sToken;
char			*cellID;
int			*pIsPrimary;
}
\subsubpara{U_DeleteLocalTokens}
Deletes internal state for the caller's Vice ID.  Returns 0.

\example{int \bold{U_DeleteLocalTokens}()}


\subpara{Andrew File Manager Routines}
These routines are used by the Andrew File Manager to do authentication.

\subsubpara{GetKeysFromToken}
Derives \italic{hKey} and \italic{sKey} from ClientIdent using one or the other of the global server keys to decrypt the secret token in \italic{cIdent}.   Returns 0 if the handshake is to be continued, -1 if not.  The \italic{sKey} is synthesized.  If 0 is returned, \italic{cIdent}'s body has been decrypted and converted to host order --- this will be passed on to the new connection routine, which can access the SecretToken fields.

\example{int \bold{GetKeysFromToken}(cIdent, hKey, sKey)
    RPC2_CountedBS	*cIdent;
    RPC2_EncryptionKey	 hKey, sKey;}

\subsubpara{SetServerKeys}
Sets the global server keys to the specified value.  Either of the keys may be NULL, in which case the corresponding key is merely marked invalid.

\example{void \bold{SetServerKeys}(serverKey1, serverKey2)
    RPC2_EncryptionKey serverKey1, serverKey2;}
\formatnote{.bp}
\enddata{text,268649924}