--- /dev/null
+'\" t
+.TH "BUXTON\-API" "7" "" "buxton 1" "buxton\-api"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+buxton\-api \- List of all Buxton API functions
+
+.SH "DESCRIPTION"
+.PP
+This document contains the complete list of buxton API functions,
+each having its own manual page\&.
+
+In addition, there are several "hello world" demo programs in the
+buxton source tree, in the demos/ directory, that demonstrate how to
+use these API functions\&.
+
+.SH "API functions"
+.SS "Client connections"
+.PP
+\fBbuxton_open\fR(3)
+\(em Open a buxton client connection
+.br
+\fBbuxton_close\fR(3)
+\(em Close a buxton client connection
+.br
+
+.SS "BuxtonKey utility functions"
+.PP
+\fBbuxton_key_create\fR(3)
+\(em Create a client\-side key (BuxtonKey)
+.br
+\fBbuxton_key_free\fR(3)
+\(em Free a BuxtonKey
+.br
+\fBbuxton_key_get_type\fR(3)
+\(em Get the type member of a BuxtonKey
+.br
+\fBbuxton_key_get_layer\fR(3)
+\(em Get the layer member of a BuxtonKey
+.br
+\fBbuxton_key_get_group\fR(3)
+\(em Get a group member of a BuxtonKey
+.br
+\fBbuxton_key_get_name\fR(3)
+\(em Get a name member of a BuxtonKey
+.br
+
+.SS "Group storage and manipulation"
+.PP
+\fBbuxton_create_group\fR(3)
+\(em Create a group within a layer
+.br
+\fBbuxton_remove_group\fR(3)
+\(em Remove a group within a layer
+.br
+\fBbuxton_set_label\fR(3)
+\(em Set the Smack label for a group
+.br
+
+.SS "Key storage and manipulation"
+.PP
+\fBbuxton_set_value\fR(3)
+\(em Set the value for a key
+.br
+\fBbuxton_get_value\fR(3)
+\(em Get the value of a key
+.br
+\fBbuxton_unset_value\fR(3)
+\(em Unset the value for a key
+.br
+\fBbuxton_set_label\fR(3)
+\(em Set the Smack label for a key
+.br
+
+.SS "Notifications"
+.PP
+\fBbuxton_register_notification\fR(3)
+\(em Register for a key notification
+.br
+\fBbuxton_unregister_notification\fR(3)
+\(em Unregister for a key notification
+.br
+\fBbuxton_handle_response\fR(3)
+\(em Notification response helper
+.br
+
+.SS "Callbacks"
+.PP
+\fBbuxton_response_status\fR(3)
+\(em Get the status for a BuxtonResponse in a callback
+.br
+\fBbuxton_response_key\fR(3)
+\(em Fetch the BuxtonKey within a callback
+.br
+\fBbuxton_response_type\fR(3)
+\(em Fetch the response type within a callback
+.br
+\fBbuxton_response_value\fR(3)
+\(em Fetch the response value within a callback
+.br
+
+.SS "Configuration"
+.PP
+\fBbuxton_set_conf_file\fR(3)
+\(em Set the path to the Buxton configuration file
+.br
+
+.SH "COPYRIGHT"
+.PP
+Copyright 2014 Intel Corporation\&. License: Creative Commons
+Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2\&.
+
+.SH "SEE ALSO"
+.PP
+\fBbuxton\fR(7)
+
+.SH "NOTES"
+.IP " 1." 4
+Creative Commons Attribution\-ShareAlike 3.0 Unported
+.RS 4
+\%http://creativecommons.org/licenses/by-sa/3.0/
+.RE
--- /dev/null
+'\" t
+.TH "BUXTON\-PROTOCOL" "7" "" "buxton 1" "buxton\-protocol"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+buxton\-protocol \- The wire protocol for buxton
+
+.SH "DESCRIPTION"
+.PP
+A buxton client communicates with the buxton daemon
+(\fBbuxtond\fR(8)) through a Unix Domain Socket by sending
+messages over this socket that adhere to a specific format\&. Also,
+\fBbuxtond\fR(8) may send a response back to the client in a same
+format\&. The required rules, formats, and values permitted in this
+two-way communication channel is hereafter called the "wire
+protocol"\&.
+
+.SH "PROTOCOL SPECIFICATION"
+.PP
+The following sections detail the specifics of the wire protocol\&.
+
+.SH "MESSAGE FORMAT"
+.PP
+The messages sent to \fBbuxtond\fR(8) from a client, or vice
+versa, adhere to the following format:
+
+.SS "Header"
+.PP
+Magic (2 bytes)
+.RS 4
+The magic byte string has hex value 0x672\&.
+.RE
+.PP
+Control code (2 bytes)
+.RS 4
+All control codes belong to an enum with 13 elements\&. Each code is
+cast to a uint16_t value when serialized\&.
+
+For client messages, the accepted control codes are:
+BUXTON_CONTROL_SET, BUXTON_CONTROL_SET_LABEL,
+BUXTON_CONTROL_CREATE_GROUP, BUXTON_CONTROL_REMOVE_GROUP,
+BUXTON_CONTROL_GET, BUXTON_CONTROL_UNSET, BUXTON_CONTROL_NOTIFY, and
+BUXTON_CONTROL_UNNOTIFY\&.
+
+For daemon responses, accepted control codes are:
+BUXTON_CONTROL_STATUS and BUXTON_CONTROL_CHANGED\&.
+
+.RE
+.PP
+Message size (4 bytes)
+.RS 4
+The size on the entire message, with type uint32_t\&.
+.RE
+.PP
+Message ID (8 bytes)
+.RS 4
+The unique ID for this message, with type uint32_t\&.
+.RE
+.PP
+Parameter count (4 bytes)
+.RS 4
+The number of parameters in the message body, with contents as
+described in the next section\&. This number has type uint32_t\&.
+.RE
+
+.SS "Message body"
+.PP
+The message body contains one or more parameters, each with the
+following structure:
+.PP
+Data type (2 bytes)
+.RS 4
+All recognized data types belong to an enum with 8 elements\&. Each
+type is cast to a uint16_t value when serialized\&.
+
+Accepted types include STRING, INT32, UINT32, INT64, UINT64, FLOAT,
+DOUBLE, and BOOLEAN\&.
+\&.
+.RE
+.PP
+Data length (4 bytes)
+.RS 4
+The length the data value, as defined in the next entry\&.
+.RE
+.PP
+Data value (varies depending on data type)
+.RS 4
+For data with STRING type, the value may range from 0 (zero) bytes to
+an arbitrary maximum, as permitted by the maximum message length and
+factoring in the overall payload of the message\&. For all other data
+types, the value size depends on the data type, with maximum size of
+8 bytes\&.
+.RE
+
+.SH "NOTES"
+.PP
+The maximum message length is 32KB (32768 bytes)\&.
+.PP
+The message byte order is dependent on the endianness of the host
+machine\&.
+
+.SH "COPYRIGHT"
+.PP
+Copyright 2014 Intel Corporation\&. License: Creative Commons
+Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2\&.
+
+.SH "SEE ALSO"
+.PP
+\fBbuxton\fR(7),
+\fBbuxtonctl\fR(1),
+\fBbuxtond\fR(8),
+\fBbuxton\-api\fR(7)
+
+.SH "FOOTNOTES"
+.IP " 1." 4
+Creative Commons Attribution\-ShareAlike 3.0 Unported
+.RS 4
+\%http://creativecommons.org/licenses/by-sa/3.0/
+.RE
--- /dev/null
+'\" t
+.TH "BUXTON\-SECURITY" "7" "" "buxton 1" "buxton\-security"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+buxton\-security \- Outline of buxton security model
+
+.SH "DESCRIPTION"
+.PP
+Buxton uses a Mandatory Access Control (MAC) system to secure
+configuration storage elements, namely, groups and keys within these
+groups\&. MAC is enforced by using the
+\m[blue]\fBSmack\fR\m[]\&\s-2\u[1]\d\s+2
+Linux Security Module\&.
+
+Each group and key that exists in buxton's configuration storage has
+a Smack label associated with it\&. The label set by buxton is taken
+from the Smack label of the running process (client) that created the
+original group or key\&. If the label for a group or key should be
+changed after initial group or key creation, a client with
+appropriate privilege (UID 0) may modify it using
+\fBbuxton_set_label\fR(3) or the "set\-label" command of
+\fBbuxtonctl\fR(1)\&.
+
+MAC is enforced for nearly all types of access requested by
+clients\&. When enforcement is in effect, buxton consults the list of
+Smack rules, managed by the Smack LSM, to make an access decision\&.
+The table below lists the checks in effect for every buxton
+command\&.
+
+.B Table\ \&1.\ \&Access check grid
+.TS
+allbox tab(:);
+lB lB.
+T{
+Command
+T}:T{
+Access checks
+T}
+.T&
+l l
+l l
+l l
+l l
+l l
+l l.
+T{
+set\-value (int32, bool, etc\&.)
+T}:T{
+Check read/write access on the group, and if the key exists, check
+read/write access on the key\&.
+T}
+T{
+get\-value (int32, bool, etc\&.)
+T}:T{
+Check read access on the group, and check read access on the key\&.
+T}
+T{
+unset\-value
+T}:T{
+Check read/write access on the group and on the key\&.
+T}
+T{
+create\-group
+T}:T{
+For system layers, check for UID 0\&. For user layers, no permission
+checks are needed\&.
+T}
+T{
+remove\-group
+T}:T{
+For system layers, check for UID 0\&. For user layers, check write
+access on the group\&.
+T}
+T{
+set\-label
+T}:T{
+For system layers, check for UID 0\&. Action is not allowed for user
+layers\&.
+T}
+.TE
+
+.sp 1
+
+.PP
+Since buxton uses layers to store sets of groups and keys, and
+identical group/key sets may exist across all layers, fine\-grained
+access control is achievable by setting appropriate Smack labels on
+groups and keys for the targeted layer\&. For a more detailed
+discussion of the interaction of group/key labels and the layer
+model, see \fBbuxton\-layers\fR(7)\&.
+
+.SH "COPYRIGHT"
+.PP
+Copyright 2014 Intel Corporation\&. License: Creative Commons
+Attribution\-ShareAlike 3.0 Unported\s-2\u[2]\d\s+2\&.
+
+.SH "SEE ALSO"
+.PP
+\fBbuxton\fR(7),
+\fBbuxtonctl\fR(1),
+\fBbuxtond\fR(8),
+\fBbuxton\-api\fR(7)
+
+.SH "NOTES"
+.IP " 1." 4
+Smack
+.RS 4
+\%https://www.kernel.org/doc/Documentation/security/Smack.txt
+.RE
+.IP " 2." 4
+Creative Commons Attribution\-ShareAlike 3.0 Unported
+.RS 4
+\%http://creativecommons.org/licenses/by-sa/3.0/
+.RE
projects / external / buxton.git / commitdiff