The AUTH command

AUTH commands contain the following payload:

        typedef struct {
                IMPI_Uint8 key;  // 64 bits
        } IMPI_Auth;

A server may or may not be written such that it requires a 64-bit key from the clients. Servers which do not require such keys will consume an AUTH command silently. Servers which do require such keys will disconnect from any client which either does not pass an AUTH as its first command or does not pass the correct key value.

The AUTH command does not generate any return traffic back to the clients.

Editor's note: The following text has been proposed to replace the current text for this section.

A client must be authenticated to the server before sending any other commands; the AUTH command must be the first command sent to the server. After successful authentication, the client may continue the IMPI startup process. If the authentication is not successful, the server will terminate the client's connection.

Advice to implementors.The protocols that are outlined below, because they are designed to be flexible, may seem somewhat amorphous and non-intuitive when reading. There are comprehensive examples at the end of the description of each authentication protocol.(End of advice to implementors.)

The client and server will each have multiple authentication mechanisms available. As such, they must negotiate and agree on a specific method before authentication can proceed. Two authentication mechanisms are currently mandated for all client and server implementations: the IMPI_AUTH_NONE and IMPI_AUTH_KEY protocols.

Rationale.In order to make the authentication mechanism universal between client and server, the list of standardized methods is enumerated below. It is expected that this list can be expanded in the future, both by user requests for specific forms of authentication, and also with advances in authentication technologies.(End of rationale.)

Two factors determine whether an authentication method can be used in either the client or the server. First, the mechanism needs to be implemented in the software. Second, the mechanism needs to be enabled by the user. If both of these criteria are met, the authentication method is available for negotiation. If either the client or the server has no authentication mechanisms available for negotiation upon invocation, it will abort with an error message.

Since the client and server may have different authentication mechanisms available for negotiation, they must negotiate to decide on a common method to use. The client begins the negotiation by sending a bit mask of the authentication mechanisms available for negotiation to the server.

        typedef struct {
               IMPI_Uint4 auth_mask;   // Mask of which authentication
                                       // methods the client has available 
        } IMPI_Client_auth;

Advice to implementors.The auth_mask is only 32 bits long. While this is probably enough to specify currently available authentication mechanisms, it is possible that it will become desirable to have more than 32 choices in the future. This can be implemented by having the client send multiple IMPI_Client_auth's, and change the value of len in the AUTH IMPI_Cmd header.(End of advice to implementors.)

For each client, the server will compare the client's available methods with its own, and choose the most preferable method that is supported by both. If no common method exists, the server will terminate the connection and display an error message. If a common mechanism exists, the server will inform the client which authentication method it wishes to use, optionally followed by any protocol-specific messages.

        typedef struct {
                IMPI_Int4 which; // Which authentication will be used 
                IMPI_Int4 len;   // Length of follow-on [protocol-specific]
                                 // message(s)
        } IMPI_Server_auth;

The which variable is the enumerated value of the authentication mechanism to be used, with the least significant bit of the first auth_mask being 0, and the most significant bit being 31. The len variable indicates the length of any protocol-specific follow-on message(s) that may be sent by the server immediately after the IMPI_Server_auth message. A len of zero indicates that the server will not send any protocol-specific messages. All authentication messages after the IMPI_Server_auth message are protocol-dependent, and are detailed in the sections below.

The currently supported mechanisms are listed in Table 2.1. Their values are are shown with their symbolic (i.e., #define) name, enumerated values (i.e., their corresponding which value), and their bit mask form (i.e., their corresponding auth_mask value). The symbolic name is synonymous with the enumerated value.

 

Table 2.1: List of standardized authentication methods, shown in enumerated and bit mask forms.

Protocol	Enumerated value	Bit mask form
IMPI_AUTH_NONE	0	0x0001
IMPI_AUTH_KEY	1	0x0002

 

On the command line of the server, the user can specify the order of preference of authentication methods. For example, IMPI_AUTH_NONE (if available for negotiation), should always be last in the order of preference. The following command line syntax will be used to specify the preference list:

        impirun -server N -auth <preference_list>

The <preference_list> is a comma separated list of which value ranges specifying the highest preference on the left. A range can be a single number or a hyphen-separated range of numbers. For example, to specify protocol three as the most preferable, followed by IMPI_AUTH_KEY and IMPI_AUTH_NONE (in that order), the following syntax can be used:

        impirun -server N -auth 3,1-0

If no -auth flag is specified on the command line, the server may choose any authentication mechanism that is available for negotiation on both the client and server.

Advice to implementors.High quality server implementations will choose the ``strongest'' or ``best'' form of authentication when multiple authentication mechanisms are available, even if easier, less-secure methods are also available.(End of advice to implementors.)

IMPI_AUTH_NONE Protocol

Since some sites can guarantee the security of their networks (behind firewalls, etc.), no authentication is necessary. The IMPI_AUTH_NONE method is designed just for this purpose. The presence of the IMPI_AUTH_NONE environment variable allows the client (and server) to make this method available for negotiation.

If the IMPI_AUTH_NONE protocol is chosen, the which value sent to the client will be zero, and the len will also be zero. After the server sends the IMPI_Server_auth message, the authentication is considered successful; no further authentication messages are sent.

Advice to implementors.Even though the IMPI_AUTH_NONE protocol must be deliberately chosen by the user by setting the IMPI_AUTH_NONE environment variable, it is still a ``dangerous'' operation. A high quality implementation of the server should warn the user that a client has connected with IMPI_AUTH_NONE authentication by printing a message to the standard output (or standard error), that includes the network address of the connected client.(End of advice to implementors.)

Example Authentication Using IMPI_AUTH_NONE

The following command lines show two clients attempting to start. client1 sets the IMPI_AUTH_NONE environment variable and invokes impirun on myprog. client2 does not set the IMPI_AUTH_NONE environment variable, and aborts since the user presumably did not make any other authentication mechanisms available.

        client1% setenv IMPI_AUTH_NONE
        client1% impirun [...client args...] myprog

        client2% impirun [...client args...] myprog
        Error: No authentication methods available for negotiation. 
        Aborting.

The server also sets the IMPI_AUTH_NONE variable, and invokes impirun. After printing out its IP and socket numbers, it receives a connection from client1, and prints a warning message stating that IMPI_AUTH_NONE was used to authenticate.

        server% setenv IMPI_AUTH_NONE
        server% impirun -server 2
        12.34.56.78:9000
        Warning: client1.foo.com (12.34.56.78) has authenticated 
        with IMPI_AUTH_NONE.

The messages exchanged by client1 and server were as follows:

        Client1 sends:  IMPI_Cmd { IMPI_CMD_AUTH, 4 }
        Client1 sends:  IMPI_Client_auth { 0x0001 }
        Server sends:   IMPI_Server_auth { 0, 0 }

At this point, the authentication is considered successful for client1.

IMPI_AUTH_KEY Protocol

The IMPI_AUTH_KEY protocol is a simplistic mechanism that involves the client sending a key to the server. If the client's key matches the server's key, the authentication is successful. If this method of authentication is desired, the value of the key is placed in the IMPI_AUTH_KEY environment variable. The presence of a value in this variable allows both the client and the server to make the IMPI_AUTH_KEY protocol available for negotiation.

If this protocol is chosen, the server sends a which value of one, and a len of zero back to the client. The client responds with the following message.

        typedef struct {
                IMPI_Uint8 key; // 64-bit authentication key 
        } IMPI_Auth_key;

If the client's key does not match the key on the server, the server terminates the connection. If the client's key does match, the fact that the server does not terminate the connection indicates a successful authentication.

Example Authentication Using IMPI_AUTH_KEY

The server sets the key value in the environment variable IMPI_AUTH_KEY:

        server% setenv IMPI_AUTH_KEY 5678
        server% impirun -server 2
        12.34.56.78:9000

The following command lines show two clients attempting to start. client1 sets the IMPI_AUTH_KEY environment variable to the same value as the server, and invokes impirun on myprog. client2 sets the IMPI_AUTH_KEY environment variable to the wrong value, and aborts when the server terminates the connection.

        client1% setenv IMPI_AUTH_KEY 5678
        client1% impirun [...client args...] myprog

        client2% setenv IMPI_AUTH_KEY 1234
        client2% impirun [...client args...] myprog
        Error: Server disconnected (wrong authentication key?)

The messages exchanged by the clients and the server are as follows:

        Client1 sends:  IMPI_Cmd { IMPI_CMD_AUTH, 4 }
        Client1 sends:  IMPI_Client_auth { 0x0002 }
        Server sends:   IMPI_Server_auth { 1, 0 }
        Client1 sends:  IMPI_Auth_key { 5678 }

        Client2 sends:  IMPI_Cmd { IMPI_CMD_AUTH, 4 }
        Client2 sends:  IMPI_Client_auth { 0x0002 }
        Server sends:   IMPI_Server_auth { 1, 0 }
        Client2 sends:  IMPI_Auth_key { 1234 }
        Server disconnects