mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-19 09:00:54 +00:00
update README on xous-names, and refine the API a bit
This commit is contained in:
parent
1075dff559
commit
61409bb94c
5 changed files with 167 additions and 126 deletions
|
|
@ -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 {
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
|
|
@ -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 }
|
||||||
|
}
|
||||||
|
|
|
||||||
|
|
@ -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());
|
||||||
|
|
||||||
|
*/
|
||||||
|
|
|
||||||
|
|
@ -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");
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue