RepoMirrors/selinux
1
0
Fork 0
mirror of https://github.com/SELinuxProject/selinux synced 2024-12-14 18:14:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
e016502c0a
selinux/libselinux/man/man3/set_matchpathcon_flags.3

63 lines
2.1 KiB
Groff
Raw Normal View History

Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.TH "set_matchpathcon_flags" "3" "21 November 2009" "sds@tycho.nsa.gov" "SELinux API documentation"
.SH "NAME"
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
set_matchpathcon_flags, set_matchpathcon_invalidcon, set_matchpathcon_printf \- set flags controlling the operation of matchpathcon or matchpathcon_index and configure the behaviour of validity checking and error displaying
.
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.SH "SYNOPSIS"
.B #include <selinux/selinux.h>
.sp
.BI "void set_matchpathcon_flags(unsigned int " flags ");"
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.sp
.BI "void set_matchpathcon_invalidcon(int (*" f ")(const char *" path ", unsigned " lineno ", char *" context "));"
.sp
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.BI "void set_matchpathcon_printf(void (*" f ")(const char *" fmt ", ...));"
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.SH "DESCRIPTION"
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR set_matchpathcon_flags ()
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
sets the flags controlling the operation of
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR matchpathcon_init (3)
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
and subsequently
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR matchpathcon_index (3)
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
or
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR matchpathcon (3).
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
If the
.B MATCHPATHCON_BASEONLY
flag is set, then only the base file contexts configuration file
will be processed, not any dynamically generated entries or local customizations.
.sp
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR set_matchpathcon_invalidcon ()
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
sets the function used by
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR matchpathcon_init (3)
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
when checking the validity of a context in the file contexts
configuration. If not set, then this defaults to a test based
on
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR security_check_context (3),
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
which checks validity against the active policy on a SELinux system.
This can be set to instead perform checking based on a binary policy file,
e.g. using
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR sepol_check_context (3),
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
as is done by
.B setfiles \-c.
The function is also responsible for reporting any such error, and
may include the
.I path
and
.I lineno
in such error messages.
.sp
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR set_matchpathcon_printf ()
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
sets the function used by
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.BR matchpathcon_init (3)
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
when displaying errors about the file contexts configuration. If not set,
then this defaults to fprintf(stderr, fmt, ...). This can be set to redirect
error reporting to a different destination.
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.SH "RETURN VALUE"
Returns zero on success or \-1 otherwise.
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.SH "SEE ALSO"
libselinux: man: Fix man pages formatting - Add man page sections '(N)' to external references, and '()' on functions described in the same man page. - Escape minus signs when those are expected to be used on the command line or files. - Mark files and variables in italic; Note headings, function names, constants, program options and man page references in bold. - Do not justify and hyphenate SEE ALSO section, and avoid hyphenation on symbol names by prepending them with \%. - Remove trailing dot from NAME section description. - Split sections with a no-op command '.', to visually distinguish them but to avoid introducing spurious vertical space in the formatted output. - Add explicit .sp commands in the SYNOPSIS section between function prototypes, and fix space placement in function protoypes. - Split header includes with .br (instead of the explicit or implicit .sp) so that they are vertically contiguous. - Add missing {} around SELINUXTYPE and POLICYTYPE variable text in paths. - Remove unneeded formatting commands. - Remove spurious blank lines. Signed-off-by: Guillem Jover <guillem@debian.org> Signed-off-by: Eric Paris <eparis@redhat.com> Acked-by: Dan Walsh <dwalsh@redhat.com>
2012-11-13 20:15:34 +00:00
.ad l
.nh
Author: Guido Trentalancia Email: guido@trentalancia.com Subject: Contributed manual pages for libselinux Date: Sat, 21 Nov 2009 20:51:17 +0100 Hello Eamon ! On Fri, 2009-11-20 at 21:42 -0500, Eamon Walsh wrote: > Hi, thanks for doing this. Some quick review below. You are welcome, I suppose it was a boring task for many... Thanks very much for reviewing the changes. And please accept my apologies for not placing "[PATCH]" in the subject of the original post. I had just subscribed to the list. I left you cc address intact here... > There is too much in matchpathcon(3) now. It's going to need to be > split up into different pages, perhaps the init/fini/teardown stuff in > one page, the lookup calls in another, and the non-matchpathcon prefixed > calls in a third page. > > Also, .so manpage links are needed for all the calls here. Yes, matchpathcon is a mess. Following your guidelines, I have now splitted the huge and messy page in several different man pages. It's easier to consult and easier to maintain. The first part (page) is strictly related to _init, its variant _init_index, _fini, matchpathcon and its variant matchpathcon_index. Nice and concise. References are provided in the "SEE ALSO" section to the rest. The second page describes the auxiliary lookup calls (matchpathcon_checkmatches) and the inode associations functions (matchpathcon_filespec_{add,destroy,eval}). The reference section points to the main matchpathcon page. A third page has been created for the functions that are used to set the flags (set_matchpathcon_flags) or to configure the behaviour of the main matchpathcon functions (set_matchpathcon_invalidcon and set_matchpathcon_printf). A fourth and fifth page is devoted to functions that should never had ended up in matchpathcon (selinux_file_context_cmp and selinux_file_context_verify in one page and selinux_lsetfilecon_default in another one): we do not really need to save electrons needed for new pages... > > > > * print_access_vector > > > > Looks good. No modifications. > > * security_disable > > > > See the selinux.h comments for this. It needs to be documented that > this function can only be called at startup time. Ok. I have stressed that now and also mentioned that after the policy has been loaded at startup, then only "setenforce" can be used to alter (not disable) the mode of the SELinux kernel code (for example by placing it into "permissive" mode). > > * security_set_boolean_list > > > > a RETURN VALUE section is needed in this page, documenting at least this > call if not the others in that page. I have now added a "RETURN VALUE" section. Also, to avoid confusion, I have rephrased the word "returns" in "provides" when not strictly referring the to the return value of the function (take for example security_get_boolean_names(), strictly speaking the function returns an integer representing 0=success or -1=failure, although from a conceptual point of view it also returns a list trough modification of one of its parameters passed by reference). Usually when an application developer looks at the "RETURN VALUE" section it is because he/she has already planned/coded the call to the function (and thus also the handling to parameters passed by reference) and only needs to check for the function exit status so that it can be handled properly at the call point. > > * selinux_check_passwd_access > > > > This is a replacement for the inconsistently named "checkPasswdAccess" > function. So, the existing description of checkPasswdAccess should be > moved to this function, and checkPasswdAccess should be changed to "this > is a deprecated alias for selinux_check_passwd_access". Yes, I have now mentioned that checkPasswdAccess is deprecated. We are referring to file security_compute_av.3 as the description of these two functions lives there... By the way, it has been pointed out that this function should not hard-code a string. I also agree with him, there is a generic constant for such "passwd" object class, it is defined in flask.h could be used instead of the string, thus avoiding hard-coding and also allowing to save a few cycles and be theoretically future-proof (if ever the name would change, say to "password", "auth-token" or anything else). libselinux/src/checkAccess.c.orig 2009-11-21 20:07:21.000000000 libselinux/src/checkAccess.c 2009-11-21 20:08:36.000000000 @@ -13,17 +13,12 @@ int selinux_check_passwd_access(access_v if (is_selinux_enabled() == 0) return 0; if (getprevcon_raw(&user_context) == 0) { - security_class_t passwd_class; struct av_decision avd; int retval; - passwd_class = string_to_security_class("passwd"); - if (passwd_class == 0) - return 0; - retval = security_compute_av_raw(user_context, user_context, - passwd_class, + SECCLASS_PASSWD, requested, &avd); Note that the above code, should really live in the application and not in the selinux library. It used to be like that, then for some reason it has been introduced. Redhat's passwd and cronie are calling the library function and thus at the moment they rely on it. But for example, util-linux-ng has the code in it and does not call this function, as I believe it should be. A very minor issue anyway... > > * selinux_init_load_policy > > > > A paragraph break is needed in the DESCRIPTION section before this function. Done. I have also added a note to the already mentioned fact that after initial policy load, SELinux cannot be anymore disabled using calls to security_disable(3). > > * selinux_lsetfilecon_default > > > > See notes above about the matchpathcon manpage. Yes, separate man page now. > > * selinux_mkload_policy > > > > Looks good. No modifications. > > * set_selinuxmnt > > > > This manpage includes two static functions that are not part of the > libselinux API (at least, not anymore) and should be removed. > > Also, I'm not comfortable with the description given. Instead, use the > comments in selinux.h, which are more accurate and verbose. > Please let me know if things are any better now. I did also provide on the same day a patch for beautifying and improving the command-line option parsing of a few utilities (a ticket had been created by somebody). That patch provides those improvement according to GNU-style parsing of "help" and "version" options (including long-option variants). I think it also fixes a couple of typos here and there. Feel free to include that patch too if you like it, so that the ticket can be closed ! I will attach it again in another separate message: it has been slightly modified in order to apply cleanly to the latest git snapshot. More important, I was also thinking about fingerprinting (and subsequently checking) the libraries with some cryptographic hash function such as the NIST-recommended SHA2. It is beginning to be done for security-related projects like OpenSSL, so I believe it is even more essential for SELinux. Ever thought about anything like that ? Best regards, Guido Signed-off-By: Joshua Brindle <method@manicmethod.com>
2009-11-27 19:44:41 +00:00
.BR selinux "(8), " matchpathcon "(3), " matchpathcon_index "(3), " set_matchpathcon_invalidcon "(3), " set_matchpathcon_printf "(3), " freecon "(3), " setfilecon "(3), " setfscreatecon "(3)"
Reference in New Issue Copy Permalink