DIRECTORY
AuthenticationP14V2 USING [CallProblem, Credentials, CredentialsType, HashedPassword, Key, Problem, Verifier, Which],
BasicTime USING [GMT],
CHNameP2V0 USING [Name],
Rope USING [ROPE],
XNS USING [Host]
;
XNSAuth:
CEDAR
DEFINITIONS
~ {
OPEN Auth: AuthenticationP14V2, CHName: CHNameP2V0;
Introduction
This interface is copied almost verbatim from Services 8.0. Refer to the Services 8.0 Prograammer's Guide for details. See also the Courier Authentication program, version 2 (XSIS 098404).
Copied Types
ROPE: TYPE ~ Rope.ROPE;
GMT: TYPE ~ BasicTime.GMT;
Name: TYPE ~ CHName.Name;
HostNumber: TYPE ~ XNS.Host;
CredentialsType: TYPE ~ Auth.CredentialsType;
Credentials: TYPE ~ Auth.Credentials;
Verifier: TYPE ~ Auth.Verifier;
HashedPassword: TYPE ~ Auth.HashedPassword;
Key: TYPE ~ Auth.Key;
Errors
Nearly every procedure in this interface will raise ERROR ERROR if given a NIL or bogus Identity or Conversation.
The following ERRORs are "inherited" from the Courier program.
AuthenticationError:
VAR ERROR [problem: Auth.Problem];
← Auth.AuthenticationError;
Problem: TYPE ~ Auth.Problem;
CallError:
VAR ERROR[problem: Auth.CallProblem, whichArg: Auth.Which];
← Auth.CallError;
CallProblem: TYPE ~ Auth.CallProblem;
Which: TYPE ~ Auth.Which;
Identities
An Identity consists of a <name, password> pair and some cached information. You need an identity to initiate a conversation with a server. The correct way to get an identity for the currently logged in Cedar user is to call UserCredentials.GetIdentity — this returns a single identity that is shared among all clients (and so is guaranteed to have a big cache of initiator credentials as described below) and is guaranteed to be destroyed on rollback. For other uses — e.g. Cedar-based servers — identities can be created and destroyed with the following procedures.
Identity: TYPE ~ REF;
MakeIdentity: PROC[name: Name, password: ROPE,
credentialsType: CredentialsType ← strong, check: BOOL ← TRUE]
RETURNS [identity: Identity];
MakeStrongIdentityUsingKey:
PROC[name: Name, key: Key, check:
BOOL ←
TRUE]
RETURNS [identity: Identity];
Create an identity. Each call creates an independent identity, with an independent cache of conversations. For efficiency, processes should share a single identity whenever possible rather than use separate identities.
The simple CredentialsType is intended for things like typewriters that aren't smart enough to do DES encryption; its use in Cedar is discouraged.
ERRORS: AuthenticationError, CallError (only if check is TRUE).
DestroyIdentity:
PROC [identity: Identity];
Destroy the identity, making it (and any conversations created with it) unusable by anybody else with a REF to it. Don't call DestroyIdentity unless that's really what you want — it's safe just to drop the identity on the floor.
ERRORS: None.
GetNullIdentity:
PROC
RETURNS [identity: Identity];
Returns a "null" identity — a simple identity with a null user name and password. A few services/operations are willing to accept this.
Initiator
A Conversation contains credentials that identify me (the initiator of the conversation) to a specific conversant (the recipient of the conversation). Conversations are cached per identity.
Conversation: TYPE ~ REF;
defaultCredentialsLifetime: CARD ~ (120*60);
Initiate:
PROC [identity: Identity, recipientName: Name,
seconds:
CARD ← defaultCredentialsLifetime]
RETURNS [conversation: Conversation];
Create a conversation for the specified recipient. The credentials in the conversation are guaranteed not to expire before seconds have elapsed.
ERRORS: AuthenticationError, CallError (for strong identities); None (for simple identities).
Refresh:
PROC [conversation: Conversation,
seconds:
CARD ← defaultCredentialsLifetime];
Guarantee the credentials in conversation won't expire before seconds have elapsed, . A new set of strong credentials doesn't expire for a long time (~ a day), and simple credentials never expire. Thus, for reasonable values of seconds, calling Refresh is essentially free.
ERRORS: AuthenticationError, CallError (for strong conversations); None (for simple conversations).
Terminate:
PROC [conversation: Conversation];
It's okay to drop a conversation on the floor, but calling Terminate gets it back into the conversation cache sooner.
ERRORS: None.
GetCredentials:
PROC [conversation: Conversation]
RETURNS [credentials: Credentials];
Extract credentials from a conversation.
ERRORS: None.
SetRecipientHostNumber:
PROC [conversation: Conversation,
recipientHostNumber: HostNumber];
The recipient host number is used in constructing strong verifiers. For strong credentials, SetRecipientHostNumber must be called before calling GetNextVerifier.
ERRORS: None.
GetNextVerifier:
PROC [conversation: Conversation]
RETURNS [verifier: Verifier];
ERRORS: None.
ReplyVerifierChecks:
PROC [conversation: Conversation, verifier: Verifier]
RETURNS [ok:
BOOL];
ERRORS: AuthenticationError[inappropriateCredentials] if simple credentials are used; any other problems just return FALSE.
Recipient
Authenticate:
PROC [myIdentity: Identity,
hisCredentials: Credentials, hisVerifier: Verifier,
allowSimpleCredentials:
BOOL ←
FALSE,
useExpiredCredentials:
BOOL ←
FALSE]
RETURNS [hisName: Name];
Test whether hisCredentials and hisVerifier are legitimate. myIdentity must be strong unless hisCredentials are known to be simple — it is possible to authenticate his simple credentials with my strong identity, but not the other way around. If useExpiredCredentials is true, the expiration date on his strong credentials is not checked (simple credentials never expire).
ERRORS: CallError (for simple credentials only); AuthenticationError (for simple or strong credentials).
AuthenticateAndReply:
PROC [myIdentity: Identity,
hisCredentials: Credentials, hisVerifier: Verifier,
useExpiredCredentials:
BOOL ←
FALSE]
RETURNS [hisName: Name, replyVerifier: Verifier];
Like Authenticate, but compute a reply verifier as well. myIdentity and hisCredentials must be strong (reply verifiers don't make sense with simple credentials).
ERRORS: AuthenticationError.
Key and password administration
For all the following procedures, myIdentity must be strong. The Create... and Delete... procedures require that myIdentity be an Authentication Service Wheel.
ERRORS: AuthenticationError, CallError.
CreateStrongKey: PROC [myIdentity: Identity, name: Name, newKey: Key];
DeleteStrongKey: PROC [myIdentity: Identity, name: Name];
CreateSimpleKey: PROC [myIdentity: Identity, name: Name, newKey: HashedPassword];
DeleteSimpleKey: PROC [myIdentity: Identity, name: Name];
ChangeMyPasswords: PROC [myIdentity: Identity, newPassword: ROPE,
changeStrong: BOOL ← TRUE, changeSimple: BOOL ← TRUE];
ChangeMyStrongKey: PROC [myIdentity: Identity, newKey: Key];
ChangeMySimpleKey: PROC [myIdentity: Identity, newKey: HashedPassword];
Utilities
ERRORS: None.
StrongKeyFromPassword: PROC [password: ROPE] RETURNS [key: Key];
SimpleKeyFromPassword: PROC [password: ROPE] RETURNS [HashedPassword];
GetCredentialsType: PROC [credentials: Credentials]
RETURNS [CredentialsType];
GetConversationDetails: PROC [conversation: Conversation] RETURNS [
recipientName: Name, recipientHostNumber: HostNumber, credentials: Credentials, conversationKey: Key, owner: Identity];
GetIdentityDetails: PROC [identity: Identity] RETURNS [
name: Name, password: ROPE, credentialsType: CredentialsType];
GetCredentialsDetails:
PROC [myKey: Key, hisCredentials: Credentials]
RETURNS [
ok:
BOOL, credentialsType: CredentialsType, conversationKey: Key,
expirationTime:
GMT, hisName: Name];
If hisCredentials are simple, myKey is not used and the returned conversationKey and expirationTime are uninteresting.
}.