01411: Explain Qualify() in PmWiki.Functions

Summary: Explain Qualify() in PmWiki.Functions
Created: 2017-06-18 11:32
Status: Closed, documented
Category: Documentation
From: Sven
Priority: 3
Version: live on pmwiki.org
OS: pmwiki.org

Description: I checked the API for RetrieveAuthSection in PmWiki.Functions and found a reminder "The caller is responsible for calling Qualify() as needed." I couldn't however find any description of Qualify() in the docs, especially about what kind of effects to expect if I or other recipe authors take this responsibility too lightly. I consider this high priority because I fear it could cause severe security problems if this is about defusing maliciously crafted inputs. Sven June 18, 2017, at 11:33 AM

PS: I did try (for a few minutes) to search the source code for explanation, but couldn't find an easy HTTP-browseable copy of it earlier. Now that I found the Subversion page, but no link to an http-to-svn bridge on it, I get the impression that we really don't have the source on display yet, do we? Sven June 18, 2017, at 12:21 PM

Update: I managed to find a 3rd-party auto-migrated copy on Github and added the source explanation to docs. Looks like it's not about security (right?) so I'll decrease priority to normal. On another note, how about refactoring the function explanations to a page for each, and pagelist-ing them (with partial include) in alphabetical order? Sven June 18, 2017, at 12:35 PM

RetrieveAuthSection will return a page section from another page, possibly in OtherGroup, if the current user has read permissions. However, in that section, links like [[Page]] need to be rewritten ("qualified") as [[OtherGroup/Page]], as well as variables like {$Title} into {OtherGroup.OtherPage$Title} otherwise links and variables may not work as expected. This rewriting or "qualification" is done by Qualify(). The comment reminds, if you use RetrieveAuthSection() to get a section from another page, make sure you also call Qualify() on the resulting text of the section. --Petko June 18, 2017, at 03:43 PM

I added my recent findings on the Functions page earlier, so now from my point of view it's documented well enough that I'll close this issue. :-) — Sven June 24, 2017, at 07:32 PM