update README on xous-names, and refine the API a bit

This commit is contained in:
bunnie 2021-01-05 02:28:27 +08:00
parent 1075dff559
commit 61409bb94c
5 changed files with 167 additions and 126 deletions

View file

@ -5,10 +5,11 @@ use blitstr::{Cursor, GlyphStyle};
use com::*; use com::*;
use core::fmt::Write; use core::fmt::Write;
use graphics_server::{Circle, DrawStyle, Line, PixelColor, Point, Rectangle}; use graphics_server::{Circle, DrawStyle, Line, PixelColor, Point, Rectangle};
use xous_names::api::Registration;
use log::{error, info}; use log::{error, info};
use xous::String; use xous::String;
use xous::ipc::*; use xous::ipc::*;
use xous_names::api::Registration;
use core::convert::TryFrom; use core::convert::TryFrom;
@ -138,7 +139,7 @@ fn shell_main() -> ! {
let ticktimer_server_id = xous::SID::from_bytes(b"ticktimer-server").unwrap(); let ticktimer_server_id = xous::SID::from_bytes(b"ticktimer-server").unwrap();
let log_server_id = xous::SID::from_bytes(b"xous-log-server ").unwrap(); let log_server_id = xous::SID::from_bytes(b"xous-log-server ").unwrap();
let com_id = xous::SID::from_bytes(b"com ").unwrap(); let com_id = xous::SID::from_bytes(b"com ").unwrap();
let ns_id = xous::SID::from_bytes(b"xousnames-server").unwrap(); let ns_id = xous::SID::from_bytes(b"xous-name-server").unwrap();
let log_conn = xous::connect(log_server_id).unwrap(); let log_conn = xous::connect(log_server_id).unwrap();
let graphics_conn = xous::connect(graphics_server_id).unwrap(); let graphics_conn = xous::connect(graphics_server_id).unwrap();
@ -219,12 +220,7 @@ fn shell_main() -> ! {
.expect("unable to clear region"); .expect("unable to clear region");
let mut firsttime = true; let mut firsttime = true;
let mut registration = Registration { let mut registration = Registration::new();
sid: xous::SID::from_u32(0, 0, 0, 0,),
name: *b"test name ",
name_len: b"test name".len(),
success: false
};
let mut sendable_registration = Sendable::new(registration) let mut sendable_registration = Sendable::new(registration)
.expect("can't create sendable registration structure"); .expect("can't create sendable registration structure");
loop { loop {
@ -361,8 +357,11 @@ fn shell_main() -> ! {
get_batt_stats_nb(com_conn).expect("Can't get battery stats from COM"); get_batt_stats_nb(com_conn).expect("Can't get battery stats from COM");
info!("Test NS lookup"); info!("Test NS lookup");
sendable_registration.success = false; sendable_registration.success = false;
let test_name = b"A test Name!";
sendable_registration.name[..test_name.len()].clone_from_slice(test_name);
sendable_registration.name_len = test_name.len();
info!("NS lookup input: {:?}", sendable_registration.success); info!("NS lookup input: {:?}", sendable_registration.success);
sendable_registration.lend_mut(ns_conn, xous_names::api::ID_REGISTER_NAME); sendable_registration.lend_mut(ns_conn, sendable_registration.mid());
info!("NS lookup result: {:?}", sendable_registration.success); info!("NS lookup result: {:?}", sendable_registration.success);
} }
} else { } else {

View file

@ -6,80 +6,106 @@ forge an SID before a server can claim it, it can “become” the
server. Thus, it’s helpful to keep the SID a secret. 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 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`. known to the server itself, and an oracle known as `xous-name-server`.
SIDs are never revealed to a process. Processes establish connections SIDs are never revealed to a process. Processes establish connections
to servers using a descriptive, human-readable string name. Since the to servers using a descriptive, human-readable string name. Since the
SIDs are random numbers, there is no way to turn the descriptive SIDs are random numbers, there is no way to turn the descriptive
string into the SID except by resolving it with `xous-names`. string into the SID except by resolving it with `xous-name-server`.
On boot, a trusted set of processes are started which form the On boot, a trusted set of processes are started which form the
operating system. These must all claim names in the name space before operating system. These must all claim names in the name space before
any further processes are started, to prevent later processes from any further processes are started, to prevent later processes from
claiming their names. claiming their names.
The exception to random SIDs are the `xous-names` and The exception to random SIDs are the `xous-name-server` and
`log-server`. These are two well known names that have a defined, `xous-log-server ` (note the trailing space). These are two well known names that have a defined,
fixed SID so that all processes can talk to them; `xous-names` is fixed SID so that all processes can talk to them; `xous-name-server` is
necessarily well-known as it is the mechanism to resolve further necessarily well-known as it is the mechanism to resolve further
names, `log-server` is necessary for debugging, so that bugs upstream names, `xous-log-server ` is necessary for debugging, so that bugs upstream
of name resolution can be logged. `xous-names` was picked because of name resolution can be logged. `xous-name-server` was picked because
`name-server` already has a meaning in the context of DNS. `name-server` already has a meaning in the context of DNS.
A new process that intends to receive messages initializes using the A new process that intends to receive messages initializes using the
following procedure: following procedure:
1. It creates a SID by calling `xous::create_server()` (*note*: this 1. It creates a `Registration` IPC structure by wrapping it in `xous::ipc::Sendable`,
needs to be refactored to take no argument). The SID is a 128-bit using the `new()` initializer.
GUID.
2. It registers the SID by sending `xous-names` a “Mutable Borrow” 2. It copies a preferred ASCII name string, limited to 64 characters,
`MemoryMessage` consisting of a `struct` containing a preferred UTF-8 into the `Registration` record. It then uses the `.lend_mut()` method
name string (limited to how long?) plus its 128-bit SID, as well as an on the Sendable Registration to lend the structure to `xous-name-server`.
empty slot for the response. The sending process will block until The sending process will block until `xous-name-server` returns.
`xous-names` returns.
3. `xous-names` returns the borrowed memory to the server, with the 3. `xous-name-server` returns the borrowed memory to the server, with the
response field with a code that either affirms the name was response field with a code that either affirms the name was
registered, or the registration is denied (because the proposed name registered, or the registration is denied (because the proposed name
is already taken or otherwise invalid). is already taken or otherwise invalid). In the case that the registration
is affirmed, the SID field in `Registration` contains the assigned SID
of calling process.
4. If the registration is denied, the server can attempt to 4. If the registration is denied, the server can attempt to
re-register its SID with a different UTF-8 name string by repeating re-register its SID with a different ASCII name string by repeating
steps 2-3. steps 2-3.
A process that would like to send a server a message does so using the following procedure: 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 1. It creates a `Lookup` IPC structure by wrapping it in a `xous::ipc::Sendable`,
of a `struct` containing the preferred UTF-8 name of the server it using the `new()` initializer.
wants to talk to, along with slots for the response codes.
2. `xous-names` can respond with one of three results: A. affirm the 2. It populates the Lookup structure with the name of the server it is looking up.
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 3. It uses `.lend_mut()` method to send `xous-name-server` a “Mutable Borrow”
authenticate. `MemoryMessage`.
4. `xous-name-server` 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: Here are the cases worked out:
A. affirming the connection: `xous-names` would use A. affirming the connection: `xous-name-server` would use
`MessageSender.pid()` to extract the sender’s PID, and call `MessageSender.pid()` to extract the sender’s PID, and call
`ConnectForProcess(PID,SID)` on behalf of the sender. The sender can `ConnectForProcess(PID,SID)` on behalf of the sender. The sender can
then use the CID as the first argument to `send_message()`. This is 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 the common case, and many servers follow this path, such as those
asking for access to the `ticktimer` or other public services. asking for access to the `ticktimer` or other public services.
B. flat denial: `xous-names` simply returns a message saying the B. flat denial: `xous-name-server` simply returns a message saying the
request was denied. This is also the case when the request is request was denied by setting `success` to `false`. This is also the case
malformed or incorrect. No information shall be leaked about the 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 nature of the denial. Denials are also delayed to the nearest 0.5 second interval since boot
to eliminate side channels and to rate limit fuzzing requests. Some to eliminate side channels and to rate limit fuzzing requests. Some
services (such as the key server) are restricted to only a set of services (such as the key server) are restricted to only a set of
trusted process loaded at boot, and therefore it should not be trusted process loaded at boot, and therefore it should not be
discoverable. discoverable.
C. request to authenticate: `xous-names` responds with a 32-bit nonce C. request to authenticate: `xous-name-server` responds with `success` set
that the sending process must hash then sign with a private key to to `false`, but `authenticate_request` to `true`. The `pubkey_id` field
prove that it is authorized to communicate with the requested is populated with the ID of an acceptable Ed25519 public key for authentication, and
server. This is used to handle the intermediate case of a user-crafted a 256-bit challenge nonce is provided in the `challenge` field. Authentication
process requiring elevated access. consists of the requesting server proving that it has knowledge of a shared
secret, namely, an Ed25519 private key.
Upon generating the request to authenticate, `xous-name-server` computes
the correct response to the challenge and stores it in a table with
a timestamp.
The sending process must then sign the `challenge` and return an
`Authenticate` message, constructed similarly to the `Lookup`
message but with the `response_to_challenge` field filled out. It must
do this before `AUTHENTICATE_TIMEOUT` milliseconds have passed.
The server, upon receipt of an `Authenticate` message, merely checks
if the `response_to_challenge` matches any response stored in its
table, and if it does, it accepts the process as authenticated. It is
cryptographically unlikely for there to be a collision in the table;
however, this implementation is weak to an attacker potentially
stealing the response and using it. That being said, if an attacker
already has that level of control in the calling process, there
are bigger problems.
The `AUTHENTICATE_TIMEOUT` field is used to give `xous-name-server`
a chance to depopulate the response table over time, so that it
does not "leak" memory.

View file

@ -1,92 +1,91 @@
use xous::{Message, ScalarMessage, SID}; use xous::{Message, ScalarMessage, SID};
pub struct Registration {
pub sid: SID,
pub name: [u8; 64],
pub name_len: usize,
pub success: bool,
// _padding: [u8; 4096-(core::mem::size_of::<SID>() + 64 + core::mem::size_of::<usize>() + core::mem::size_of::<bool>],
}
pub struct Lookup {
sid: SID,
name: [u8; 64],
name_len: usize,
success: bool,
autheticate: bool,
challenge: [u32; 8],
response: [u32; 8],
// _padding: [u8; 4096-(core::mem::size_of::<SID>() + 64 + core::mem::size_of::<usize>() + core::mem::size_of::<bool>],
}
pub const ID_REGISTER_NAME: usize = 0; pub const ID_REGISTER_NAME: usize = 0;
pub const ID_LOOKUP_NAME: usize = 1; pub const ID_LOOKUP_NAME: usize = 1;
pub const ID_AUTHENTICATE: usize = 2; pub const ID_AUTHENTICATE: usize = 2;
/* pub const AUTHENTICATE_TIMEOUT: usize = 10_000; // time in ms that a process has to respond to an authentication request
#[derive(Debug)] #[derive(Debug)]
pub enum Opcode { pub struct Registration {
/// Register a 128-bit SID with a preferred, unique lookup name mid: usize,
RegisterName(Registration), pub sid: SID,
// we use fixed-length, u8-only records to pass server names. This is different from
/// Retrieve the 128-bit SID for a server, given its unique lookup name // your typical Rust String object; but, a key restriction on IPC calls is that the size
LookupName(Lookup), // of structures must be (1) statically known and (2) contain no references. Therefore
// the name is a pre-allocated, 64-length u8 array, and the length of the name is explicitly encoded.
/// Authenticate to the name server, based on nonce embedded in LookupName response pub name: [u8; 64],
/// this is always as a response to a lookupname that reqeusts the authentication challenge-response pub name_len: usize,
Authenticate(Lookup), pub success: bool,
} }
impl<'a> core::convert::TryFrom<&'a Message> for Opcode { impl Registration {
type Error = &'static str; pub fn mid(&self) -> usize { self.mid }
fn try_from(message: &'a Message) -> Result<Self, Self::Error> {
match message {
Message::MutableBorrow(m) => {
if m.id as u16 == ID_REGISTER_NAME {
let registration: Registration = unsafe {
&mut *(m.buf.as_mut_ptr() as *mut Registration)
};
Ok(Opcode::RegisterName(registration))
}
}
_ => Err("unhandled message type"),
}
}
}*/
/* No "Into<>" methods -- we use the ipc::lend() to create messages pub fn new() -> Self {
impl Into<Message> for Opcode { Registration {
fn into(self) -> Message { mid: ID_REGISTER_NAME,
match self { sid: xous::SID::from_u32(0,0,0,0),
Opcode::Reset => Message::Scalar(ScalarMessage { name: [0; 64],
id: 1, name_len: 0,
arg1: 0, success: false,
arg2: 0,
arg3: 0,
arg4: 0,
}),
Opcode::RecalculateSleep => Message::Scalar(ScalarMessage {
id: 131072,
arg1: 0,
arg2: 0,
arg3: 0,
arg4: 0,
}),
Opcode::ElapsedMs => Message::BlockingScalar(ScalarMessage {
id: 4919,
arg1: 0,
arg2: 0,
arg3: 0,
arg4: 0,
}),
Opcode::SleepMs(ms) => Message::BlockingScalar(ScalarMessage {
id: 3,
arg1: ms,
arg2: 0,
arg3: 0,
arg4: 0,
}),
} }
} }
} }
*/
#[derive(Debug)]
pub struct Lookup {
mid: usize,
pub cid: xous::CID,
pub name: [u8; 64],
pub name_len: usize,
pub success: bool,
pub authenticate_request: bool,
pub pubkey_id: [u8; 20], // 160-bit pubkey ID encoded in network order (big endian)
pub challenge: [u32; 8],
}
impl Default for Lookup {
fn default() -> Self {
Lookup {
mid: ID_LOOKUP_NAME,
cid: 0,
name: [0; 64],
name_len: 0,
success: false,
authenticate_request: false,
pubkey_id: [0; 20],
challenge: [0; 8],
}
}
}
impl Lookup {
pub fn mid(&self) -> usize { self.mid }
}
#[derive(Debug)]
pub struct Authenticate {
mid: usize,
pub cid: xous::CID,
pub name: [u8; 64],
pub name_len: usize,
pub success: bool,
pub response_to_challenge: [u32; 8],
}
impl Default for Authenticate {
fn default() -> Self {
Authenticate {
mid: ID_AUTHENTICATE,
cid: 0,
name: [0; 64],
name_len: 0,
success: false,
response_to_challenge: [0; 8],
}
}
}
impl Authenticate {
pub fn mid(&self) -> usize { self.mid }
}

View file

@ -2,4 +2,19 @@
pub mod api; pub mod api;
use xous::{send_message, Error, CID}; /*
Calls are made using the xous::ipc::Sendable IPC wrapper, for example:
use xous::ipc::*;
let mut registration = Registration::new();
let mut sendable_registration = Sendable::new(registration)
.expect("can't create sendable registration structure");
let test_name = b"A test Name!";
sendable_registration.name[..test_name.len()].clone_from_slice(test_name);
sendable_registration.name_len = test_name.len();
sendable_registration.lend_mut(ns_conn, sendable_registration.mid());
*/

View file

@ -15,7 +15,9 @@ fn xmain() -> ! {
log_server::init_wait().unwrap(); log_server::init_wait().unwrap();
let name_server = let name_server =
xous::create_server_with_address(b"xousnames-server").expect("Couldn't create xousnames-server"); xous::create_server_with_address(b"xous-name-server").expect("Couldn't create xousnames-server");
xous::create_server();
info!("NS: started"); info!("NS: started");
loop { loop {
@ -30,7 +32,7 @@ fn xmain() -> ! {
let name: String<U64> = String::from_utf8(namevec).unwrap(); let name: String<U64> = String::from_utf8(namevec).unwrap();
info!("NS: registration request for {}", name); info!("NS: registration request for {}", name);
registration.success = true; registration.success = true;
xous::return_memory(envelope.sender, m.buf).unwrap(); // memory is automatically returend upon exit, no need for explicit return of memory
} else { } else {
error!("NS: unknown message ID received"); error!("NS: unknown message ID received");
} }