new file mode 100644
@@ -0,0 +1,138 @@
+This helper script is used in /etc/request-key.d/cifs.spnego.conf to
+ enable complex matching of fields in the description of the key
+ when using krb5 for cifs mounts; when a match is found, cifs.upcall
+ is then executed with the specified options.
+
+This script will read each line of /etc/cifs-upcall-helper.conf, applying
+ match criteria in the first field to the key description; if all
+ criteria match, the options specified in the second field are used to
+ construct the command-line for calling the cifs.upcall program.
+
+If the cifs-upcall-helper.conf file is not present, or if no lines match,
+ the cifs.upcall is executed with the current default options (if any)
+
+
+To use this helper script, install this script at
+ /usr/sbin/cifs-upcall-helper, and replace the following line in
+ /etc/request-key.d/cifs.spnego.conf:
+
+ create cifs.spnego * * /usr/bin/cifs.upcall %k
+
+ with
+
+ create cifs.spnego * * /usr/sbin/cifs-upcall-helper %k
+
+
+each line of the cifs-upcall-helper.conf file has the following format:
+
+ <line> :=
+ <selection_criteria><whitespace><options>
+ default<whitespace><options>
+ log_level<whitespace><log_level>
+
+ <selection_criteria> := <criterion>[<delimiter><criterion>]*
+
+ <options> := <option>[<delimiter><option>]*
+
+ <delimiter> := [,;]
+
+ <criterion> :=
+ *
+ host<string_comparator><host_string>
+ user<string_comparator><user_string>
+ sec<string_comparator><sec_string>
+
+ ip4<ip4_comparator><ip4_string>
+ ip6<string_comparator><ip6_string>
+ (TODO: enhance ip6_comparator)
+
+ uid<numeric_comparator><uid_string>
+ creduid<numeric_comparator><uid_string>
+
+ <string_comparator> :=
+ '=' | '==' | '!=' | '~' | '!~'
+ '=', '==', and '!=' compare as 'globs'
+ ('*' is a wildcard which represents zero or more
+ characters; all other characters are literals)
+ '~' and '!~' compare the string as a 'regex'
+
+ <host_string> := <character_string>
+ <user_string> := <character_string>
+ <sec_string> := krb5 | mskrb5 | iakerb
+
+ <character_string> := [-a-zA-Z0-9_.]
+
+ <ip4_comparator> := '=', '==', '!='
+
+ <ip4_string> :=
+ <ip4_addr> | <ip4_range> | <ip4_net_netmask> | <ip4_net_prefix>
+
+ <ip4_addr> := [0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}
+ <ip4_range> := <ip4_addr>-<ip4_addr>
+ <ip4_net_netmask> := <ip4_addr>/<ip4_addr>
+ <ip4_net_prefix> := <ip4_addr>/<ip4_prefix>
+ <ip4_prefix> := ([0-9]|[12][0-9]|3[0-2])
+
+ (invalid netmask/prefix results in 'not a match', regardless of comparator)
+
+
+ <numeric_comparator> := '<' | '<=' | '=' | '==' | '>=' | '>' | '!='
+
+ <uid_string> := [0-9]+ | 0x[0-9a-fA-F]+
+
+ <option> :=
+ * | -
+ keytab=<path>
+ krb5conf=<path>
+ krb5_trace=<path>
+ use-proxy|use_proxy
+ no-env-probe|no_env_probe
+ trust-dns|trust_dns
+ legacy-uid|legacy_uid
+
+ with the exception of use_proxy and krb5_trace, options are passed to 'cifs.upcall'
+ with the relevant command-line argument; see the OPTIONS section of the manpage
+ for cifs.upcall(8) for further details
+
+ use_proxy sets the GSS_USE_PROXY environment variable prior to calling 'cifs.upcall',
+ enabling the use of gssproxy; see the ENVIRONMENT VARIABLES section of the manpage
+ for cifs.upcall(8) for further details
+
+ specifying 'krb5_trace' with path will set the KRB5_TRACE environment variable to the
+ path, prior to calling 'cifs.upcall'; setting this environment variable causes
+ kerberos-related tracing to be written to the file; see the ENVIRONMENT VARIABLES
+ section of the manpage for kerberos(7) for further details
+
+
+ in the <option> field, the <path> values for <keytab>, <krb5conf>, and <krb5_trace>
+ will also accept the following macros:
+ %h server hostname
+ %i server IP address
+ %s sec type
+ %U uid
+ %c creduid
+ %u username
+
+
+ when 'default' is specified as the selection criteria, all currently-specified
+ default options are cleared, and the <options> specified (if any) are
+ set as defaults
+ the line does not match, and processing continues with the next line
+ use option '*' or '-' as a placeholder; options will be cleared, but no
+ new options set
+ NOTE: default must be the only criteria
+
+
+ <log_level> := (0|1|2|errors|info|debug)
+
+ when 'log_level' is specified as the selection criteria,
+ the logging level is set to the specified level. Options are:
+ 0|errors
+ only errors are logged to syslog, at level LOG_ERR
+ 1|info
+ more verbose information is logged to syslog, at level LOG_INFO
+ 2|debug
+ verbose debugging messages are output to syslog, at level LOG_INFO
+ any other values
+ verbosity is unchanged
+ NOTE: log_level must be the only criteria
Add a directory in contrib for the cifs-upcall-helper script, with README that explains the script's use. Signed-off-by: Frank Sorenson <sorenson@redhat.com> --- contrib/upcall-helper/README | 138 +++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 contrib/upcall-helper/README