mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-15 08:30:02 +00:00
add some docs on the name server
This commit is contained in:
parent
bd64323f36
commit
fbf9d7a342
1 changed files with 85 additions and 0 deletions
85
services/xous-names/README.md
Normal file
85
services/xous-names/README.md
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
# xous-names
|
||||
|
||||
Server IDs (SIDs) are used by processes to send messages to
|
||||
servers. It is thus an attack surface. Furthermore, if a process can
|
||||
forge an SID before a server can claim it, it can “become” the
|
||||
server. Thus, it’s helpful to keep the SID a secret.
|
||||
|
||||
In Xous, an SID is a 128-bit number that, with two exceptions, is only
|
||||
known to the server itself, and an oracle known as `xous-names`.
|
||||
|
||||
SIDs are never revealed to a process. Processes establish connections
|
||||
to servers using a descriptive, human-readable string name. Since the
|
||||
SIDs are random numbers, there is no way to turn the descriptive
|
||||
string into the SID except by resolving it with `xous-names`.
|
||||
|
||||
On boot, a trusted set of processes are started which form the
|
||||
operating system. These must all claim names in the name space before
|
||||
any further processes are started, to prevent later processes from
|
||||
claiming their names.
|
||||
|
||||
The exception to random SIDs are the `xous-names` and
|
||||
`log-server`. These are two well known names that have a defined,
|
||||
fixed SID so that all processes can talk to them; `xous-names` is
|
||||
necessarily well-known as it is the mechanism to resolve further
|
||||
names, `log-server` is necessary for debugging, so that bugs upstream
|
||||
of name resolution can be logged. `xous-names` was picked because
|
||||
`name-server` already has a meaning in the context of DNS.
|
||||
|
||||
A new process that intends to receive messages initializes using the
|
||||
following procedure:
|
||||
|
||||
1. It creates a SID by calling `xous::create_server()` (*note*: this
|
||||
needs to be refactored to take no argument). The SID is a 128-bit
|
||||
GUID.
|
||||
|
||||
2. It registers the SID by sending `xous-names` a “Mutable Borrow”
|
||||
`MemoryMessage` consisting of a `struct` containing a preferred UTF-8
|
||||
name string (limited to how long?) plus its 128-bit SID, as well as an
|
||||
empty slot for the response. The sending process will block until
|
||||
`xous-names` returns.
|
||||
|
||||
3. `xous-names` returns the borrowed memory to the server, with the
|
||||
response field with a code that either affirms the name was
|
||||
registered, or the registration is denied (because the proposed name
|
||||
is already taken or otherwise invalid).
|
||||
|
||||
4. If the registration is denied, the server can attempt to
|
||||
re-register its SID with a different UTF-8 name string by repeating
|
||||
steps 2-3.
|
||||
|
||||
|
||||
A process that would like to send a server a message does so using the following procedure:
|
||||
|
||||
1. It sends `xous-names` a “Mutable Borrow” `MemoryMessage` consisting
|
||||
of a `struct` containing the preferred UTF-8 name of the server it
|
||||
wants to talk to, along with slots for the response codes.
|
||||
|
||||
2. `xous-names` can respond with one of three results: A. affirm the
|
||||
connection, where one of the slots contains the connection ID; B. a
|
||||
flat denial of the connection; or C. a slot containing a request to
|
||||
authenticate.
|
||||
|
||||
Here are the cases worked out:
|
||||
|
||||
A. affirming the connection: `xous-names` would use
|
||||
`MessageSender.pid()` to extract the sender’s PID, and call
|
||||
`ConnectForProcess(PID,SID)` on behalf of the sender. The sender can
|
||||
then use the CID as the first argument to `send_message()`. This is
|
||||
the common case, and many servers follow this path, such as those
|
||||
asking for access to the `ticktimer` or other public services.
|
||||
|
||||
B. flat denial: `xous-names` simply returns a message saying the
|
||||
request was denied. This is also the case when the request is
|
||||
malformed or incorrect. No information shall be leaked about the
|
||||
nature of the denial. Denials are also delayed by exactly 0.5 seconds
|
||||
to eliminate side channels and to rate limit fuzzing requests. Some
|
||||
services (such as the key server) are restricted to only a set of
|
||||
trusted process loaded at boot, and therefore it should not be
|
||||
discoverable.
|
||||
|
||||
C. request to authenticate: `xous-names` responds with a 32-bit nonce
|
||||
that the sending process must hash then sign with a private key to
|
||||
prove that it is authorized to communicate with the requested
|
||||
server. This is used to handle the intermediate case of a user-crafted
|
||||
process requiring elevated access.
|
||||
Loading…
Reference in a new issue