diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index 91b8614..d5fb661 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -10,7 +10,7 @@ The sepgsql is a module which performs as an external security provider; to support label based mandatory access control - (MAC) base on SELinux policy. + (MAC) based on SELinux policy. This extension won't build at all unless the installation was configured @@ -22,20 +22,20 @@ PostgreSQL provides various kind of hooks. Some of these - hooks can be utilized to make access control decision on the supplied + hooks can be utilized to make an access control decision on the supplied users' accesses on database objects. - We call plug-in modules making access control decision based on its own + We call plug-in modules making access control decisions based on its own security model as an external security provider. This module acquires control on these strategic points, then it asks SELinux to check whether the supplied access shall be allowed, or not. Then, it returns its access control decision. - If violated, this module prevents this access with rising an error for + If violated, this module prevents this access by raising an error for example. - A series of making decision is done independently from the default + A series of decision making is done independently from the default database privilege mechanism. Users must be allowed with both of access control models, whenever they try to access something. @@ -54,17 +54,17 @@ PostgreSQL 9.1 or later supports - statement that allows to assign - a security label on specified database objects, if user wants to change - label from the creation default. - Also SELinux provides an interface to obtain security + statement that allows assignment of + a security label on specified database objects, if the user wants to change + the label from the creation default. + Also SELinux provides an interface to obtain the security label of the peer process that connected to. - These facilities enable to integrate SELinux model within - access controls to database objects. Because it makes access control - decision according to a common centralized security policy (a set of rules), - its decision will be always consistent independent from the way to store + These facilities enable integration of the SELinux model + within access controls to database objects. Because it makes access control + decisions according to a common centralized security policy (a set of rules), + its decision will always be consistent independent from the way to store information assets. @@ -123,12 +123,12 @@ Policy version: 24 Policy from config file: targeted If disabled or not-installed, you need to set up SELinux - prior to all the installation step of SE-PostgreSQL. + prior to all the installation steps of SE-PostgreSQL. - On the compile time, add --with-selinux option to - the configure script to check existence of - the libselinux, and to set a flag whether + At compile time, add the --with-selinux option to + the configure script to check for the existence of + libselinux, and to set a flag to indicate whether we build this contrib module, or not. $ ./configure --enable-debug --enable-cassert --with-selinux @@ -141,11 +141,11 @@ $ make install to in the postgresql.conf. - It enables to load sepgsql on the starting up of + It enables the loading of sepgsql during that start up of the postmaster process. - Then, load the sepgsql.sql script for each databases. + Then, load the sepgsql.sql script for each database. It installs functions corresponding to security label management, and tries to assign initial labels on the target objects. @@ -163,8 +163,8 @@ $ for DBNAME in template0 template1 postgres; do done - If all the installation process was done with no errors, start postmaster - process. SE-PostgreSQL shall prevent violated accesses + If the installation process completed with no errors, start the postmaster + process. SE-PostgreSQL shall prevent access violations according to the security policy of SELinux. @@ -177,16 +177,16 @@ $ for DBNAME in template0 template1 postgres; do See the following steps. - First, install the policy package for regression test. + First, install the policy package for the regression test. The sepgsql-regtest.pp is a special purpose policy package that provides a set of rules to be allowed during the regression test - cases. It shall be installed at /usr/local/pgsql/share/contrib - directory in the default setup. + cases. It shall be installed in the + /usr/local/pgsql/share/contrib directory in the default setup. - You need to install this policy package using semodule - command which enables to link supplied policy packages and load them - into the kernel space. If you could install the pakage correctly, + You need to install this policy package using the semodule + command which links supplied policy packages and loads them + into the kernel space. If you install the package correctly, semodule -l prints sepgsql-regtest as a part of policy packages currently available. @@ -201,7 +201,7 @@ sepgsql-regtest 1.03 Second, turn on the sepgsql_regression_test_mode. We don't enable all the rules in the sepgsql-regtest.pp - in the default, for your system's safety. + by default, for your system's safety. The sepgsql_regression_test_mode parameter is associated with rules to launch regression test. It can be turned on using setsebool command. @@ -216,15 +216,15 @@ sepgsql_regression_test_mode --> on Last, kick the regression test from the unconfined_t domain. - This test policy is designed to kick each test cases from the + This test policy is designed to kick each test case from the unconfined_t domain that is a default choice in most of - the known SELinux installation base. + the known SELinux installation bases. So, you don't need to set up anything special, as long as you didn't - change default configuration of SELinux before. + change the default configuration of SELinux beforehand. The id command tells us the current working domain. - Confirm your shell is now performing with unconfined_t + Confirm your shell is now performing with the unconfined_t domain as follows. @@ -262,12 +262,12 @@ test misc ... ok ===================== - If pg_regress failed to launch psql command, + If pg_regress failed to launch the psql command, here is a hint to fix up the matter. When we try to launch psql command with restrictive - privileges, the psql must eb labeled as bin_t. - If not, try to run restorecon to fix up security label of + privileges, the psql must be labeled as bin_t. + If not, try to run restorecon to fix the security label of the commands as expected. @@ -286,25 +286,25 @@ $ restorecon -R /usr/local/pgsql/ - This parameter enables to perform SE-PostgreSQL + This parameter enables SE-PostgreSQL to function in permissive mode independent from the system setting. The default is off (according to the system setting). This parameter can only be set in the postgresql.conf file or on the server command line. - We have two performing mode except for disabled; The one is enforcing + We have two performing modes except for disabled; One is the enforcing mode that checks the security policy on references and actually prevents violated accesses. The other is permissive mode that only checks - the security policy, but does not prevents anything except for log + the security policy, but does not prevent anything except for log generation. This log shall be utilized for debugging of the security policy itself. - When this parameter is on, SE-PostgreSQL performs - in permissive mode, even if the platform system is working on enforcing + When this parameter is on, SE-PostgreSQL functions + in permissive mode, even if the platform system is working in enforcing mode. - We recommend users to keep the default setting, except for the case + We recommend users keep the default setting, except for the case when we develop security policy by ourself. @@ -316,20 +316,20 @@ $ restorecon -R /usr/local/pgsql/ - This parameter enables to print audit messages independent from + This parameter enables the printing of audit messages independent from the policy setting. The default is off (according to the security policy setting). The security policy of SELinux also has rules to control what accesses shall be logged, or not. - In the default, any access violations are logged, but any allowed + By default, any access violations are logged, but any allowed accesses are not logged. When this parameter is on, all the possible logs shall be printed independently from the policy settings. - We recommend to keep the variable turned off in normal cases to + We recommend keeping the variable turned off in normal cases to avoid noisy messages. @@ -349,24 +349,24 @@ $ restorecon -R /usr/local/pgsql/ We call a set of these rules as security policy. - All the access control decision shall be made according to the security + All the access control decisions shall be made according to the security policy, when we ask SELinux whether the required action shall be allowed or not. - Thus, we have no way to control accesses on any sort of objects without + Thus, we have no way to control access on any sort of objects without security labels. (SELinux assumes unlabeled_t is assigned, if no valid security label is assigned on the target object.) - This version of SE-PostgreSQL supports to assign + This version of SE-PostgreSQL supports assignment of a security label on these database object classes: schema, table, column, sequence, view and procedure. - Other database object classes are not supported to assign security label - on, right now. + Other database object classes do not supported assignment of a security + label right now. A security label shall be automatically assigned to the supported - database objects on their creation time. + database objects at their creation time. This label is called as a default security label; being decided according to the security policy, or a pair of security label of the client and upper object for more correctly.