Struct fidl_fuchsia_io::RightsRequest

pub struct RightsRequest {
    pub at_most: Operations,
    pub at_least: Operations,
    pub resolution: RightsResolution,
}

Options for requesting rights on the new connection.

Rights Hierarchy

Respecting principles of least privileges, rights in general must meet the following restrictions:

• A connection must have nonzero rights.
• From the perspective of a client, rights must never increase in a derived connection.
• From the perspective of a directory proxy, it must ensure that new connections opened through it cannot have more rights than the connection where the proxy received the Open/Reopen call.

The proper enforcement of the rights hierarchy is a powerful refinement over the existing access control facilities offered by directory sandboxing.

Rights vs Abilities

The rights on a connection limits the set of operations allowed on that connection, but does not guarantee their availability, because the object may not support it.

See [Rights] and [Abilities].

Implementation Notes

When a directory proxy encounters an absent rights field, let r be the rights on the connection where it received this request, the proxy should fill in this field with the following:

RightsRequest {
    at_most: r,
    at_least: 0,
    resolution: RightsResolution.MAXIMIZE,
}

before forwarding the request to the remote party.

Because opening a new connection may involve multiple hops through directory proxies, we require the client to set an upper bound and lower bound on the rights request, and intermediate proxies to refine these bounds.

The rights manipulation should be implemented mechanically without knowledge of any specific rights, and servers should propagate unknown bits members, to gracefully handle future rights extensions.

Implementation Notes

It could be common for a client to request an exact set of rights. We recommend client libraries to define a helper function like follows:

fn Exact(exact_rights: Rights) -> RightsRequest {
    RightsRequest {
        at_most: exact_rights,
        at_least: exact_rights,
        resolution: RightsResolution.MAXIMIZE,
    }
}

Fields

at_most: Operations

Sets an upper bound on the resulting rights. The exact rights will depend on resolution.

Implementation Notes

When a directory proxy encounters this variant, it should compute the intersection between this and the rights on the connection where it received the request, to shrink the rights.

• If the intersection is empty, or not a superset of at_least, the proxy should close object_request with the ZX_ERR_ACCESS_DENIED epitaph.
• Otherwise, the proxy should forward the Open call as usual, but update at_most with the shrunk rights.

at_least: Operations

Sets a lower bound on the resulting rights. The exact rights will depend on resolution.

• During [Directory.Open], you may only specify the same rights as what the directory connection already has, or a subset of those.
• During [Node.Reopen], similarly, you may only specify the same or a subset of rights possessed by the original connection.
• Exceeding those rights causes object_request to be closed with a ZX_ERR_ACCESS_DENIED epitaph.

Therefore there are these invariants which should be maintained:

at_most ⊋ {}
at_most ⊃ at_least
rights_on_connection_where_open_is_received ⊋ {}
rights_on_connection_where_open_is_received ⊃ at_least

using the superset (⊃), proper superset (⊋), and empty set ({}) notations.

resolution: RightsResolution

When an Open/Reopen request reaches its final remote server, it should assign rights on the new connection based on one of these modes.

Trait Implementations

impl Clone for RightsRequest

fn clone(&self) -> RightsRequest

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RightsRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Decode<RightsRequest> for RightsRequest

fn new_empty() -> Self

Creates a valid instance of Self. The specific value does not matter, since it will be overwritten by decode.

unsafe fn decode( &mut self, decoder: &mut Decoder<'_>, offset: usize, depth: Depth ) -> Result<()>

Decodes an object of type T from the decoder’s buffers into self.

impl Encode<RightsRequest> for &RightsRequest

unsafe fn encode( self, encoder: &mut Encoder<'_>, offset: usize, depth: Depth ) -> Result<()>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID.

impl<T0: Encode<Operations>, T1: Encode<Operations>, T2: Encode<RightsResolution>> Encode<RightsRequest> for (T0, T1, T2)

unsafe fn encode( self, encoder: &mut Encoder<'_>, offset: usize, depth: Depth ) -> Result<()>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID.

impl Hash for RightsRequest

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for RightsRequest

fn cmp(&self, other: &RightsRequest) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<RightsRequest> for RightsRequest

fn eq(&self, other: &RightsRequest) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<RightsRequest> for RightsRequest

fn partial_cmp(&self, other: &RightsRequest) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TypeMarker for RightsRequest

type Owned = RightsRequest

The owned Rust type which this FIDL type decodes into.

fn inline_align(context: Context) -> usize

Returns the minimum required alignment of the inline portion of the encoded object. It must be a (nonzero) power of two.

fn inline_size(context: Context) -> usize

Returns the size of the inline portion of the encoded object, including padding for alignment. Must be a multiple of inline_align.

fn encode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and encoding requires no validation. When true, we can optimize encoding arrays and vectors of Self::Owned to a single memcpy.

fn decode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and decoding requires no validation. When true, we can optimize decoding arrays and vectors of Self::Owned to a single memcpy.

impl ValueTypeMarker for RightsRequest

type Borrowed<'a> = &'a <RightsRequest as TypeMarker>::Owned

The Rust type to use for encoding. This is a particular Encode<Self> type cheaply obtainable from &Self::Owned. There are three cases:

fn borrow<'a>(value: &'a <Self as TypeMarker>::Owned) -> Self::Borrowed<'a>

Cheaply converts from &Self::Owned to Self::Borrowed.

impl Copy for RightsRequest

impl Eq for RightsRequest

impl StructuralEq for RightsRequest

impl StructuralPartialEq for RightsRequest

impl TopLevel for RightsRequest