mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-16 08:38:26 +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 core::fmt::Write;
|
||||
use graphics_server::{Circle, DrawStyle, Line, PixelColor, Point, Rectangle};
|
||||
use xous_names::api::Registration;
|
||||
|
||||
use log::{error, info};
|
||||
use xous::String;
|
||||
use xous::ipc::*;
|
||||
use xous_names::api::Registration;
|
||||
|
||||
use core::convert::TryFrom;
|
||||
|
||||
|
|
@ -138,7 +139,7 @@ fn shell_main() -> ! {
|
|||
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 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 graphics_conn = xous::connect(graphics_server_id).unwrap();
|
||||
|
|
@ -219,12 +220,7 @@ fn shell_main() -> ! {
|
|||
.expect("unable to clear region");
|
||||
|
||||
let mut firsttime = true;
|
||||
let mut registration = Registration {
|
||||
sid: xous::SID::from_u32(0, 0, 0, 0,),
|
||||
name: *b"test name ",
|
||||
name_len: b"test name".len(),
|
||||
success: false
|
||||
};
|
||||
let mut registration = Registration::new();
|
||||
let mut sendable_registration = Sendable::new(registration)
|
||||
.expect("can't create sendable registration structure");
|
||||
loop {
|
||||
|
|
@ -361,8 +357,11 @@ fn shell_main() -> ! {
|
|||
get_batt_stats_nb(com_conn).expect("Can't get battery stats from COM");
|
||||
info!("Test NS lookup");
|
||||
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);
|
||||
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);
|
||||
}
|
||||
} 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.
|
||||
|
||||
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
|
||||
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`.
|
||||
string into the SID except by resolving it with `xous-name-server`.
|
||||
|
||||
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
|
||||
The exception to random SIDs are the `xous-name-server` and
|
||||
`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-name-server` 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
|
||||
names, `xous-log-server ` is necessary for debugging, so that bugs upstream
|
||||
of name resolution can be logged. `xous-name-server` 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.
|
||||
1. It creates a `Registration` IPC structure by wrapping it in `xous::ipc::Sendable`,
|
||||
using the `new()` initializer.
|
||||
|
||||
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.
|
||||
2. It copies a preferred ASCII name string, limited to 64 characters,
|
||||
into the `Registration` record. It then uses the `.lend_mut()` method
|
||||
on the Sendable Registration to lend the structure to `xous-name-server`.
|
||||
The sending process will block until `xous-name-server` 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
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
1. It creates a `Lookup` IPC structure by wrapping it in a `xous::ipc::Sendable`,
|
||||
using the `new()` initializer.
|
||||
|
||||
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.
|
||||
2. It populates the Lookup structure with the name of the server it is looking up.
|
||||
|
||||
3. It uses `.lend_mut()` method to send `xous-name-server` a “Mutable Borrow”
|
||||
`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:
|
||||
|
||||
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
|
||||
`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
|
||||
B. flat denial: `xous-name-server` simply returns a message saying the
|
||||
request was denied by setting `success` to `false`. 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 to the nearest 0.5 second interval since boot
|
||||
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.
|
||||
C. request to authenticate: `xous-name-server` responds with `success` set
|
||||
to `false`, but `authenticate_request` to `true`. The `pubkey_id` field
|
||||
is populated with the ID of an acceptable Ed25519 public key for authentication, and
|
||||
a 256-bit challenge nonce is provided in the `challenge` field. Authentication
|
||||
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};
|
||||
|
||||
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_LOOKUP_NAME: usize = 1;
|
||||
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)]
|
||||
pub enum Opcode {
|
||||
/// Register a 128-bit SID with a preferred, unique lookup name
|
||||
RegisterName(Registration),
|
||||
|
||||
/// Retrieve the 128-bit SID for a server, given its unique lookup name
|
||||
LookupName(Lookup),
|
||||
|
||||
/// Authenticate to the name server, based on nonce embedded in LookupName response
|
||||
/// this is always as a response to a lookupname that reqeusts the authentication challenge-response
|
||||
Authenticate(Lookup),
|
||||
pub struct Registration {
|
||||
mid: usize,
|
||||
pub sid: SID,
|
||||
// we use fixed-length, u8-only records to pass server names. This is different from
|
||||
// your typical Rust String object; but, a key restriction on IPC calls is that the size
|
||||
// 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.
|
||||
pub name: [u8; 64],
|
||||
pub name_len: usize,
|
||||
pub success: bool,
|
||||
}
|
||||
|
||||
impl<'a> core::convert::TryFrom<&'a Message> for Opcode {
|
||||
type Error = &'static str;
|
||||
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"),
|
||||
}
|
||||
}
|
||||
}*/
|
||||
impl Registration {
|
||||
pub fn mid(&self) -> usize { self.mid }
|
||||
|
||||
/* No "Into<>" methods -- we use the ipc::lend() to create messages
|
||||
impl Into<Message> for Opcode {
|
||||
fn into(self) -> Message {
|
||||
match self {
|
||||
Opcode::Reset => Message::Scalar(ScalarMessage {
|
||||
id: 1,
|
||||
arg1: 0,
|
||||
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,
|
||||
}),
|
||||
pub fn new() -> Self {
|
||||
Registration {
|
||||
mid: ID_REGISTER_NAME,
|
||||
sid: xous::SID::from_u32(0,0,0,0),
|
||||
name: [0; 64],
|
||||
name_len: 0,
|
||||
success: false,
|
||||
}
|
||||
}
|
||||
}
|
||||
*/
|
||||
|
||||
#[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;
|
||||
|
||||
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();
|
||||
|
||||
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");
|
||||
loop {
|
||||
|
|
@ -30,7 +32,7 @@ fn xmain() -> ! {
|
|||
let name: String<U64> = String::from_utf8(namevec).unwrap();
|
||||
info!("NS: registration request for {}", name);
|
||||
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 {
|
||||
error!("NS: unknown message ID received");
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue