-/******************************************************************************
- *
- * Copyright (C) 2000 Pierangelo Masarati, <ando@sys-net.it>
- * All rights reserved.
- *
- * Permission is granted to anyone to use this software for any purpose
- * on any computer system, and to alter it and redistribute it, subject
- * to the following restrictions:
- *
- * 1. The author is not responsible for the consequences of use of this
- * software, no matter how awful, even if they arise from flaws in it.
- *
- * 2. The origin of this software must not be misrepresented, either by
- * explicit claim or by omission. Since few users ever read sources,
- * credits should appear in the documentation.
- *
- * 3. Altered versions must be plainly marked as such, and must not be
- * misrepresented as being the original software. Since few users
- * ever read sources, credits should appear in the documentation.
- *
- * 4. This notice may not be removed or altered.
- *
- ******************************************************************************/
-
-/*
- * Description
- *
- * A string is rewritten according to a set of rules, called
- * a `rewrite context'.
- * The rules are based on Regular Expressions (POSIX regex) with
- * substring matching; extensions are planned to allow basic variable
- * substitution and map resolution of substrings.
- * The behavior of pattern matching/substitution can be altered by a
- * set of flags.
- *
- * The underlying concept is to build a lightweight rewrite module
- * for the slapd server (initially dedicated to the back-ldap module).
- *
- *
- * Passes
- *
- * An incoming string is matched agains a set of rules. Rules are made
- * of a match pattern, a substitution pattern and a set of actions.
- * In case of match a string rewriting is performed according to the
- * substitution pattern that allows to refer to substrings matched
- * in the incoming string. The actions, if any, are finally performed.
- * The substitution pattern allows map resolution of substrings.
- * A map is a generic object that maps a substitution pattern to a
- * value.
- *
- *
- * Pattern Matching Flags
- *
- * 'C' honors case in matching (default is case insensitive)
- * 'R' use POSIX Basic Regular Expressions (default is Extended)
- *
- *
- * Action Flags
- *
- * ':' apply the rule once only (default is recursive)
- * '@' stop applying rules in case of match.
- * '#' stop current operation if the rule matches, and issue an
- * `unwilling to perform' error.
- * 'G{n}' jump n rules back and forth (watch for loops!). Note that
- * 'G{1}' is implicit in every rule.
- * 'I' ignores errors in rule; this means, in case of error, e.g.
- * issued by a map, the error is treated as a missed match.
- * The 'unwilling to perform' is not overridden.
- *
- * the ordering of the flags is significant. For instance:
- *
- * 'IG{2}' means ignore errors and jump two lines ahead both in case
- * of match and in case of error, while
- * 'G{2}I' means ignore errors, but jump thwo lines ahead only in case
- * of match.
- *
- * More flags (mainly Action Flags) will be added as needed.
- *
- *
- * Pattern matching:
- *
- * see regex(7)
- *
- *
- * String Substitution:
- *
- * the string substitution happens according to a substitution pattern.
- * - susbtring substitution is allowed with the syntax '\d'
- * where 'd' is a digit ranging 0-9 (0 is the full match).
- * I see that 0-9 digit expansion is a widely accepted
- * practise; however there is no technical reason to use
- * such a strict limit. A syntax of the form '\{ddd}'
- * should be fine if there is any need to use a higher
- * number of possible submatches.
- * - variable substitution will be allowed (at least when I
- * figure out which kind of variable could be proficiently
- * substituted)
- * - map lookup will be allowed (map lookup of substring matches
- * in gdbm, ldap(!), math(?) and so on maps 'a la sendmail'.
- * - subroutine invocation will make it possible to rewrite a
- * submatch in terms of the output of another rewriteContext
- *
- * Old syntax:
- *
- * '\' {0-9} [ '{' <name> [ '(' <args> ')' ] '}' ]
- *
- * where <name> is the name of a built-in map, and
- * <args> are optional arguments to the map, if
- * the map <name> requires them.
- * The following experimental maps have been implemented:
- *
- * \n{xpasswd}
- * maps the n-th substring match as uid to
- * the gecos field in /etc/passwd;
- *
- * \n{xfile(/absolute/path)}
- * maps the n-th substring match
- * to a 'key value' style plain text file.
- *
- * \n{xldap(ldap://url/with?%0?in?filter)
- * maps the n-th substring match to an
- * attribute retrieved by means of an LDAP
- * url with substitution of %0 in the filter
- * (NOT IMPL.)
- *
- * New scheme:
- *
- * - everything starting with '\' requires substitution;
- * - the only obvious exception is '\\', which is left as is;
- * - the basic substitution is '\d', where 'd' is a digit;
- * 0 means the whole string, while 1-9 is a submatch;
- * - in the outdated schema, the digit may be optionally
- * followed by a '{', which means pipe the submatch into
- * the map described by the string up to the following '}';
- * - the output of the map is used instead of the submatch;
- * - in the new schema, a '\' followed by a '{' invokes an
- * advanced substitution scheme. The pattern is:
- *
- * '\' '{' [{ <op> }] <name> '(' <substitution schema> ')' '}'
- *
- * where <name> must be a legal name for the map, i.e.
- *
- * <name> ::= [a-z][a-z0-9]* (case insensitive)
- * <op> ::= '>' '|' '&' '&&' '*' '**' '$'
- *
- * and <substitution schema> must be a legal substitution
- * schema, with no limits on the nesting level.
- * The operators are:
- * > sub context invocation; <name> must be a legal,
- * already defined rewrite context name
- * | external command invocation; <name> must refer
- * to a legal, already defined command name (NOT IMPL.)
- * & variable assignment; <name> defines a variable
- * in the running operation structure which can be
- * dereferenced later (NOT IMPL.)
- * * variable dereferencing; <name> must refer to a
- * variable that is defined and assigned for the
- * running operation (NOT IMPL.)
- * $ parameter dereferencing; <name> must refer to
- * an existing parameter; the idea is to make
- * some run-time parameters set by the system
- * available to the rewrite engine, as the client
- * host name, the bind dn if any, constant
- * parameters initialized at config time, and so
- * on (NOT IMPL.)
- *
- * Note: as the slapd parsing routines escape backslashes ('\'),
- * a double backslash is required inside substitution patterns.
- * To overcome the resulting heavy notation, the substitution escaping
- * has been delegated to the '%' symbol, which should be used
- * instead of '\' in string substitution patterns. The symbol can
- * be altered at will by redefining the related macro in "rewrite-int.h".
- * In the current snapshot, all the '\' on the left side of each rule
- * (the regex pattern) must be converted in '\\'; all the '\' on the
- * right side of the rule (the substitution pattern) must be turned
- * into '%'. In the following examples, the original (more readable)
- * syntax is used; however, in the servers/slapd/back-ldap/slapd.conf
- * example file, the working syntax is used.
- *
- *
- *
- * Rewrite context:
- *
- * a rewrite context is a set of rules which are applied in sequence.
- * The basic idea is to have an application initialize a rewrite
- * engine (think of Apache's mod_rewrite ...) with a set of rewrite
- * contexts; when string rewriting is required, one invokes the
- * appropriate rewrite context with the input string and obtains the
- * newly rewritten one if no errors occur.
- *
- * An interesting application, in back-ldap or in slapd itself,
- * could associate each basic server operation to a rewrite context
- * (most of them possibly aliasing the default one). Then, DN rewriting
- + could take place at any invocation of a backend operation.
- *
- * client -> server:
- * default if defined and no specific context is available
- * bindDn bind
- * searchBase search
- * searchFilter search
- * compareDn compare
- * addDn add
- * modifyDn modify
- * modrDn modrdn
- * newSuperiorDn modrdn
- * deleteDn delete
- *
- * server -> client:
- * searchResult search (only if defined; no default)
- *
- *
- * Configuration syntax:
- *
- * Basics:
- *
- * rewriteEngine { on | off }
- *
- * rewriteContext <context name> [ alias <aliased context name> ]
- *
- * rewriteRule <regex pattern> <substitution pattern> [ <flags> ]
- *
- *
- * Additional:
- *
- * rewriteMap <map name> <map type> [ <map attrs> ]
- *
- * rewriteParam <param name> <param value>
- *
- * rewriteMaxPasses <number of passes>
- *
- *
- *
- * rewriteEngine:
- *
- * if 'on', the requested rewriting is performed; if 'off', no
- * rewriting takes place (an easy way to stop rewriting without
- * altering too much the configuration file)
- *
- * rewriteContext:
- *
- * <context name> is the name that identifies the context, i.e.
- * the name used by the application to refer to the set of rules
- * it contains. It is used also to reference sub contexts in
- * string rewriting. A context may aliase another one. In this
- * case the alias context contains no rule, and any reference to
- * it will result in accessing the aliased one.
- *
- * rewriteRule:
- *
- * determines how a tring can be rewritten if a pattern is matched.
- * Examples are reported below.
- *
- * rewriteMap:
- *
- * allows to define a map that transforms substring rewriting into
- * something else. The map is referenced inside the substitution
- * pattern of a rule.
- *
- * rewriteParam:
- *
- * sets a value with global scope, that can be dereferenced by the
- * command '\{$paramName}'.
- *
- * rewriteMaxPasses:
- *
- * sets the maximum number of total rewriting passes taht can be
- * performed in a signle rewriting operation (to avoid loops).
- *
- *
- * Configuration examples:
- *
- * # set to 'off' to disable rewriting
- *
- * rewriteEngine on
- *
- *
- * # everything defined here goes into the 'default' context
- * # this rule changes the naming context of anything sent to
- * # 'dc=home,dc=net' to 'dc=OpenLDAP, dc=org'
- *
- * rewriteRule "(.*)dc=home,[ ]?dc=net" "\1dc=OpenLDAP, dc=org" ":"
- *
- *
- * # start a new context (ends input of the previous one)
- * # this rule adds blancs between dn parts if not present.
- *
- * rewriteContext addBlancs
- * rewriteRule "(.*),([^ ].*)" "\1, \2"
- *
- *
- * # this one eats blancs
- *
- * rewriteContext eatBlancs
- * rewriteRule "(.*),[ ](.*)" "\1,\2"
- *
- *
- * # here control goes back to the default rewrite context; rules are
- * # appended to the existing ones.
- * # anything that gets here is piped into rule 'addBlancs'
- *
- * rewriteContext default
- * rewriteRule ".*" "\{>addBlancs(\0)}" ":"
- *
- *
- * # anything with 'uid=username' gets looked up in /etc/passwd for
- * # gecos (I know it's nearly useless, but it is there just to
- * # test something fancy!). Note the 'I' flag that leaves
- * # 'uid=username' in place if 'username' does not have a valid
- * # account. Note also the ':' that forces the rule to be processed
- * # exactly once.
- *
- * rewriteContext uid2Gecos
- * rewriteRule "(.*)uid=([a-z0-9]+),(.+)" "\1cn=\2{xpasswd},\3" "I:"
- *
- *
- * # finally, in case of bind, if one uses a 'uid=username' dn,
- * # it is rewritten in 'cn=name surname' if possible.
- *
- * rewriteContext bindDn
- * rewriteRule ".*" "\{>addBlancs(\{>uid2Gecos(\0)})}" ":"
- *
- *
- * # the search base is rewritten according to 'default' rules
- *
- * rewriteContext searchBase alias default
- *
- *
- * # search results with OpenLDAP dn are rewritten back with
- * # 'dc=home,dc=net' naming context, with spaces eaten.
- *
- * rewriteContext searchResult
- * rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
- * "\{>eatBlancs(\1)}dc=home,dc=net" ":"
- *
- * # bind with email instead of full dn: we first need an ldap map
- * # that turns attributes into a dn (the filter is provided by the
- * # substitution string):
- *
- * rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
- *
- * # then we need to detect emails; note that the rule in case of match
- * # stops rewriting; in case of error, it is ignored.
- * # In case we are mapping virtual to real naming contexts, we also
- * # need to rewrite regular dns, because the definition of a bindDn
- * # rewrite context overrides the default definition.
- *
- * rewriteContext bindDn
- * rewriteRule "(mail=[^,]+@[^,]+)" "\{attr2dn(\1)}" "@I"
- *
- * # This is a rather sophisticate example. It massages a search filter
- * # in case who performs the search has administrative privileges.
- * # First we need to keep track of the bind dn of the incoming request:
- *
- * rewriteContext bindDn
- * rewriteRule ".+" "\{**&binddn(\0)}" ":"
- *
- * # a search filter containing 'uid=' is rewritten only if an
- * # appropriate dn is bound.
- * # to do this, in the first rule the bound dn is dereferenced, while
- * # the filter is decomposed in a prefix, the argument of the 'uid=',
- * # and in a suffix. A tag '<>' is appended to the dn. If the dn
- * # refers to an entry in the 'ou=admin' subtree, the filter is
- * # rewritten OR-ing the 'uid=<arg>' with 'cn=<arg>'; otherwise
- * # it is left as is. This could be useful, for instance, to allow
- * # apache's auth_ldap-1.4 module to authenticate users with both
- * # 'uid' and 'cn', but only if the request comes from a possible
- * # 'dn: cn=Web auth, ou=admin, dc=home, dc=net' user.
- *
- * rewriteContext searchFilter
- * rewriteRule "(.*\()uid=([a-z0-9_]+)(\).*)"
- * "\{**binddn}<>\{&prefix(\1)}\{&arg(\2)}\{&suffix(\3)}" ":I"
- * rewriteRule "[^,]+,[ ]?ou=admin,[ ]?dc=home,[ ]?dc=net"
- * "\{*prefix}|(uid=\{*arg})(cn=\{*arg})\{*suffix}" "@I"
- * rewriteRule ".*<>" "\{*prefix}uid=\{*arg}\{*suffix}"
- *
- *
- * LDAP Proxy resolution (a possible evolution of the back-ldap):
- *
- * in case the rewritten dn is an LDAP URL, the operation is initiated
- * towards the host[:port] indicated in the url, if it does not refer
- * to the local server.
- *
- * e.g.:
- *
- * rewriteRule '^cn=root,.*' '\0' 'G{3}'
- * rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/\0' '@'
- * rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/\0' '@'
- * rewriteRule '.*' 'ldap://ldap3.my.org/\0' '@'
- *
- * (rule 1 is simply there to illustrate the 'G{n}' action; it could
- * have been written:
- *
- * rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/\0' '@'
- *
- * with the advantage of saving one rewrite pass ...)
- */
-
+The workings of the rewrite library are described in the
+REWRITING section of the slapd-meta(5) manual page.
projects / openldap / blobdiff