VAL
Virtuoso Authentication Layer
VAL Internal ACL Utility API

Functions

 VAL.DBA.add_ownership_graph (varchar uri, varchar scope)
 Add a resource ownership graph. More...
 
 VAL.DBA.add_resource_ownership (varchar scope, varchar resource, varchar serviceId)
 Add a resource ownership relation. More...
 
 VAL.DBA.check_acls_for_resource_basic (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 Check Basic ACLs for a resource. More...
 
 VAL.DBA.check_acls_for_resource_conditional (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 Check Conditional ACLs for a resource. More...
 
 VAL.DBA.check_acls_for_resource_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 Check ACLs granting access to IP Addresses. More...
 
 VAL.DBA.check_acls_for_resource_public (varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 Check Public ACLs for a resource. More...
 
 VAL.DBA.check_resource_ownership (varchar serviceId, varchar resource, varchar scope, varchar sameAsGraph=null)
 Check the ownership of a resource. More...
 
 VAL.DBA.find_acl_permissions_basic (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 
 VAL.DBA.find_acl_permissions_conditional (varchar serviceId, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int evalRecursiveRules=0)
 
 VAL.DBA.find_acl_permissions_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 
 VAL.DBA.find_acl_permissions_public (varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)
 
 VAL.DBA.find_restrictions_basic (varchar serviceId, varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
 Find the restriction values from basic rules. More...
 
 VAL.DBA.find_restrictions_conditional (varchar serviceId, varchar resource, varchar realm, varchar webidGraph=null, any certificate=null, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
 Find the restriction values from conditional rules. More...
 
 VAL.DBA.find_restrictions_ip_address (varchar ipAddress, varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null)
 Find the restriction values from IP Address based rules. More...
 
 VAL.DBA.find_restrictions_public (varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null)
 Find the restriction values from public rules. More...
 
 VAL.DBA.get_acl_schema_graph ()
 The VAL ACL Schema graph IRI. More...
 
 VAL.DBA.get_dav_scope ()
 The IRI of the DAV ACL rule scope. More...
 
 VAL.DBA.get_owned_graphs (varchar serviceId)
 Get the graphs owned by a given service id. More...
 
 VAL.DBA.get_query_scope ()
 The IRI of the Query ACL rule scope. More...
 
 VAL.DBA.get_resource_owner (varchar resource, varchar scope)
 Get the owner of a resource. More...
 
 VAL.DBA.get_restrictions_scope ()
 The IRI of the Restrictions ACL rule scope. More...
 
 VAL.DBA.get_sparql_scope ()
 The IRI of the Private named graphs ACL rule scope. More...
 
 VAL.DBA.ownership_graph_group (varchar scope)
 The URI of the graph group used to combine all resource ownership graphs. More...
 
 VAL.DBA.remove_ownership_graph (varchar uri, varchar scope)
 Remove a resource ownership graph. More...
 
 VAL.DBA.set_resource_ownership (varchar scope, varchar resource, varchar serviceId)
 Set the owner of a resource in a given scope. More...
 
 VAL.DBA.sparql_graph_ownership_graph ()
 Graph containing the ownership relations for named graphs. More...
 

Detailed Description

The procedures in the utility API can be used in applications to enforce the ACL rules and to maintain Resource Ownership. Most notably VAL.DBA.val_prepare_sparql_permissions_for_query() needs to be called before each SPARQL query to ensure proper permissions.

In contrast to the procedures in VAL Internal ACL API the usage of these procedures is encouraged and often necessary.

Function Documentation

◆ add_ownership_graph()

VAL.DBA.add_ownership_graph ( varchar  uri,
varchar  scope 
)

Add a resource ownership graph.

VAL uses the ownership definitions in all ownershop graphs to determine if a user is allowed to create ACL rules for a resource.

This procedure allows to add a named graph for VAL to search. This graph should contain triples like

<http://www.facebook.com/foobar> foaf:made <urn:someresource> .

This would allow the authenticated user http://www.facebook.com/foobar to create ACL rules for resource urn:someresource.

Be aware that the SPARQL ownership is handled by VAL via VAL.DBA.add_graph_ownership() and VAL.DBA.remove_graph_ownership().

Also VAL provides convinience procedures like VAL.DBA.set_resource_ownership () to avoid the need for clients to define their own ownership graphs.

See also
VAL.DBA.remove_ownership_graph()

◆ add_resource_ownership()

VAL.DBA.add_resource_ownership ( varchar  scope,
varchar  resource,
varchar  serviceId 
)

Add a resource ownership relation.

Instead of defining an ownership graph manually and adding it via VAL.DBA.add_ownership_graph() one can simply use VAL.DBA.add_resource_ownership(), VAL.DBA.set_resource_ownership(), and VAL.DBA.remove_resource_ownership() to simplify things and let VAL handle the rest.

This procedure will try to add a new ownership relation. In contrast to VAL.DBA.set_resource_ownership() it will not overwrite existing ownership but throw a signal instead.

See also
VAL.DBA.set_resource_ownership(), VAL.DBA.remove_resource_ownership()

◆ check_acls_for_resource_basic()

VAL.DBA.check_acls_for_resource_basic ( varchar  serviceId,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
varchar  sameAsGraph = null,
int  evalRecursiveRules = 0 
)

Check Basic ACLs for a resource.

Checks basic ACL rules for access to one or more resources. This includes rules which grant access to a person or a static group. Conditional groups are handled by VAL.DBA.check_acls_for_resource_conditional().

In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.

Parameters
serviceIdThe service id which access is requested for.
resourceThe optional resource to request access to. If not given all resources serviceId has access to are returned.
realmThe application realm in which permissions should be checked.
modeThe optional access mode to check for. If not given all granted access modes are returned.
scopeThe optional scope of the queried rules. A scope defines the type of resource.
sameAsGraphThis is the graph from which VAL will read owl:sameAs triples to determine which service URIs denote the same person. This defaults to VAL.DBA.val_owl_sameas_graph () which is based on account mappings in VAL.DBA.VAL_USER_ONLINE_ACCOUNTS.
evalRecursiveRulesIf 1 then recursive rules will be evaluated for scopes other than DAV. See Recursion Based On Relations for details on how the rules are evaluated.
Returns
A vector which contains key/value pairs mapping resources to a list of the granted access modes. The access modes are represented by URIs as stored in the ACLs
See also
VAL.DBA.check_acls_for_resource(), VAL.DBA.check_acls_for_resource_public(), VAL.DBA.check_acls_for_resource_conditional()

◆ check_acls_for_resource_conditional()

VAL.DBA.check_acls_for_resource_conditional ( varchar  serviceId,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
varchar  webidGraph = null,
any  certificate = null,
varchar  sameAsGraph = null,
int  evalRecursiveRules = 0 
)

Check Conditional ACLs for a resource.

Checks conditional ACL rules for access to one or more resources. This includes rules which grant access to a conditional group. Conditional groups are handled by VAL.DBA.check_acls_for_resource_basic().

In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.

Parameters
serviceIdThe service id which access is requested for.
resourceThe optional resource to request access to. If not given all resources serviceId has access to are returned.
realmThe application realm in which permissions should be checked.
modeThe optional access mode to check for. If not given all granted access modes are returned.
scopeThe optional scope of the queried rules. A scope defines the type of resource.
webidGraphThe optional named graph which contains the triples imported from the WebID profile if certificate contains an embedded WebID.
certificateThe optional client certificate used for authentication.
sameAsGraphThis is the graph from which VAL will read owl:sameAs triples to determine which service URIs denote the same person. This defaults to VAL.DBA.val_owl_sameas_graph () which is based on account mappings in VAL.DBA.VAL_USER_ONLINE_ACCOUNTS.
evalRecursiveRulesIf 1 then recursive rules will be evaluated for scopes other than DAV. See Recursion Based On Relations for details on how the rules are evaluated.
Returns
A vector which contains key/value pairs mapping resources to a list of the granted access modes. The access modes are represented by URIs as stored in the ACLs
See also
VAL.DBA.check_acls_for_resource(), VAL.DBA.check_acls_for_resource_public(), VAL.DBA.check_acls_for_resource_basic()

◆ check_acls_for_resource_ip_address()

VAL.DBA.check_acls_for_resource_ip_address ( varchar  ipAddress,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
int  evalRecursiveRules = 0 
)

Check ACLs granting access to IP Addresses.

Checks ACL rules for access to one or more resources. ACLs which grant access for service ids are handled by VAL.DBA.check_acls_for_resource().

Parameters
ipAddressThe IP address which access is requested for.
resourceThe optional resource to request access to. If not given all resources serviceId has access to are returned.
realmThe application realm in which permissions should be checked.
modeThe optional access mode to check for. If not given all granted access modes are returned.
scopeThe optional scope of the queried rules. A scope defines the type of resource.
evalRecursiveRulesIf 1 then recursive rules will be evaluated for scopes other than DAV. See Recursion Based On Relations for details on how the rules are evaluated.
Returns
A vector which contains key/value pairs mapping resources to a list of the granted access modes. The access modes are represented by URIs as stored in the ACLs
See also
VAL.DBA.check_acls_for_resource(), VAL.DBA.check_acls_for_resource_public(), VAL.DBA.check_acls_for_resource_conditional()

◆ check_acls_for_resource_public()

VAL.DBA.check_acls_for_resource_public ( varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
int  evalRecursiveRules = 0 
)

Check Public ACLs for a resource.

Checks public ACL rules for access to one or more resources. This means rules that grant access to foaf:Agent. Basic rules are handled by VAL.DBA.check_acls_for_resource_basic(), conditional groups are handled by VAL.DBA.check_acls_for_resource_conditional().

In general it is recommended to use VAL.DBA.check_acls_for_resource() instead.

Parameters
resourceThe optional resource to request access to. If not given all resources serviceId has access to are returned.
realmThe application realm in which permissions should be checked.
modeThe optional access mode to check for. If not given all granted access modes are returned.
scopeThe optional scope of the queried rules. A scope defines the type of resource.
evalRecursiveRulesIf 1 then recursive rules will be evaluated for scopes other than DAV. See Recursion Based On Relations for details on how the rules are evaluated.
Returns
A vector which contains key/value pairs mapping resources to a list of the granted access modes. The access modes are represented by URIs as stored in the ACLs
See also
VAL.DBA.check_acls_for_resource(), VAL.DBA.check_acls_for_resource_basic(), VAL.DBA.check_acls_for_resource_conditional()

◆ check_resource_ownership()

VAL.DBA.check_resource_ownership ( varchar  serviceId,
varchar  resource,
varchar  scope,
varchar  sameAsGraph = null 
)

Check the ownership of a resource.

Check if the given serviceId does own the given resource in the given scope. If scope is not null then specific ownership is tested. That means specific scopes can have their own way of defining ownership. A typical example is DAV which is checked via the permissions of the resource.

Returns
1 in case serviceId does own resource, 0 otherwise.
See also
VAL.DBA.add_ownership_graph()

◆ find_acl_permissions_basic()

VAL.DBA.find_acl_permissions_basic ( varchar  serviceId,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
varchar  sameAsGraph = null,
int  evalRecursiveRules = 0 
)

Find all permissions a given serviceId has on a given resource (or any resource if omitted) in the given application realm. If mode is specified, only that mode is verified and returned. This procedure only checks basic rules, ie. such rules that grant permissions to a person or a static group.

This procedure creates a result set. As such it is suitable for queries and can be used as follows:

for (select _resource, _mode
from VAL.DBA.find_acl_permissions_basic (s, res, rlm, m)(_resource varchar, _mode varchar) x
where s = myServiceId and
res = myResource and
rlm = myRealm and
m = myMode) do {
do_something_with_permissions (_resource, _mode);
}
See also
VAL.DBA.check_acls_for_resource_basic(), VAL.DBA.find_acl_permissions_public(), VAL.DBA.find_acl_permissions_conditional()

◆ find_acl_permissions_conditional()

VAL.DBA.find_acl_permissions_conditional ( varchar  serviceId,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
varchar  webidGraph = null,
any  certificate = null,
varchar  sameAsGraph = null,
int  evalRecursiveRules = 0 
)

Find all permissions a given serviceId has on a given resource (or any resource if omitted) in the given application realm. If mode is specified, only that mode is verified and returned. This procedure only checks conditional rules, ie. such rules that grant permissions to a conditional group.

This procedure creates a result set. As such it is suitable for queries and can be used as follows:

for (select _resource, _mode
from VAL.DBA.find_acl_permissions_conditional (s, res, rlm, m, wg, c)(_resource varchar, _mode varchar) x
where s = myServiceId and
res = myResource and
rlm = myRealm and
m = myMode and
wg = myWebidGraph and
c = myCertificate) do {
do_something_with_permissions (_resource, _mode);
}
See also
VAL.DBA.check_acls_for_resource_conditional(), VAL.DBA.find_acl_permissions_public(), VAL.DBA.find_acl_permissions_basic()

◆ find_acl_permissions_ip_address()

VAL.DBA.find_acl_permissions_ip_address ( varchar  ipAddress,
varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
int  evalRecursiveRules = 0 
)

Find all permissions a given ipAddress has on a given resource (or any resource if omitted) in the given application realm. If mode is specified, only that mode is verified and returned.

This procedure creates a result set. As such it is suitable for queries and can be used as follows:

for (select _resource, _mode
from VAL.DBA.find_acl_permissions_ip_address (ip, res, rlm, m)(_resource varchar, _mode varchar) x
where ip = myIpAddress and
res = myResource and
rlm = myRealm and
m = myMode) do {
do_something_with_permissions (_resource, _mode);
}
See also
VAL.DBA.check_acls_for_resource_ip_address(), VAL.DBA.find_acl_permissions_public(), VAL.DBA.find_acl_permissions_basic(), VAL.DBA.find_acl_permissions_conditional()

◆ find_acl_permissions_public()

VAL.DBA.find_acl_permissions_public ( varchar  resource = null,
varchar  realm,
varchar  mode = null,
varchar  scope = null,
int  evalRecursiveRules = 0 
)

Find all permissions granted by public rules on a given resource (or any resource if omitted) in the given application realm. If mode is specified, only that mode is verified and returned. This procedure only checks public rules, ie. such rules that grant permissions to foaf:Agent.

This procedure creates a result set. As such it is suitable for queries and can be used as follows:

for (select _resource, _mode
from VAL.DBA.find_acl_permissions_public (s, res, rlm, m)(_resource varchar, _mode varchar) x
where s = myServiceId and
res = myResource and
rlm = myRealm and
m = myMode) do {
do_something_with_permissions (_resource, _mode);
}
See also
VAL.DBA.check_acls_for_resource_public(), VAL.DBA.find_acl_permissions_basic(), VAL.DBA.find_acl_permissions_conditional()

◆ find_restrictions_basic()

VAL.DBA.find_restrictions_basic ( varchar  serviceId,
varchar  resource,
varchar  realm,
decimal  minValue,
decimal  maxValue,
varchar  parameter = null,
varchar  sameAsGraph = null 
)

Find the restriction values from basic rules.

This procedure will find the least restrictive values from all basic rules in the given realm for the given resource. This includes restrictions scoped to individuals and static groups.

sameAsGraph is the graph from which VAL will read owl:sameAs triples to determine which service URIs denote the same person. This defaults to VAL.DBA.val_owl_sameas_graph () which is based on account mappings in VAL.DBA.VAL_USER_ONLINE_ACCOUNTS.

Typically one would use VAL.DBA.find_restrictions() instead.

◆ find_restrictions_conditional()

VAL.DBA.find_restrictions_conditional ( varchar  serviceId,
varchar  resource,
varchar  realm,
varchar  webidGraph = null,
any  certificate = null,
decimal  minValue,
decimal  maxValue,
varchar  parameter = null,
varchar  sameAsGraph = null 
)

Find the restriction values from conditional rules.

This procedure will find the least restrictive values from all conditional rules in the given realm for the given resource. This means restrictions scoped to conditional groups.

sameAsGraph is the graph from which VAL will read owl:sameAs triples to determine which service URIs denote the same person. This defaults to VAL.DBA.val_owl_sameas_graph () which is based on account mappings in VAL.DBA.VAL_USER_ONLINE_ACCOUNTS.

Typically one would use VAL.DBA.find_restrictions() instead.

◆ find_restrictions_ip_address()

VAL.DBA.find_restrictions_ip_address ( varchar  ipAddress,
varchar  resource,
varchar  realm,
decimal  minValue,
decimal  maxValue,
varchar  parameter = null 
)

Find the restriction values from IP Address based rules.

This procedure will find the least restrictive values from all IP Address based rules in the given realm for the given resource.

Typically one would use VAL.DBA.find_restrictions() instead.

◆ find_restrictions_public()

VAL.DBA.find_restrictions_public ( varchar  resource,
varchar  realm,
decimal  minValue,
decimal  maxValue,
varchar  parameter = null 
)

Find the restriction values from public rules.

This procedure will find the least restrictive values from all public rules in the given realm for the given resource.

Typically one would use VAL.DBA.find_restrictions() instead.

◆ get_acl_schema_graph()

VAL.DBA.get_acl_schema_graph ( )

The VAL ACL Schema graph IRI.

To ensure that nobody can tamper with default access modes and the like it is important that the Openlink ACL and restriction ontologies are stored in a private trusted graph.

VAL uses the ACL schema graph urn:virtuoso:val:acl:schema for this purpose. It is mandatory for both the ACL and the restriction ontologies to be loaded into this graph for the VAL ACL system to work properly.

Returns
The IRI of the VAL ACL schema graph.
Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;

◆ get_dav_scope()

VAL.DBA.get_dav_scope ( )

The IRI of the DAV ACL rule scope.

This scope is special as VAL contains special ownership handling for DAV resources and collections. See DAV ACL Rules for details.

Returns
The IRI of the DAV resource scope: oplacl:Dav.
See also
Rule Scopes
Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;

◆ get_owned_graphs()

VAL.DBA.get_owned_graphs ( varchar  serviceId)

Get the graphs owned by a given service id.

VAL manages the ownership relations for named graphs. This procedure lists all graphs which have been set as owned by the given person.

Returns
a vector of graph IRIs.
See also
VAL.DBA.set_graph_ownership(), VAL.DBA.add_graph_ownership(), VAL.DBA.remove_graph_ownership()

◆ get_query_scope()

VAL.DBA.get_query_scope ( )

The IRI of the Query ACL rule scope.

This is used to group ACL rules which grant permission to execute SQL or SPARQL expressions in general. Applicable resources are:

  • urn:virtuoso:access:sql - Grants read and/or write access for SQL expressions.
  • urn:virtuoso:access:sparql - Grants read, write, and sponge permissions for SPARQL in general. Access to specific graphs is handled via rules in the sparql scope.
See also
Rule Scopes, VAL.DBA.get_sparql_scope()

◆ get_resource_owner()

VAL.DBA.get_resource_owner ( varchar  resource,
varchar  scope 
)

Get the owner of a resource.

This procedure checks resource ownership graphs and handles DAV as a special case.

Returns
The service URI of the owner of the given resource or null if none could be found.
Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;

◆ get_restrictions_scope()

VAL.DBA.get_restrictions_scope ( )

The IRI of the Restrictions ACL rule scope.

This scope is only used for permissions for restriction creation. By default only dba can create restrictions on any resource. ACL rules creates in this scope allow to grant the right to create restrictions to others.

Returns
The IRI of the restrictions scope: oplres:Restrictions.
See also
Rule Scopes

◆ get_sparql_scope()

VAL.DBA.get_sparql_scope ( )

The IRI of the Private named graphs ACL rule scope.

See also
Rule Scopes
Special SQL Execute Permissions
This procedure can be executed by role VAL_ACL. This means that applications running as a SQL user different from dba can use the API by being granted the VAL_ACL role:
grant VAL_ACL to myuser;

◆ ownership_graph_group()

VAL.DBA.ownership_graph_group ( varchar  scope)

The URI of the graph group used to combine all resource ownership graphs.

Resource ownership is managed in several graphs. Applications can simply register their own ownership graphs via VAL.DBA.add_ownership_graph() for the ACL system to pick up the information within.

This graph group combines all the ownership graphs for one scope, ie. it can be used to query all ownership graphs at once.

◆ remove_ownership_graph()

VAL.DBA.remove_ownership_graph ( varchar  uri,
varchar  scope 
)

Remove a resource ownership graph.

VAL uses the ownership definitions in all ownershop graphs to determine if a user is allowed to create ACL rules for a resource.

This procedure allows to remove a named graph for VAL not to search anymore.

See also
VAL.DBA.add_ownership_graph()

◆ set_resource_ownership()

VAL.DBA.set_resource_ownership ( varchar  scope,
varchar  resource,
varchar  serviceId 
)

Set the owner of a resource in a given scope.

Instead of defining an ownership graph manually and adding it via VAL.DBA.add_ownership_graph() one can simply use VAL.DBA.add_resource_ownership(), VAL.DBA.set_resource_ownership(), and VAL.DBA.remove_resource_ownership() to simplify things and let VAL handle the rest.

Parameters
scopeThe ACL scope for which the ownership should hold.
resourceThe resource which should be defined as being owned by the given service id.
serviceIdThe owner of the given resource.
See also
VAL.DBA.add_ownership_graph()
VAL.DBA.remove_ownership_graph()
VAL.DBA.set_graph_ownership()

◆ sparql_graph_ownership_graph()

VAL.DBA.sparql_graph_ownership_graph ( )

Graph containing the ownership relations for named graphs.

VAL manages the ownership relations for named graphs. It maintains all ownership relations in this graph. Clients should only depend on VAL.DBA.add_graph_ownership(), VAL.DBA.set_graph_ownership(), and VAL.DBA.remove_graph_ownership() to avoid problems with mapping ACLs to Virtuoso's internal graph security system.