XQuery Function Documentation

http://exist-db.org/xquery/securitymanager

java:org.exist.xquery.functions.securitymanager.SecurityManagerModule

Module for interacting with the Security Manager

sm:add-group-ace

sm:add-group-ace($path as xs:anyURI, $group-name as xs:string, $allowed as xs:boolean, $mode as xs:string) as empty-sequence()

Adds a Group ACE to the ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to add the ACE to.
$group-name	The name of the group to create an ACE for.
$allowed	true() if the ACE is allowing the permission mode, or false() if we are denying the permission mode
$mode	The mode to set on the ACE e.g. 'rwx'

Returns:

empty-sequence()

sm:add-group-manager

sm:add-group-manager($group as xs:string, $manager as xs:string+) as empty-sequence()

Adds a manager to a groups managers. Can only be called by a group manager or DBA.

Parameters:

$group	The name of the group to which you wish to add a manager(s).
$manager+	The user(s) to add to the group managers.

Returns:

empty-sequence()

sm:add-group-member

sm:add-group-member($group as xs:string, $member as xs:string+) as empty-sequence()

Adds a user to a group. Can only be called by a group manager or DBA.

Parameters:

$group	The name of the group whoose membership you wish to modify.
$member+	The user(s) to add to the group membership.

Returns:

empty-sequence()

sm:add-user-ace

sm:add-user-ace($path as xs:anyURI, $user-name as xs:string, $allowed as xs:boolean, $mode as xs:string) as empty-sequence()

Adds a User ACE to the ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to add the ACE to.
$user-name	The name of the user to create an ACE for.
$allowed	true() if the ACE is allowing the permission mode, or false() if we are denying the permission mode
$mode	The mode to set on the ACE e.g. 'rwx'

Returns:

empty-sequence()

sm:chgrp

sm:chgrp($path as xs:anyURI, $group-name as xs:string) as empty-sequence()

Changes the group owner of a resource or collection.

Parameters:

$path	The path to the resource or collection whose group owner you wish to set
$group-name	The name of the user group owner to set on the resource or collection e.g. 'guest'

Returns:

empty-sequence()

sm:chmod

sm:chmod($path as xs:anyURI, $mode as xs:string) as empty-sequence()

Changes the mode of a resource or collection.

Parameters:

$path	The path to the resource or collection whose mode you wish to set
$mode	The mode to set on the resource or collection e.g. 'rwxrwxrwx'

Returns:

empty-sequence()

sm:chown

sm:chown($path as xs:anyURI, $owner as xs:string) as empty-sequence()

Changes the owner of a resource or collection.

Parameters:

$path	The path to the resource or collection whose owner you wish to set
$owner	The name of the user owner to set on the resource or collection e.g. 'guest'. You may also provide a group owner, by using the syntax 'user:group' if you wish.

Returns:

empty-sequence()

sm:clear-acl

sm:clear-acl($path as xs:anyURI) as empty-sequence()

Removes all ACEs from the ACL of a resource or collection.

Parameters:

$path

The path to the resource or collection whose ACL you wish to clear.

Returns:

empty-sequence()

sm:create-account

sm:create-account($username as xs:string, $password as xs:string, $primary-group as xs:string, $groups as xs:string*) as empty-sequence()

Creates a User Account.

Parameters:

$username	The User's username.
$password	The User's password.
$primary-group	The primary group of the user.
$groups*	Any supplementary groups of which the user should be a member.

Returns:

empty-sequence()

sm:create-account

sm:create-account($username as xs:string, $password as xs:string, $primary-group as xs:string, $groups as xs:string*, $full-name as xs:string, $description as xs:string) as empty-sequence()

Creates a User Account.

Parameters:

$username	The User's username.
$password	The User's password.
$primary-group	The primary group of the user.
$groups*	Any supplementary groups of which the user should be a member.
$full-name	The full name of the user.
$description	A description of the user.

Returns:

empty-sequence()

sm:create-account

sm:create-account($username as xs:string, $password as xs:string, $groups as xs:string*) as empty-sequence()

Creates a User Account and a personal group for that user. The personal group takes the same name as the user, and is set as the user's primary group.

Parameters:

$username	The User's username.
$password	The User's password.
$groups*	Any supplementary groups of which the user should be a member.

Returns:

empty-sequence()

sm:create-account

sm:create-account($username as xs:string, $password as xs:string, $groups as xs:string*, $full-name as xs:string, $description as xs:string) as empty-sequence()

Creates a User Account and a personal group for that user. The personal group takes the same name as the user, and is set as the user's primary group.

Parameters:

$username	The User's username.
$password	The User's password.
$groups*	Any supplementary groups of which the user should be a member.
$full-name	The full name of the user.
$description	A description of the user.

Returns:

empty-sequence()

sm:create-group

sm:create-group($group-name as xs:string) as empty-sequence()

Creates a User Group. The current user will be set as the group's manager.

Parameters:

$group-name

The name of the group to create.

Returns:

empty-sequence()

sm:create-group

sm:create-group($group-name as xs:string, $description as xs:string) as empty-sequence()

Creates a User Group. The current user will be set as the group's manager.

Parameters:

$group-name	The name of the group to create.
$description	A description of the group.

Returns:

empty-sequence()

sm:create-group

sm:create-group($group-name as xs:string, $managers as xs:string+, $description as xs:string) as empty-sequence()

Creates a User Group. The current user will be set as a manager of the group in addition to the specified managers.

Parameters:

$group-name	The name of the group to create.
$managers+	The usernames of users that will be a manager of this group.
$description	A description of the group.

Returns:

empty-sequence()

sm:find-groups-by-groupname

sm:find-groups-by-groupname($starts-with as xs:string) as xs:string*

Finds groups whoose group name starts with a matching string

Parameters:

$starts-with

The starting string against which to match group names

Returns:

xs:string* : The list of matching group names

sm:find-groups-where-groupname-contains

sm:find-groups-where-groupname-contains($fragment as xs:string) as xs:string*

Finds groups whoose group name contains the string fragment

Parameters:

$fragment

The fragment against which to match group names

Returns:

xs:string* : The list of matching group names

sm:find-users-by-name

sm:find-users-by-name($starts-with as xs:string) as xs:string*

Finds users whoose personal name starts with a matching string

Parameters:

$starts-with

The starting string against which to match a personal name

Returns:

xs:string* : The list of matching usernames

sm:find-users-by-name-part

sm:find-users-by-name-part($starts-with as xs:string) as xs:string*

Finds users whoose first name or last name starts with a matching string

Parameters:

$starts-with

The starting string against which to match a first or last name

Returns:

xs:string* : The list of matching usernames

sm:find-users-by-username

sm:find-users-by-username($starts-with as xs:string) as xs:string*

Finds users whoose username starts with a matching string

Parameters:

$starts-with

The starting string against which to match usernames

Returns:

xs:string* : The list of matching usernames

sm:get-account-metadata

sm:get-account-metadata($username as xs:string, $attribute as xs:anyURI) as xs:string?

Gets a metadata attribute value for an account

Parameters:

$username	The username of the account to retrieve metadata from.
$attribute	The fully qualified metadata attribute key name

Returns:

xs:string? : The metadata value

sm:get-account-metadata-keys

sm:get-account-metadata-keys() as xs:anyURI*

Gets a sequence of the metadata attribute keys that may be used for an account.

Returns:: xs:anyURI* : The fully qualified metadata attribute key names

sm:get-account-metadata-keys

sm:get-account-metadata-keys($username as xs:string) as xs:anyURI*

Gets a sequence of the metadata attribute keys present for an account

Parameters:

$username

The username of the account to retrieve metadata from.

Returns:

xs:anyURI* : The fully qualified metadata attribute key names

sm:get-group-managers

sm:get-group-managers($group as xs:string) as xs:string+

Gets a list of the group managers. Can only be called by a group manager.

Parameters:

$group

The group name to retrieve the list of managers for.

Returns:

xs:string+ : The list of group managers for the group $group

sm:get-group-members

sm:get-group-members($group as xs:string) as xs:string+

Gets a list of the group members.

Parameters:

$group

The group name to retrieve the list of members for.

Returns:

xs:string+ : The list of group members for the group $group

sm:get-group-metadata

sm:get-group-metadata($group-name as xs:string, $attribute as xs:anyURI) as xs:string?

Gets a metadata attribute value for a group

Parameters:

$group-name	The name of the group to retrieve metadata from.
$attribute	The fully qualified metadata attribute key name

Returns:

xs:string? : The metadata value

sm:get-group-metadata-keys

sm:get-group-metadata-keys() as xs:anyURI*

Gets a sequence of the metadata attribute keys that may be used for a group.

Returns:: xs:anyURI* : The fully qualified metadata attribute key names

sm:get-group-metadata-keys

sm:get-group-metadata-keys($group-name as xs:string) as xs:anyURI*

Gets a sequence of the metadata attribute keys present for a group

Parameters:

$group-name

The name of the group to retrieve metadata from.

Returns:

xs:anyURI* : The fully qualified metadata attribute key names

sm:get-permissions

sm:get-permissions($path as xs:anyURI) as document-node()

Gets the permissions of a resource or collection.

Parameters:

$path

The path to the resource or collection to get permissions of.

Returns:

document-node() : The permissions of the resource or collection

sm:get-umask

sm:get-umask($username as xs:string) as xs:int*

Gets the umask of a Users Account.

Parameters:

$username

The username of the account to retrieve the umask for.

Returns:

xs:int* : The umask of the users account expressed as an integer

sm:get-user-groups

sm:get-user-groups($user as xs:string) as xs:string+

Returns the sequence of groups that the user $user is a member of. You must be a DBA or logged in as the user for which you are trying to retrieve group details for.

Parameters:

$user

The username to retrieve the group membership list for.

Returns:

xs:string+ : The users group memberships

sm:get-user-primary-group

sm:get-user-primary-group($user as xs:string) as xs:string

Returns the primary group of the user $user. You must be a DBA or logged in as the user for which you are trying to retrieve group details for.

Parameters:

$user

The username to retrieve the primary group of.

Returns:

xs:string : The users primary group

sm:group-exists

sm:group-exists($group as xs:string) as xs:boolean

Determines whether a user group exists.

Parameters:

$group

The name of the user group to check for existence.

Returns:

xs:boolean : true if the user group exists, false otherwise.

sm:has-access

sm:has-access($path as xs:anyURI, $mode as xs:string) as xs:boolean

Checks whether the current user has access to the resource or collection.

Parameters:

$path	The path to the resource or collection whose access of which you wish to check
$mode	The partial mode to check against the resource or collection e.g. 'rwx'

Returns:

xs:boolean

sm:id

sm:id() as document-node()

Returns the user and group names of the account executing the XQuery. If the real and effective accounts are different, then both the real and effective account details are returned, otherwise only the real account details are returned.

Returns:: document-node() : Example output when an XQuery is running setUid <id xmlns="http://exist-db.org/xquery/securitymanager"><real><username>guest</username><groups><group>guest</group></groups></real><effective><username>admin</username><groups><group>dba</group></groups></effective></id>.

sm:insert-group-ace

sm:insert-group-ace($path as xs:anyURI, $index as xs:int, $group-name as xs:string, $allowed as xs:boolean, $mode as xs:string) as empty-sequence()

Inserts a Group ACE into the ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to add the ACE to.
$index	The index in the ACL to insert the ACE before, subsequent entries will be renumbered
$group-name	The name of the group to create an ACE for.
$allowed	true() if the ACE is allowing the permission mode, or false() if we are denying the permission mode
$mode	The mode to set on the ACE e.g. 'rwx'

Returns:

empty-sequence()

sm:insert-user-ace

sm:insert-user-ace($path as xs:anyURI, $index as xs:int, $user-name as xs:string, $allowed as xs:boolean, $mode as xs:string) as empty-sequence()

Inserts a User ACE into the ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to add the ACE to.
$index	The index in the ACL to insert the ACE before, subsequent entries will be renumbered
$user-name	The name of the user to create an ACE for.
$allowed	true() if the ACE is allowing the permission mode, or false() if we are denying the permission mode
$mode	The mode to set on the ACE e.g. 'rwx'

Returns:

empty-sequence()

sm:is-account-enabled

sm:is-account-enabled($username as xs:string) as xs:boolean

Determines whether a user account is enabled. You must be a DBA, or you must be enquiring about your own user account.

Parameters:

$username

The username of the account to check the status for.

Returns:

xs:boolean : true if the account is enabled, false otherwise.

sm:is-authenticated

sm:is-authenticated() as xs:boolean

Returns the true() if current account is authenticated, false() otherwise.

Returns:: xs:boolean : true() if user from the xquery context is authenticated, false() otherwise

sm:is-dba

sm:is-dba($username as xs:string) as xs:boolean

Determines if the user is a DBA.

Parameters:

$username

The username of the user account to check if they are a member of the DBA group.

Returns:

xs:boolean : true of the user is a DBA, false otherwise.

sm:is-externally-authenticated

sm:is-externally-authenticated() as xs:boolean

Returns the true() if current account is authenticated by an external realm, false() otherwise.

Returns:: xs:boolean : true() if user from the xquery context is authenticated, false() otherwise

sm:list-groups

sm:list-groups() as xs:string*

List all groups

Returns:: xs:string* : The list of groups

sm:list-users

sm:list-users() as xs:string+

List all users. You must be a DBA to enumerate all users, if you are not a DBA you will just get the username of the currently logged in user.

Returns:: xs:string+ : The list of users.

sm:mode-to-octal

sm:mode-to-octal($mode as xs:string) as xs:string

Converts a mode string e.g. 'rwxrwxrwx' to an octal number e.g. 0777.

Parameters:

$mode

The mode to convert to an octal string.

Returns:

xs:string

sm:modify-ace

sm:modify-ace($path as xs:anyURI, $index as xs:int, $allowed as xs:boolean, $mode as xs:string) as empty-sequence()

Modified an ACE of an ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to modify the ACE of.
$index	The index of the ACE in the ACL to modify
$allowed	true() if the ACE is allowing the permission mode, or false() if we are denying the permission mode
$mode	The mode to set on the ACE e.g. 'rwx'

Returns:

empty-sequence()

sm:octal-to-mode

sm:octal-to-mode($octal as xs:string) as xs:string

Converts an octal string e.g. '0777' to a mode string e.g. 'rwxrwxrwx'.

Parameters:

$octal

The octal string to convert to a mode.

Returns:

xs:string

sm:passwd

sm:passwd($username as xs:string, $password as xs:string) as empty-sequence()

Changes the password of a User Account.

Parameters:

$username	The User's username.
$password	The User's new password.

Returns:

empty-sequence()

sm:passwd-hash

sm:passwd-hash($username as xs:string, $password-digest as xs:string) as empty-sequence()

Changes the password of a User Account by directly setting the stored digest password. The use-case for this function is migrating a user from one eXist instance to another.

Parameters:

$username	The User's username.
$password-digest	The encoded digest of the User's new password (assumes eXist's default digest algorithm).

Returns:

empty-sequence()

sm:remove-account

sm:remove-account($username as xs:string) as empty-sequence()

Removes a User Account. If the user has a personal group you are responsible for removing that separately through sm:remove-group.

Parameters:

$username

The User's username.

Returns:

empty-sequence()

sm:remove-ace

sm:remove-ace($path as xs:anyURI, $index as xs:int) as empty-sequence()

Removes an ACE from the ACL of a resource or collection.

Parameters:

$path	The path to the resource or collection whose ACL you wish to remove the ACE from.
$index	The index of the ACE in the ACL to remove, subsequent entries will be renumbered

Returns:

empty-sequence()

sm:remove-group

sm:remove-group($group-name as xs:string) as empty-sequence()

Remove a User Group.

Parameters:

$group-name

The group-id to delete

Returns:

empty-sequence()

sm:remove-group-manager

sm:remove-group-manager($group as xs:string, $manager as xs:string+) as empty-sequence()

Removes a manager from a groups managers. Can only be called by a group manager of DBA.

Parameters:

$group	The name of the group from which you wish to remove a manager(s)
$manager+	The user(s) to remove from the group managers.

Returns:

empty-sequence()

sm:remove-group-member

sm:remove-group-member($group as xs:string, $member as xs:string+) as empty-sequence()

Removes a user from a group. Can only be called by a group manager of DBA.

Parameters:

$group	The name of the group whoose membership you wish to modify.
$member+	The user(s) to remove from the group membership.

Returns:

empty-sequence()

sm:set-account-enabled

sm:set-account-enabled($username as xs:string, $enabled as xs:boolean) as empty-sequence()

Enabled or disables a users account. You must be a DBA to enable or disable an account.

Parameters:

$username	The username of the account to enable or disable.
$enabled	true to enable the account, false to disable the account.

Returns:

empty-sequence()

sm:set-account-metadata

sm:set-account-metadata($username as xs:string, $attribute as xs:anyURI, $value as xs:string) as empty-sequence()

Sets a metadata attribute value for an account

Parameters:

$username	The username of the account to set metadata for.
$attribute	The metadata attribute key.
$value	The metadata value,

Returns:

empty-sequence()

sm:set-group-metadata

sm:set-group-metadata($group-name as xs:string, $attribute as xs:anyURI, $value as xs:string) as empty-sequence()

Sets a metadata attribute value for a group

Parameters:

$group-name	The name of the group to set metadata for.
$attribute	The metadata attribute key.
$value	The metadata value,

Returns:

empty-sequence()

sm:set-umask

sm:set-umask($username as xs:string, $umask as xs:int) as empty-sequence()

Sets the umask of a Users Account.

Parameters:

$username	The username of the account to set the umask for.
$umask	The umask to set as an integer.

Returns:

empty-sequence()

sm:set-user-primary-group

sm:set-user-primary-group($username as xs:string, $group as xs:string) as empty-sequence()

Sets the primary group of a user account. If the user is not yet in the group, then they are added to the group first.

Parameters:

$username	The name of the user account to set the primary group for.
$group	The group to set as the primary group for the user.

Returns:

empty-sequence()

sm:user-exists

sm:user-exists($user as xs:string) as xs:boolean

Determines whether a user exists.

Parameters:

$user

The username to check for existence.

Returns:

xs:boolean : true if the user account exists, false otherwise.