mirror of
https://github.com/xen-project/xen.git
synced 2026-10-29 02:30:03 +01:00
Juergen Gross
aeaed47023
In case Xenstore is detecting a malicious ring page modification (e.g. an invalid producer or consumer index set by a guest) it will ignore the connection of that guest in future. Add a new error field to the ring page indicating that case. Add a new feature bit in order to signal the presence of that error field. Move the ignore_connection() function to xenstored_domain.c in order to be able to access the ring page for setting the error indicator. Signed-off-by: Juergen Gross <jgross@suse.com> Reviewed-by: Anthony PERARD <anthony.perard@citrix.com>
152 lines
6.5 KiB
Plaintext
152 lines
6.5 KiB
Plaintext
The xenstore ring is a datastructure stored within a single 4KiB page
|
|
shared between the xenstore server and the guest. The ring contains
|
|
two queues of bytes -- one in each direction -- and some signalling
|
|
information. The [xenstore protocol](xenstore.txt) is layered on top of
|
|
the byte streams.
|
|
|
|
The xenstore ring datastructure
|
|
===============================
|
|
|
|
The following table describes the ring structure where
|
|
- offsets and lengths are in bytes;
|
|
- "Input" is used to describe the data sent to the server; and
|
|
- "Output" is used to describe the data sent to the domain.
|
|
|
|
Offset Length Description
|
|
-----------------------------------------------------------------
|
|
0 1024 Input data
|
|
1024 1024 Output data
|
|
2048 4 Input consumer offset
|
|
2052 4 Input producer offset
|
|
2056 4 Output consumer offset
|
|
2060 4 Output producer offset
|
|
2064 4 Server feature bitmap
|
|
2068 4 Connection state
|
|
2072 4 Connection error indicator
|
|
|
|
The Input data and Output data are circular buffers. Each buffer is
|
|
associated with a pair of free-running offsets labelled "consumer" and
|
|
"producer".
|
|
|
|
A "producer" offset is the offset in the byte stream of the next byte
|
|
to be written modulo 2^32. A "consumer" offset is the offset in the byte
|
|
stream of the next byte to be read modulo 2^32. Implementations must
|
|
take care to handle wraparound properly when performing arithmetic with
|
|
these values.
|
|
|
|
The byte at offset 'x' in the byte stream will be stored at offset
|
|
'x modulo 1024' in the circular buffer.
|
|
|
|
Implementations may only overwrite previously-written data if it has
|
|
been marked as 'consumed' by the relevant consumer pointer.
|
|
|
|
When the guest domain is created, there is no outstanding Input or Output
|
|
data. However
|
|
|
|
- guests must not assume that producer or consumer pointers start
|
|
at zero; and
|
|
- guests must not assume that unused bytes in either the Input or
|
|
Output data buffers has any particular value.
|
|
|
|
A xenstore ring is always associated with an event channel. Whenever the
|
|
ring structure is updated the event channel must be signalled. The
|
|
guest and server are free to inspect the contents of the ring at any
|
|
time, not only in response to an event channel event. This implies that
|
|
updates must be ordered carefully to ensure consistency.
|
|
|
|
The xenstore server may decide to advertise some features via the
|
|
"Server feature bitmap". The server can start advertising features
|
|
at any time by setting bits but it will never stop advertising features
|
|
i.e. bits will never be cleared. The guest is not permitted to write to
|
|
the server feature bitmap. The server features are offered to the guest;
|
|
it is up to the guest whether to use them or not. The guest should ignore
|
|
any unknown feature bits.
|
|
|
|
The following features are defined:
|
|
|
|
Mask Description
|
|
-----------------------------------------------------------------
|
|
1 Ring reconnection (see the ring reconnection feature below)
|
|
2 Connection error indicator (see connection error feature below)
|
|
|
|
The "Connection state" field is used to request a ring close and reconnect.
|
|
The "Connection state" field only contains valid data if the server has
|
|
advertised the ring reconnection feature. If the feature has been advertised
|
|
then the "Connection state" may take the following values:
|
|
|
|
Value Description
|
|
-----------------------------------------------------------------
|
|
0 Ring is connected
|
|
1 Ring close and reconnect is in progress (see the "ring
|
|
reconnection feature" described below)
|
|
|
|
The "Connection error indicator" is used to let the server indicate it has
|
|
detected some error that led to deactivation of the connection by the server.
|
|
If the feature has been advertised then the "Connection error indicator" may
|
|
take the following values (new values might be added in future without them
|
|
being advertised as a new feature):
|
|
|
|
Value Description
|
|
-----------------------------------------------------------------
|
|
0 No error, connection is valid
|
|
1 Communication problems (event channel not functional)
|
|
2 Inconsistent producer or consumer offset
|
|
3 Protocol violation (client data package too long)
|
|
|
|
The ring reconnection feature
|
|
=============================
|
|
|
|
The ring reconnection feature allows the guest to ask the server to
|
|
reset the ring to a valid initial state i.e. one in which the Input
|
|
and Output queues contain no data and there are no outstanding requests,
|
|
watches or transactions.
|
|
|
|
The ring reconnection feature is only available if the 'Ring reconnection'
|
|
feature bit has been set by the server in the "Server feature bitmap".
|
|
If a server supports ring reconnection, it will guarantee to advertise
|
|
the feature before producing or consuming any data from the Input or Output
|
|
queues.
|
|
|
|
Assuming the server has advertised the feature, the guest can initiate
|
|
a reconnection by setting the the Connection state to 1 ("Ring close
|
|
and reconnect is in progress") and signalling the event channel.
|
|
The guest must now ignore all fields except the Connection state and
|
|
wait for it to be set to 0 ("Ring is connected")
|
|
|
|
The server will guarantee to
|
|
|
|
- drop any partially read or written higher-level
|
|
[xenstore protocol](xenstore.txt) packets it may have;
|
|
- empty the Input and Output queues in the xenstore ring;
|
|
- discard any in-flight requests
|
|
- discard any watches associated with the connection
|
|
- discard any transactions associated with the connection
|
|
- set the Connection state to 0 ("Ring is connected"); and
|
|
- signal the event channel.
|
|
|
|
From the point of view of the guest, the connection has been reset on a
|
|
packet boundary.
|
|
|
|
Note that only the guest may set the Connection state to 1 and only the
|
|
server may set it back to 0.
|
|
|
|
The connection error feature
|
|
============================
|
|
|
|
The connection error feature allows the server to signal error conditions
|
|
leading to a stop of the communication with the client. In case such an error
|
|
condition has occurred, the server will set the appropriate error condition in
|
|
the Connection error indicator and will stop communication with the client.
|
|
|
|
Any value different from 0 is indicating an error. The value used is meant
|
|
just for diagnostic purposes. A client reading the error value should be
|
|
prepared to see values not described here, as new error cases might be added
|
|
in future.
|
|
|
|
The server will discard any already read or written packets, in-flight
|
|
requests, watches and transactions associated with the connection.
|
|
|
|
Depending on the error cause it might be possible that a reconnect via the
|
|
ring reconnection feature (if present) can be performed. There is no guarantee
|
|
this will succeed.
|