Crate onc_rpc

ONC RPC

This crate implements the Open Network Computing Remote Procedure Call system (originally known as the Sun RPC system) as described in RFC 1831 and RFC 5531.

• Zero copy deserialisation
• Support for serialisation buffer reuse and pooling
• Only safe Rust code
• No heap allocations
• Simple, descriptive, one-to-one types matching the RFCs

Example

use onc_rpc::{
    auth::{AuthFlavor, AuthUnixParams},
    CallBody,
    MessageType,
    RpcMessage,
};

// Add RPC call authentication.
let auth_params = AuthUnixParams::new(
	42,										// Stamp
	"bananas.local",						// Machine name
	501,									// UID
	501,									// GID
	None,									// No additional GIDs
);

// Build a dummy byte payload.
let payload = vec![42, 42, 42, 42];

// Construct the actual RPC message.
let msg = RpcMessage::new(
    4242,
    MessageType::Call(CallBody::new(
        100000, 							// Program number
        42,									// Program version
        13,									// Procedure number
        AuthFlavor::AuthUnix(auth_params),	// Credentials
        AuthFlavor::AuthNone(None),			// Response verifier
        &payload,
    )),
);

// Serialise the RPC message, or serialise_into() to reuse buffers.
let network_buffer = msg.serialise().expect("serialise message");

// And do something with it!

Limitations

I had no use for the following, however PRs to extend this crate are happily accepted :)

• No support for fragmented messages
• No support for the deprecated and trivially broken Diffie-Hellman authentication flavor
• No defined GSS / Kerberos auth flavor types

The auth flavors not included in this crate can still be used as the flavor discriminant and associated opaque data is available in the application layer - this crate just lacks pre-defined types to describe them.

Future development

Currently a buffer has to be passed to serialise the complete message into a continuous memory region - it would be nicer to support vectorised I/O to provide zero-copy serialisation too.

Fuzzing

Included in the fuzz/ directory is a deserialisation fuzzer that attempts to decode arbitrary inputs, and if successful serialises the resulting message and compares the result with the input.

Install cargo fuzz and invoke the fuzzer with cargo fuzz run parse_serialise -- -jobs=30 for parallelised workers.

Modules

auth

A set of basic auth flavors specified in RFC 5531.

buf

Utilities for working with buffers.

Structs

AcceptedReply

A type sent in response to a request that contains credentials accepted by the server.

Bytes

A cheaply cloneable and sliceable chunk of contiguous memory.

BytesMut

A unique reference to a contiguous slice of memory.

CallBody

A request invoking an RPC.

RpcMessage

An Open Network Computing RPC message, generic over a source of bytes (T) and a payload buffer (P).

TryGetError

Error type for the try_get_ methods of Buf. Indicates that there were not enough remaining bytes in the buffer while attempting to get a value from a Buf with one of the try_get_ methods.

Enums

AcceptedStatus

The response status code for a request that contains valid credentials.

AuthError

AuthError describes the reason the request authentication credentials were rejected.

Error

Error types returned by this crate.

MessageType

The type of RPC message.

RejectedReply

The response type for a rejected RPC invocation.

ReplyBody

ReplyBody defines the response to an RPC invocation.

Traits

Buf

Read bytes from a buffer.

BufMut

A trait for values that provide sequential write access to bytes.

Functions

expected_message_len

Reads the message header from data, and returns the expected wire length of the RPC message.