# auth

### MODULE

auth

### MODULE SUMMARY

The Erlang Network Authentication Server

### DESCRIPTION

Authentication determines which nodes are allowed to communicate with each other. In a network of different Erlang nodes, it is built into the system at the lowest possible level. Each node has its `Magic Cookie`, which is an Erlang atom.

Whenever a message is transferred from one node to another, it is accompanied by the `Magic Cookie` of the receiving node. For example, a message transferred from node `A` to node `B` is accompanied by what node `A` believes to be the`Magic Cookie` of node `B`.

When the message arrives at node `B`, the runtime system immediately checks that the accompanying cookie is the right one. If it is, the message is passed on in the normal way. If it is not, the message is transformed into a `badcookie` message, which is sent to the system process `net_kernel`. By default, the `net_kernel` process passes the message to the registered process `auth`, which is then responsible for taking the appropriate action for the unauthorized message. In the standard system, the default action is to shut down connection to that node.

At start-up, the first action of the standard `auth` server is to read a file named `$HOME/erlang.cookie`. An atom is created from the contents of this file and the cookie of the node is set to this atom with the use of `erlang:set_cookie(node(), CookieAtom)`.

If the file does not exist, it is created. The UNIX permissions mode of the file is set to octal 400 (read-only by owner) and filled with a random string. For this reason, the same user, or group of users with identical cookie files, can have Erlang nodes which can communicate freely and without interference from the `Magic Cookie` system. Users who want to run nodes on separate file systems must be certain that their cookie files are identical on the different file systems.

Initially, each node has a random atom assigned as its magic cookie. Once the procedure described above has been concluded, the cookie is set to the contents of the `$HOME/erlang.cookie` file.

To communicate with another node, the magic cookie of that node must be known. The BIF `erlang:set_cookie(Node, Cookie)` sets the cookie for `Node` to `Cookie`. From then on, all messages will be accompanied by the cookie `Cookie`. If the cookie is not correct when messages arrive at `Node`, they are sent to the `auth server` at `Node`. The call `erlang:set_cookie(node(), CookieAtom)` will set the current cookie to `CookieAtom`. It will, however, also set the cookie of all other unknown nodes to `CookieAtom`. In the case of the default `auth` server, this is the first thing done when the system starts. The default then, is to assume that `all` nodes which communicate have the same cookie. In the case of a single user on a single file system, this is indeed true and no further action is required. The original cookie can also be fetched by the BIF `erlang:get_cookie()`.

If nodes which communicate do not have the same cookie, they can be set explicitly on each node with the aid of `erlang:set_cookie(Node, Cookie)`. All messages sent to the node `Node` will then be accompanied by the cookie `Cookie`. Distributed systems with multiple User IDs can be handled in this way.

Initially, the system cookie is set to a random atom, and the (assumed) cookie of all other nodes is initially set to the atom `nocookie`. Thus, an Erlang node is completely unprotected when `erlang:set_cookie(node(), nocookie)` is run. Sometimes, this may be appropriate for systems which are not normally networked, and it can also be appropriate for maintenance purposes.

In the standard system, the default when two nodes are connected is to immediately connect all other involved nodes as well. This way, there is always a fully connected network. If there are nodes with different cookies, this method might be inappropriate and the host OS command line option `-connect_all false` must be issued to the Erlang runtime system. See `global(3)`.

This module uses the two BIFs `erlang:get_cookie()` which returns the magic cookie of the local node, and `erlang:set_cookie(Node,Cookie)` which sets the magic cookie of `Node` to `Cookie`. If `Node` is the user's node, the cookie of all other unknown nodes are also set to `Cookie` by this BIF.

### EXPORTS

`start()`

Starts the `auth` server.

`stop()`

Stops the `auth` server.

`open(Name)`

This function opens up the server with the name `Name`. If, for example, node `N` is run with the cookie `C`, it is impossible for other nodes with other cookies to communicate with node `N`. The call `open/1` opens the server with the registered name `Name` so it can be accessed by any other node, irrespective of cookie. The call must be executed on both nodes to have any effect. All messages to the server must have the form `Name ! Msg` and all replies from the server `{Name, Reply}`, or `{Name, Node, Reply}`. With this feature, it is possible to perform specific tasks on publicly announced Erlang network servers.

`is_auth(Node)`

Returns the value `yes` if communication with `Node` is authorized, `no` if `Node` does not exist or communication is not authorized.

`exists(Node)`

Returns `yes` if `Node` exists, otherwise `no`.

`cookie()`

Reads `cookie` from `$HOME/.erlang.cookie` and sets it. This function is used by the `auth` server at start-up.

`node_cookie(Node, Cookie)`

If the cookie of `Node` is known to the user as `Cookie` but the user's cookie is not known at `Node`, this function informs `Node` of the identity of the user's cookie.

`node_cookie([Node, Cookie])`

Another version of the previous function with the arguments in a list which can be given on the host OS command line.

`cookie([Cookie])`

Equivalent to `erlang:set_cookie(node(), Cookie)`, but with the argument in a list so it can be given on the host OS command line.

### AUTHORS

Claes Wikstrom - support@erlang.ericsson.se

kernel 2.7.2
Copyright © 1991-2002 Ericsson Utvecklings AB