Skip to content

Latest commit

 

History

History
67 lines (45 loc) · 3.92 KB

UIP-0101.md

File metadata and controls

67 lines (45 loc) · 3.92 KB
uip title description author status type category created
0101
%lick
An IPC vane
~mopfel-winrux (@mopfel-winrux)
Final
Standards
Kernel
2023-06-29

Abstract

This proposal introduces a new vane, %lick, designed to function as an Interprocess Communication (IPC) vane. It enables communication between Urbit applications and applications operating on the Host Operating System (Host OS). Urbit applications, through this vane, can open and close IPC ports on the Host OS, receive notifications about POSIX applications' connectivity status, and transfer jammed nouns.

Motivation

The primary incentive behind this proposal is to empower Urbit applications to interact directly with Host OS processes, bypassing the need for %eyre. This capability facilitates communication with a diverse array of devices, including cryptographic hardware keys, dongles, embedded devices utilizing common communication interfaces (such as UART, SPI, I2C), and IoT-connected devices.

The communication between Urbit apps and the Host OS will employ nouns shaped as [=mark =noun]. An alternative design involving ioctl was explored but discarded due to security and compatibility concerns.

Specification

%lick SHALL have the following tasks:

  • [%born ~]
    • This tells the %lick vane that the runtime has restarted.
    • %lick MUST resend information about all IPC ports to vere and notify the port owners that the port was disconnected
  • [%spin name=path]
    • %lick MUST open an IPC port in the piers .urb/dev/ folder under the path specified by name.
  • [%shut name=path]
    • %lick MUST shut the IPC port in the piers .urb/dev/ folder undet the path specified by name
  • [%spit name=path =mark =noun]
    • %lick MUST make sure the name has been opened and is connected to a process on the Host OS
    • If nothing is connected %lick MUST send a [%soak name=path mark=%error noun='not connected'] gift to the owner of path
    • If something is connected %lick MUST use the newt algorithm to jam [=mark =noun] and pass it along the IPC port.

%lick SHALL produce the following gift:

  • [%soak name=path =mark =noun]
    • %lick SHALL forward anything read from the IPC port to the ports owner. This data must be a jamed cell consisting of [=mark =noun]
    • %lick SHALL also use this gift to communicate information to the IPC ports owner. This information SHALL be when the first process on the Host OS connects, the last process on the Host OS disconnects, and if there are any errors.

NOTE: If this is coming from another vane (e.g %gall) the name may have additional information prepended to it.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Rationale

After an initial iteration (%loch) was found lacking, this method was proposed. The previous method, involving bytearrays written to files and ioctl system calls, was deemed insecure and non-portable.

This version remedies these issues by necessitating that any process aiming to communicate with Urbit must understand nouns at a minimum. Leveraging the newt protocol as a foundational element guarantees portability and security.

The concept of poke extended to an IPC port facilitates user-space applications to send and receive information or commands to POSIX processes easily.

Backwards Compatibility

A Kelvin Decrement will be necessary. No backward compatibility issues found.

Reference Implementation

Security Considerations

This does allow any unix process to connect to your Urbit. Since Urbit must open the IPC port the ship owner must approve any app that does so. Whoever is running the Host OS will be responsible to ensure the Unix process connected is secure.

Copyright

Copyright and related rights waived via CC0.