[AFS3-std] rxgk (protocol) error codes

[Benjamin Kaduk]

Some discussion of what the client is to do when it receives these errors 
is below. [ed. only one place] As previously noted, the general case is 
"abort the current operation".  In many cases the client calling rxgk will 
benefit from tracking state of repeated errors received and use that 
information to modify future behavior, but that doesn't seem like it is 
relevant to the protocol spec.


On Fri, 4 Jan 2013, Benjamin Kaduk wrote:

> % RXGK_INCONSISTENCY, "Security module structure inconsistent"
>
> This is essentially "internal error".  E.g., when the incoming packet flags 
> to the server don't match the server's idea of the connection state, trying 
> to allocate a new connection where one exists already, etc..

Might want some logic to completely reinitialize things if this is 
received multiple times in succession, but that may be out of scope for 
the document.

> % RXGK_PACKETSHORT, "Packet too short for security challenge"
>
> This directly mirrors RXKAD, when the server can't send a packet big enough 
> to contain a challenge, or the size of the response packet the server 
> receives is not the expected size of a valid response, or the analogous 
> situations on the other end of the challenge/response.
>
> % RXGK_BADCHALLENGE, "Invalid security challenge"
>
> In light of the previous entry, I take this to mean that the challenge or 
> response was the right size, but otherwise failed to decode or contained 
> nonsense or useless data.  I would not be opposed to merging PACKETSHORT into 
> BADCHALLENGE; in RXKAD PACKETSHORT is not used outside the 
> challenge/response.
>
> % RXGK_BADETYPE, "Encryption type negotiation failed"
>
> For the GSSNegotiate and CombineTokens RPCs, when the client-supplied enctype 
> list is not acceptable to the server.
>
> % RXGK_BADLEVEL, "Security level negotiation failed"
>
> Likewise, but for security level.
>
> % RXGK_BADKEYNO, "Key version number not found"
>
> Analogous to RXKAD's UNKNOWNKEY more than BADKEY (which is for bad-parity or 
> well-known DES keys), when the server doesn't have the key indicated by an 
> incoming token.

It might be okay to retry requests that get this error, under some 
circumstances, possibly with a delay.
It's probably not of enough benefit to note so in the standard though, as 
the general error-handling routines should suffice.

> % RXGK_EXPIRED, "Token has expired"
>
> Seems self-explanatory...
>
> % RXGK_COMPOUND_IDENTITY, "Token's combined identity not usable"
>
> The server doesn't like the compound identity presented by the client solely 
> because it is a compound identity (as opposed to a single-identity token) or 
> the structure of the compound identity is too complicated to be used as input 
> for CombineTokens.  (This one is rather speculative.)
>
> % RXGK_PRINTED, "Printed token not allowed"
>
> The client presented a token that was printed, but such tokens are not 
> allowed for that use case by the server.  E.g., AFSCombineTokens (in the 
> rxgk-afs draft) explicitly MUST NOT accept printed tokens.  On the other 
> hand, we don't talk about printed tokens in this document at all, so maybe 
> this error code should be deferred.
>
> % RXGK_NOTAUTH, "Caller not authorized"
>
> Analogous to RXKADNOAUTH.  RXKAD's use seems a bit unusual, though, such as 
> if the decoded ticket is flagged as 'invalid' or the token start time has not 
> yet arrived.  I guess most of the "permission denied" errors currently in the 
> wild stem from service-specific error tables and are not treated as RX-level 
> errors.
>
> % RXGK_BAD_TOKEN, "Security object was passed a bad token"
>
> Analogous to RXKADBADTICKET.  Token not present, wrong size, fails to decode, 
> zero or negative lifetime, starts too far in the future, too long a lifetime, 
> etc..
>
> % RXGK_SEALED_INCON, "Sealed data inconsistent"
>
> Analogous to RXKADSEALEDINCON.  Bad checksum, sequence/call numer don't 
> match, etc..
>
> % RXGK_DATA_LEN, "User data too long"
>
> Analogous to RXKADDATALEN.  Zero-length iovec entry while decoding/encoding, 
> or packet is too large.
>
>
> I think jaltman also wanted some guidance on how these codes should be used 
> to go into the rxgk document.  I am not opposed to this, and once we get 
> agreement on what things mean (and which ones to include), I can put them in 
> the document somewhere.  It might end up being a new section.

I still don't have a better idea than a new section.

-Ben