From 1d748413e88461bd3a50230422a5cbc3aaeae482 Mon Sep 17 00:00:00 2001 From: "jk7744.park" Date: Wed, 4 Feb 2015 14:10:37 +0900 Subject: [PATCH] add missing files by .gitignore --- docs/buxton-api.7 | 139 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/buxton-protocol.7 | 136 +++++++++++++++++++++++++++++++++++++++++++++++ docs/buxton-security.7 | 132 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 407 insertions(+) create mode 100644 docs/buxton-api.7 create mode 100644 docs/buxton-protocol.7 create mode 100644 docs/buxton-security.7 diff --git a/docs/buxton-api.7 b/docs/buxton-api.7 new file mode 100644 index 0000000..967c31b --- /dev/null +++ b/docs/buxton-api.7 @@ -0,0 +1,139 @@ +'\" 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 diff --git a/docs/buxton-protocol.7 b/docs/buxton-protocol.7 new file mode 100644 index 0000000..4c0b78d --- /dev/null +++ b/docs/buxton-protocol.7 @@ -0,0 +1,136 @@ +'\" 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 diff --git a/docs/buxton-security.7 b/docs/buxton-security.7 new file mode 100644 index 0000000..e59ae2c --- /dev/null +++ b/docs/buxton-security.7 @@ -0,0 +1,132 @@ +'\" 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 -- 2.7.4