=encoding utf-8 =head1 NAME sympa_scenario - Authorization scenario =head1 SYNOPSIS An example F file: title deletion performed only by list owners, need authentication title.es eliminacin reservada slo para el propietario, necesita autentificacin is_owner([listname],[sender]) smtp -> request_auth is_listmaster([sender]) smtp -> request_auth true() md5,smime -> do_it =head1 DESCRIPTION =head2 File format Basically, a scenario file is composed of titles on the first lines and a set of rules on the following lines. Rules consist of one or more line in the form: condition authentication_methods -> action Some terms of conditions may take one or more arguments. The arguments are variables or literals (see L, L). Authentication methods is a comma-separated list of one or more methods (see L). Some actions may have optional modifiers (see L). =head3 Terms of conditions =over =item C C<(> C<)> Always returns true. =item C C<(> IC<,> I C<)> Tests if two arguments are equal. =item C C<(> IC<,> I C<)> =item C C<(> IC<,> I C<)> =item C C<(> IC<,> I C<)> Tests if I is the subscriber, owner or editor of the list I. I is the variable C<[listname]> or list address, "I" or "IC<@>I". =item C C<(> I C<)> Tests if I is the listmaster. =item C C<(> IC<,> I C<)> Tests if I is less than I. =item C C<(> IC<,> CIC C<)> Tests if I matches with I. I is a perl regular expression. Don't forget to escape special characters (C<^>, C<$>, C<{>, C<(>, ...): Check L for regular expression syntax. It can contain the string C<[domain]> (interpreted at run time as the list or robot domain). Note: Sympa prior to 6.2.32 recognized C<[host]> instead of C<[domain]>. =item C C<(> IC<,> I C<)> Returns true if first date is posterior to the second =item C C<(> IC<,> I C<)> Returns true if first date is anterior to the second date I is Unix time or the string "ICICICICICIC", where each I is a number. =item C C<(> IC<,> IC<)> Tests if I is found by named filter. I is a file name ending with C<.ldap>, C<.sql> or C<.txt>. =item C C<(> I C<)> Tests if C CGI environment variable matches with I. This allows the user to configure their local network to only be accessible to those that are members of it. =item CI C<(> I, ... C<)> Evaluates custom condition. I is the name of a Perl package in F<$SYSCONFDIR/custom_conditions/> (lowercase). =back =head3 Variables =over =item C<[custom_vars-E>IC<]> Allows you to introduce custom parameters in your scenario. I is the name of the custom parameter you want to use. =item C<[date]> Date of reception of the message. =item C<[domain]> Mail domain of current list. Note: This variable was introduced by Sympa 6.2.32. Previous versions used a variable C<[conf-Ehost]> (obsoleted) instead. =item C<[env-E>IC<]> I is the name of CGI environment variable (note that it is case-sensitive). =item C<[is_bcc]> Set to 1 if the list is neither in To: nor Cc: field. =item C<[listname]> Name of current list. =item C<[msg_encrypted]> Set to "C" if the message was S/MIME encrypted. =item C<[msg_header-E>IC<]> =item C<[msg_header-E>IC<][>IC<]> Value of message header field, available only when evaluating the authorization scenario for sending messages. It can be used, for example, to require editor validation for multipart messages. Optional I may be integer (may be less than C<0>) to choose particular entry from multiple fields. =item C<[msg_part-Etype]> =item C<[msg_part-Ebody]> The MIME content types and bodies; the body is available for MIME parts in text/xxx format only. =item C<[previous_email]> Old email when changing subscription email in preference page. =item C<[sender]> The email address of the current user (used on web or mail interface). Default value is "nobody". =item C<[topic]> Topic of the message. This variable has a value if any of the previous C<[topic-*]> variable has a value. =item C<[topic-auto]> Topic of the message if it has been automatically tagged. =item C<[topic-editor]> Topic of the message if it has been tagged by editor. =item C<[topic-needed]> The message has not got any topic and message topic are required for the list. =item C<[topic-sender]> Topic of the message if it has been tagged by sender. =item C<[user_attributes-E>IC<]> I is one of the names of user attributes provided by the SSO system via environment variables. Available only if user authenticated with a C. =back =head3 Authentication methods The e-mail of authenticated user is given by C<[sender]> variable. If it is not given, 'C' will be set. =over =item C Default method. No actual authentication, and if any, sender of the message is used. =item C Authenticated by DKIM signature. =item C Authenticated by web authentication (password), or by authentication key in e-mail message. =item C Authenticated by S/MIME signature, or TLS client certificate. =back =head3 Actions An action consists of an action name and optional modifiers. Action names: =over =item C Allows operation. =item C The message will be forwarded to list editor. =item C The message will be held for moderation by list editor. =item C Same as C but makes newly created list be pending. =item C The operation is held and waits for approval by list owner. =item C Denies operation. =item C The operation is held and waits for confirmation by the user. =back Modifiers: =over =item C<([email])> Only for C action. Sends authentication request to the target user of operation (given as the value of "C<[email]>" variable) instead of original sender. Note that C<[email]> is a literal and no other variable names can't be used. =item C<,> C Only for C and C actions. Sends a notification to list owner. =item C<,> C Sends no notification to the message sender. =item C<(reason='>IC<')> Only for C action. Matches a key in F template corresponding to an information message about the reason of the reject of the user. I have to be a static string enclosed by C<'...'>. =item C<(tt2='>IC<')> Only for C action. Corresponding template (IC<.tt2>) is sent to the sender. I have to be a static string enclosed by C<'...'>. =back =head2 Formal syntax # Below is the formal syntax definition by modified BNF. rule : condition spaces auth_list "->" action # Condition condition : "!" condition | "true" "(" ")" | "equal" "(" var "," var ")" | "is_editor" "(" listname "," var ")" | "is_listmaster" "(" var ")" | "is_owner" "(" listname "," var ")" | "is_subscriber" "(" listname "," var ")" | "less_than" "(" var "," var ")" | "match" "(" var "," "/" perl_regexp "/" ")" | "newer" "(" date "," date ")" | "older" "(" date "," date ")" | "search" "(" named_filter_file ")" | "verify_netmask" "(" network_block ")" | "CustomCondition::" package_name "(" var* ")" var : "[email]" | "[conf->" conf_key_word "]" | "[current_date]" | "[custom_vars->" custom_var_name "]" | "[env->" env_var "]" | "[is_bcc]" | "[list->" list_key_word "]" | "[msg_body]" | "[msg_encrypted]" | "[msg_header->" field_name "]" "[" index "]" | "[msg_header->" field_name "]" | "[msg_part->type]" | "[msg_part->body]" | "[previous_email]" | "[sender]" | "[subscriber->" subscriber_key_word "]" | "[topic]" | "[topic-auto]" | "[topic-editor]" | "[topic-needed]" | "[topic-sender]" | "[user->" user_key_word "]" | "[user_attributes->" user_attributes_keyword "]" | string listname : "[listname]" | listname_string | listname_string "@" domain_string date : "[date]" | date_expr | integer user_key_word : "email" | "gecos" | "lang" | "password" | "cookie_delay_user" | additional_user_fields subscriber_key_word : "email" | "date" | "bounce" | "gecos" | "reception" | "update_date" | "visibility" | additional_subscriber_fields list_key_word : "name" | "address" | "domain" | "lang" | "max_size" | "priority" | "reply_to" | "status" | "subject" | "total" | "account" conf_key_word : "domain" | "default_list_priority" | "email" | "lang" | "listmaster" | "max_size" | "request_priority" | "sympa_priority" # Authentication methods auth_list : auth "," auth_list | auth | "" auth : "smtp" | "dkim" | "md5" | "smime" # Actions action : "do_it" ( "," "quiet" | "," "notify" )* | "editor" [ "," "quiet" ] | "editorkey" [ "," "quiet" ] | "listmaster" [ "," "notify" ] | "owner" [ "," "quiet" ] | "reject" ( "(" "reason=" reason_key ")" | "(" "tt2=" tpl_name ")" | "," "quiet" )* | "reject(tt2=" tpl_name ")" [ "," "quiet" ] | "request_auth" [ "([email])" ] =head1 FILES =over =item $EXPLDIRCIC =item $SYSCONFDIRCIC =item $SYSCONFDIRC =item $DEFAULTDIRC Path of scenario files: List, robot and site levels, and distribution defaults. =back =head1 SEE ALSO L. =head1 HISTORY Original contents of this document were partially taken from a chapter "Authorization scenarios" in I. =cut