Functions
	acl_group_addCondition (varchar serviceId, varchar name, varchar criteria=null, varchar comparator=null, varchar value=null, varchar query=null, varchar property=null, any object=null, varchar realm, varchar ipAddressPattern=null)
	Add a condition to an existing conditional group. More...

	acl_group_list (varchar serviceId, varchar type=null, integer details=0, varchar format, varchar realm)

	acl_group_new (varchar serviceId, varchar name, varchar comment=null, varchar type="static", any members=null, varchar realm)
	Create a new group. More...

	acl_group_remove (varchar serviceId, varchar name, varchar realm)
	Remove an existing group. More...

	acl_group_removeCondition (varchar serviceId, varchar uri, varchar realm)
	Remove a condition from a conditional group. More...

	acl_group_removeConditions (varchar serviceId, varchar name, varchar criteria=null, varchar comparator=null, varchar value=null, varchar query=null, varchar realm)

	acl_group_update (varchar serviceId, varchar name, varchar newName, varchar newComment, any addMembers, any removeMembers, integer overwrite=0, varchar realm)
	Update an existing group. More...

	acl_iri (varchar s)

	acl_rule_get (varchar serviceId, any iris, varchar format, varchar realm)

	acl_rule_list (varchar serviceId, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, varchar realm=null, integer details=0, varchar format=null, varchar scope=null, varchar label=null)

	acl_rule_new (varchar serviceId, varchar subject=null, integer recursive=0, varchar agent=null, varchar agentClass=null, any access, varchar realm, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null)
	Create a new ACL rule. More...

	acl_rule_remove (varchar serviceId, varchar uri, varchar realm)

	acl_rule_update (varchar serviceId, varchar uri, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, integer overwrite=0, varchar realm, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null)

	acls_enabled_for_scope (varchar scope, varchar realm=null, int fallbackValue=0)
	Checks if ACL rule evaluation is enabled for a given scope. More...

	add_default_vdirs ()

	add_graph_ownership (varchar serviceId, varchar graphIri)

	add_ownership_graph (varchar uri, varchar scope)
	Add a resource ownership graph. More...

	add_resource_ownership (varchar scope, varchar resource, varchar serviceId)
	Add a resource ownership relation. More...

	add_same_as_relation (varchar serviceId1, varchar serviceId2)
	Mark two service ids as being the same. More...

	add_sid_to_url (varchar url, varchar service=null, varchar serviceId=null, varchar realm=null, varchar sidParamName="sid", varchar cookieSidName="sid", any options=null, varchar sid=null)

	authentication_details_for_connection (varchar sid, varchar serviceId, varchar uname, int isRealUser, varchar realm=null, varchar sidParamName="sid", any cert=null, varchar webidGraph=null)

	authentication_service_icon_path (varchar service, integer size)

	build_acl_rule_sparql_pattern (varchar usrIri, varchar ruleGraph, varchar subject=null, integer recursive=null, varchar agent=null, varchar agentClass=null, any access=null, varchar realm=null, varchar name=null, varchar comment=null, varchar scope=null, varchar label=null, int readOnly=0)

	build_restriction_sparql_pattern (varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, varchar parameter=null, varchar serviceId=null, varchar label=null)

	check_access_mode_for_resource (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm, varchar mode, varchar scope, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int evalRecursiveRules=0)
	Convinience procedure to check for a specific mode on one resource. More...

	check_acl_group_condition (varchar serviceId, varchar criteria, varchar compPattern, varchar value, varchar query, varchar property, varchar object, varchar maker, any cert=null, varchar webidGraph=null, varchar sameAsGraph=null)

	check_acls_for_named_graph (varchar serviceId, varchar uname=null, varchar ipAddress=null, varchar graphUri, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int includeVirtuosoSecurity=1)
	Check access for a given user and named graph. More...

	check_acls_for_resource (varchar serviceId, varchar ipAddress=null, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null, int honorScopeState=0, int evalRecursiveRules=0)
	Find permissions for resources as set by ACL rules in a certain realm. More...

	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...

	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...

	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...

	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...

	check_conditional_group_membership (varchar groupIri, varchar serviceId, varchar owner, varchar realm, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null)
	Check if a given serviceId is part of a given conditional group. More...

	check_resource_ownership (varchar serviceId, varchar resource, varchar scope, varchar sameAsGraph=null)
	Check the ownership of a resource. More...

	clear_graph_acl_cache (varchar serviceId=null, varchar realm=null, int forced=0)
	Clear the named graph ACL cache for a given service id and realm. More...

	count_acl_rules_for_resource (varchar resource, varchar scope, varchar realm=null)
	Count the number of ACL rules for a given resource. More...

	create_acl_group_condition_uri (varchar serviceId)

	create_acl_group_uri (varchar serviceId)

	create_acl_rule_uri (varchar serviceId)

	create_login_page_url (varchar url, varchar deniedService=null, varchar deniedServiceId=null, varchar realm=null)

	create_restriction_uri ()

	create_val_vhosts (varchar vhost, varchar lhost, integer ssl=0, varchar httpsCert=null, varchar httpsKey=null, int httpsVerify=null, int httpsCvDepth=null)
	Create the necessary virtual hosts for using VAL authentication on the given endpoint. More...

	dav_resource_owner_by_url (varchar url, integer resOwnerId, varchar resOwnerUName, varchar resOwnerName, varchar resOwnerEmail)

	dav_resource_owner_get_service_accounts (integer resOwnerId)

	default_smtp_server ()
	Reads the default smpt server from the Virtuoso configuration. More...

	digest_authentication (varchar uname, varchar nonce, varchar pwdHash)

	email_address_for_service_id (varchar serviceId)
	Find an email address for the given service id. More...

	ensure_control_permissions_on_res (varchar serviceId, varchar resource, any access, varchar realm, varchar scope)

	exec_sparql (varchar query, any params=null, integer useCache=0)

	exec_sparql_with_format (varchar query, varchar format, integer useCache=0)

	exec_sql (varchar query, any params=null, int useCache=1)

	extract_acl_group_conditions_from_blob (varchar ruleData, varchar format)

	extract_acl_groups_from_blob (varchar groupData, varchar format)

	extract_acl_rules_from_blob (varchar ruleData, varchar format)

	extract_restrictions_from_blob (varchar restData, varchar format)

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

	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_acl_permissions_ip_address (varchar ipAddress, varchar resource=null, varchar realm, varchar mode=null, varchar scope=null, int evalRecursiveRules=0)

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

	find_group_by_name_or_iri (varchar serviceId, varchar name, varchar realm)

	find_group_condition_by_iri (varchar serviceId, varchar uri, varchar realm)

	find_oauth_session_for_service (varchar serviceId, varchar service, varchar requiredScope=null)

	find_restriction_by_iri (varchar serviceId, varchar uri, varchar realm)

	find_restrictions (varchar serviceId=null, varchar ipAddress=null, varchar resource, varchar realm, varchar webidGraph=null, any certificate=null, decimal minValue, decimal maxValue, varchar parameter=null, varchar sameAsGraph=null)
	Find the restriction values for a given resource. More...

	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...

	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...

	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...

	find_restrictions_max (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar parameter=null, varchar sameAsGraph=null)
	Get the maximum restriction value for a given resource. More...

	find_restrictions_min (varchar serviceId, varchar ipAddress=null, varchar resource, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar parameter=null, varchar sameAsGraph=null)
	Get the minimum restriction value for a given resource. More...

	find_restrictions_public (varchar resource, varchar realm, decimal minValue, decimal maxValue, varchar parameter=null)
	Find the restriction values from public rules. More...

	find_rule_by_iri (varchar serviceId, varchar uri, varchar realm)

	foaf_iri (varchar s)

	get_accept_mime_type (varchar format=null)

	get_acl_schema_graph ()
	The VAL ACL Schema graph IRI. More...

	get_applicable_access_for_scope (varchar scope)
	Get the list of applicable access modes for a given scope. More...

	get_authentication_details_for_connection (varchar sid, varchar serviceId, varchar uname, int isRealUser, varchar realm=null, varchar sidParamName="sid", any cert, varchar webidGraph=null)
	Checks for existing authentication information in the current connection. More...

	get_connection_realm (varchar fallback=null)
	Get the realm for the current http connection. More...

	get_content_mime_type ()

	get_dav_scope ()
	The IRI of the DAV ACL rule scope. More...

	get_default_access_for_scope (varchar scope)
	Get the list of default access modes for a given scope. More...

	get_default_realm ()
	The default application realm. More...

	get_owned_graphs (varchar serviceId)
	Get the graphs owned by a given service id. More...

	get_ownership_graph_uri (varchar scope)

	get_profile_graph_uri (varchar serviceId)
	The graph URI for a given service id. More...

	get_profile_name (varchar serviceId)
	Get the full name for the given profile URI. More...

	get_profile_url (varchar serviceId, varchar service=null)
	Get a profile URL for a given service ID. More...

	get_query_scope ()
	The IRI of the Query ACL rule scope. More...

	get_realm_config_value (varchar realm, varchar property)
	Convinience procedure to get a config value from the given realm. More...

	get_resource_owner (varchar resource, varchar scope)
	Get the owner of a resource. More...

	get_restrictions_scope ()
	The IRI of the Restrictions ACL rule scope. More...

	get_service_client_key (varchar service, any clientId)
	Get the key and secret for the given service API. More...

	get_sparql_html_footer (varchar pageUrl)

	get_sparql_permissions (varchar serviceId, varchar uname=null, varchar ipAddress=null, varchar realm=null, varchar webidGraph=null, any certificate=null, varchar sameAsGraph=null)
	Check the generic SPARQL permissions for the given authentication information. More...

	get_sparql_permissions_for_sql_user (varchar uname)

	get_sparql_scope ()
	The IRI of the Private named graphs ACL rule scope. More...

	http_to_https_uri (varchar uri, int checkForVhost=0)
	Convert an HTTP URI into its HTTPS counterpart. More...

	is_admin_user (varchar uname)
	Check if a given SQL user is `dba` or in the admin group (role) More...

	load_triples_into_tmp_graph (varchar data, varchar format)

	logout (varchar sid=null, varchar sidParamName="sid")
	Clear authentication information. More...

	new_user_session (varchar uname, varchar realm=null, int checkDeactivated=0, any options=null)

	normalize_dav_path (varchar url)
	Normalizes the path in a DAV url. More...

	normalize_host (varchar vhost, varchar lhost)

	normalize_vhost_and_lhost (varchar vhost, varchar lhost)

	oauth_refresh_token (varchar service=null, varchar serviceId=null, int force=0, varchar oauthSid=null, varchar scope=null)
	Refresh an OAuth access token based on service type and service id. More...

	oplacl_iri (varchar s)

	oplres_iri (varchar s)

	ownership_graph_group (varchar scope)
	The URI of the graph group used to combine all resource ownership graphs. More...

	prepare_sql_params (varchar _sql, any _sqlParams, any _params)

	rdfs_iri (varchar s)

	remove_graph_ownership (varchar serviceId, varchar graphIri)

	remove_ownership_graph (varchar uri, varchar scope)
	Remove a resource ownership graph. More...

	remove_resource_ownership (varchar scope, varchar resource, varchar serviceId)

	remove_user_online_mapping (varchar service, varchar serviceId)

	request_login_nonce ()

	restriction_delete (varchar uri, varchar realm=null, varchar serviceId=null)
	Delete a restriction. More...

	restriction_get (any iris, varchar format, varchar realm, varchar serviceId=null)
	Get the details one or more restrictions. More...

	restriction_list (varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, integer details=0, varchar format=null, varchar parameter=null, varchar serviceId=null, varchar label=null)
	List restrictions defined in a realm. More...

	restriction_new (varchar name=null, varchar comment=null, varchar resource, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm=null, varchar parameter=null, varchar serviceId=null, varchar label=null)
	Create a new ACL restriction. More...

	restriction_update (varchar uri, varchar name=null, varchar comment=null, varchar resource=null, varchar agent=null, varchar agentClass=null, decimal minValue=null, decimal maxValue=null, varchar realm, varchar parameter=null, varchar serviceId=null, varchar label=null)
	Update properties of an existing restriction. More...

	send_notification_email (varchar recipient, varchar subject, varchar text)
	Send a notification email to some email address from the system. More...

	service_from_profile_uri (varchar url)
	Extract service name from online account URI. More...

	service_id_to_sql_user (varchar serviceId)
	Try to find a connected SQL account for a given serviceId. More...

	session_id_for_connection (varchar sid, varchar serviceId, varchar realm=null, varchar sidParamName="sid")

	set_graph_context_query (varchar serviceId, varchar realm=null, any certificate=null, varchar webidGraph=null)
	Set the required connection settings for the read-only graph security system. More...

	set_graph_ownership (varchar serviceId, varchar graphIri)

	set_keyword (varchar name, any params, any value)

	set_resource_ownership (varchar scope, varchar resource, varchar serviceId)
	Set the owner of a resource in a given scope. More...

	setup_val_host (varchar httpVHost, varchar httpLHost, varchar httpsVHost, varchar httpsLHost, varchar httpsCert, varchar httpsKey)
	Setup a VAL host. More...

	smtp_server_available ()
	Check if a valid SMTP server has been configured. More...

	sparql_access_modes_to_bitmask (any modes)

	sparql_graph_ownership_graph ()
	Graph containing the ownership relations for named graphs. More...

	thirdparty_authentication_default_callback (varchar url, any opts, varchar service, varchar serviceId, any profile, any oauthInfo, varchar oauthSid)
	Default callback procedure for VAL.DBA.thirdparty_authentication_url. More...

	thirdparty_authentication_default_error_callback (varchar url, any opts, varchar service, any _sqlState, any _sqlMessage)

	thirdparty_authentication_url (varchar service, varchar data, varchar callback, varchar successProc=null, varchar errorProc=null, any params=null, varchar scope="basic", varchar clientIp=null, varchar realm=null)
	Create an authentication URL for any supported 3rd-party service. More...

	thirdparty_callback (varchar state)

	thirdparty_service_labels ()
	A simple map of all supported third-party authentication services and their labels. More...

	thirdparty_services ()
	A simple map of all supported third-party authentication services, their labels, and oauth apikey urls. More...

	thirdparty_supported_services ()
	A simple map of all the supported authentication services that can be used in thirdparty_authentication_url. More...

	update_graph_acl_cache (varchar serviceId, varchar realm=null, any certificate=null, varchar webidGraph=null, int forced=0)
	Update the named graph ACL cache VAL.DBA.VAL_GRAPH_ACL_CACHE. More...

	update_user_online_mapping (varchar service=null, varchar serviceId, varchar oauthSid=null, any uname)

	user_personal_uri (varchar uname)
	An SQL user's personal URI. More...

	username_for_online_account (varchar service=null, varchar serviceId, any cert=null, varchar webidGraph=null, varchar realm=null)

	val_acl_group_graph (varchar realm, int createGraph=0)

	val_acl_rule_graph (varchar realm, int createGraph=0)

	val_config_graph_uri ()

	val_get_certificate_info (int detail, any cert)

	val_restrictions_graph (varchar realm=null, int createGraph=0)

	vector_intersect (any v1, any v2)

	vector_merge (any v1, any v2)

Function Documentation

◆ acl_iri()

VAL.DBA.acl_iri ( varchar s )

Create a ACL URI. The procedure simply appends the given s to the acl namespace.

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;

◆ add_default_vdirs()

VAL.DBA.add_default_vdirs ( )

Configure the default VAL vhosts

◆ add_graph_ownership()

VAL.DBA.add_graph_ownership	(	varchar	serviceId,
		varchar	graphIri
	)

◆ add_same_as_relation()

VAL.DBA.add_same_as_relation	(	varchar	serviceId1,
		varchar	serviceId2
	)

Mark two service ids as being the same.

VAL supports owl:sameAs relations for ACL rules and the like. This procedure allows to mark two service ids as being "the same". An owl:sameAs relation will be added to VAL's sameAs graph and optionally an entry will be added to VAL_USER_ONLINE_ACCOUNTS if applicable.

Caution: only ever call this procedure if you are certain that the two accounts are the same. This is typically the case if the user authenticated with one service while working with a session connected to the other.

See also: VAL.DBA.val_owl_sameas_graph()

◆ authentication_details_for_connection()

VAL.DBA.authentication_details_for_connection	(	varchar	sid,
		varchar	serviceId,
		varchar	uname,
		int	isRealUser,
		varchar	realm = `null`,
		varchar	sidParamName = `"sid"`,
		any	cert = `null`,
		varchar	webidGraph = `null`
	)

Deprecated:: Use VAL.DBA.get_authentication_details_for_connection() instead.

◆ authentication_service_icon_path()

VAL.DBA.authentication_service_icon_path	(	varchar	service,
		integer	size
	)

Creates the path to an image that can be used to create a login button for the given service type. It uses the images provided by VAL.

Example:

If service type facebook and size \ 24 are given the following path is returned:

/val/img/social24/facebook.png

If no specific images does exist either ods.png or unknown.png are used, depending on whether the given service is an ODS instance added via ODS' admin.oauth.odshosts.new() API or not.

◆ build_acl_rule_sparql_pattern()

VAL.DBA.build_acl_rule_sparql_pattern	(	varchar	usrIri,
		varchar	ruleGraph,
		varchar	subject = `null`,
		integer	recursive = `null`,
		varchar	agent = `null`,
		varchar	agentClass = `null`,
		any	access = `null`,
		varchar	realm = `null`,
		varchar	name = `null`,
		varchar	comment = `null`,
		varchar	scope = `null`,
		varchar	label = `null`,
		int	readOnly = `0`
	)

This is an internal helper function to avoid code duplication in acl.rule.*

It creates a SPARQL pattern which selects the ACL rules as indicated by the paramters.

Also it improves input parameters by replacing empty strings with null values for easier processing.

◆ build_restriction_sparql_pattern()

VAL.DBA.build_restriction_sparql_pattern	(	varchar	name = `null`,
		varchar	comment = `null`,
		varchar	resource = `null`,
		varchar	agent = `null`,
		varchar	agentClass = `null`,
		decimal	minValue = `null`,
		decimal	maxValue = `null`,
		varchar	realm,
		varchar	parameter = `null`,
		varchar	serviceId = `null`,
		varchar	label = `null`
	)

Build a SPARQL pattern to query or insert restrictions.

This procedure is used internally by the ACL restrictions system and should normally never be called in another context.

◆ check_acl_group_condition()

VAL.DBA.check_acl_group_condition	(	varchar	serviceId,
		varchar	criteria,
		varchar	compPattern,
		varchar	value,
		varchar	query,
		varchar	property,
		varchar	object,
		varchar	maker,
		any	cert = `null`,
		varchar	webidGraph = `null`,
		varchar	sameAsGraph = `null`
	)

Check an ACL group condition.

Internal procedure used by VAL.DBA.find_acl_permissions_conditional().

◆ check_conditional_group_membership()

VAL.DBA.check_conditional_group_membership	(	varchar	groupIri,
		varchar	serviceId,
		varchar	owner,
		varchar	realm,
		varchar	webidGraph = `null`,
		any	certificate = `null`,
		varchar	sameAsGraph = `null`
	)

Check if a given serviceId is part of a given conditional group.

Parameters

groupIri	The IRI of the conditional group.
serviceId	The IRI of the person to check for group membership.
owner	The owner of the rule for which this test is relevant. This is used in check_acl_group_condition to set the graph permissions, only graph readable by the rule owner are used for evaluation of conditions.
realm	The application realm.
webidGraph	The graph in which the WebID profile is cached.
certificate	The client certificate in case of WebID authentication.
sameAsGraph	This 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.

Returns: 1 if serviceId is part of group groupIri, 0 otherwise.

◆ clear_graph_acl_cache()

VAL.DBA.clear_graph_acl_cache	(	varchar	serviceId = `null`,
		varchar	realm = `null`,
		int	forced = `0`
	)

Clear the named graph ACL cache for a given service id and realm.

Parameters

serviceId	The service id (personal uri) of the grantee to clear the cache for. If `null` then the cache will be cleared for all service ids.
realm	The realm in which to clear the cache. Falls back to the default realm oplacl:DefaultRealm.

◆ create_acl_group_condition_uri()

VAL.DBA.create_acl_group_condition_uri ( varchar serviceId )

Internal helper procedure. Do not use outside of VAL!

◆ create_acl_group_uri()

VAL.DBA.create_acl_group_uri ( varchar serviceId )

Internal helper procedure. Do not use outside of VAL!

◆ create_acl_rule_uri()

VAL.DBA.create_acl_rule_uri ( varchar serviceId )

Internal helper procedure. Do not use outside of VAL!

◆ create_restriction_uri()

VAL.DBA.create_restriction_uri ( )

Internal helper procedure. Do not use outside of VAL!

◆ create_val_vhosts()

VAL.DBA.create_val_vhosts	(	varchar	vhost,
		varchar	lhost,
		integer	ssl = `0`,
		varchar	httpsCert = `null`,
		varchar	httpsKey = `null`,
		int	httpsVerify = `null`,
		int	httpsCvDepth = `null`
	)

Create the necessary virtual hosts for using VAL authentication on the given endpoint.

This procedure will setup the required vhosts for /val and /val/api. The former is used to expose the VAL images and the 40x_page for /DAV. The latter only hosts the thirdparty_callback() function which is required for OAuth and OpenID authentication. In the case of an SSL vhost client certificates will be disabled on the host.

A typical configuration would be as follows:

VAL.DBA.create_val_vhosts ('mysite.com:443', 'mysite.com:443', 1, 'db:https_key_mysite_com', 'db:https_key_mysite_com');

Parameters

vhost	The virtual host name that the browser presents as Host: entry in the request headers. i.e. Name-based virtual hosting. The default value is taken from the Virtuoso INI file.
lhost	The address of the network interface the Virtuoso HTTP server uses to listen and accept connections. The default value is taken from the Virtuoso INI file.
ssl	`1` if the host to configure is SSL-secured. If this is set to `null` then the values are determined automatically based on the the first vdir found for the listener.
httpsCert	The name of the https certificate to use for the SSL endpoint. If this is set to `null` then the value is determined automatically based on the the first vdir found for the listener.
httpsKey	The name of the https key to use for the SSL endpoint. Often the same as `httpsCert`. If this is set to `null` then the value is determined automatically based on the the first vdir found for the listener.
httpsVerify	The `https_verify` value for the SSL listener. If this is set to `null` then the value is determined automatically based on the the first vdir found for the listener.
httpsCvDepth	The `https_cv_depth` value for the SSL listener. If this is set to `null` then the value is determined automatically based on the the first vdir found for the listener.

Typically this procedure is not called directly but via VAL.DBA.setup_val_host().

◆ dav_resource_owner_by_url()

VAL.DBA.dav_resource_owner_by_url	(	varchar	url,
		integer	resOwnerId,
		varchar	resOwnerUName,
		varchar	resOwnerName,
		varchar	resOwnerEmail
	)

Determine the owner of any DAV resource by URL.

Returns: 1 on success, 0 if the resource could not be found.

Deprecated:: Use VAL.DBA.get_resource_owner() instead.

◆ dav_resource_owner_get_service_accounts()

VAL.DBA.dav_resource_owner_get_service_accounts ( integer resOwnerId )

Get the owner's service accounts which have a profile url

param resOwnerId The ID of the account

Returns: vector of vectors with NAME, URL

◆ ensure_control_permissions_on_res()

VAL.DBA.ensure_control_permissions_on_res	(	varchar	serviceId,
		varchar	resource,
		any	access,
		varchar	realm,
		varchar	scope
	)

Checks if the given serviceId owns a given resource or has permission to grant the given access rights to anyone. Throws a signal if not.

Internal procedure. Do not use outside of VAL.

◆ exec_sparql()

VAL.DBA.exec_sparql	(	varchar	query,
		any	params = `null`,
		integer	useCache = `0`
	)

Execute a sparql query via exec() and thow the signal in case of an error.

◆ exec_sparql_with_format()

VAL.DBA.exec_sparql_with_format	(	varchar	query,
		varchar	format,
		integer	useCache = `0`
	)

Execute a describe or construct query, using the given result format.

Throws a signal on error.

◆ exec_sql()

VAL.DBA.exec_sql	(	varchar	query,
		any	params = `null`,
		int	useCache = `1`
	)

Execute a SQL query via exec() and thow the signal in case of an error.

◆ extract_acl_group_conditions_from_blob()

VAL.DBA.extract_acl_group_conditions_from_blob	(	varchar	ruleData,
		varchar	format
	)

Reads the given ruleData and extract all the ACL group conditions given within.

Returns: A vector of vectors, each containing a condition where each condition contains: query or criteria, comparator, and value

◆ extract_acl_groups_from_blob()

VAL.DBA.extract_acl_groups_from_blob	(	varchar	groupData,
		varchar	format
	)

Reads the given ruleData and extract all the ACL groups given within.

Returns: A vector of vectors, each containing name, comment, type (oplacl:ConditionalGroup or null), vector or members, vector of conditions where each condition contains: type, query or criteria or ip pattern, comparator, and value

◆ extract_acl_rules_from_blob()

VAL.DBA.extract_acl_rules_from_blob	(	varchar	ruleData,
		varchar	format
	)

Reads the given ruleData and extract all the ACL rules given within.

Returns

A vector of vectors, each containing

subject
recursive (0 or 1)
agent
agentClass
access vector (containing uris like oplacl:Read or oplacl:GrantWrite)
name
comment
scope

◆ extract_restrictions_from_blob()

VAL.DBA.extract_restrictions_from_blob	(	varchar	restData,
		varchar	format
	)

Extract a set of restriction objects from a blob of data.

Returns

A vector of vectors, each representing one restriction consisting of:

name
comment
resource
agent
agent class
min value
max value
restricted parameter
label

◆ find_group_by_name_or_iri()

VAL.DBA.find_group_by_name_or_iri	(	varchar	serviceId,
		varchar	name,
		varchar	realm
	)

This is a helper function which only exists to avoid code duplication in acl.group.*

It finds a group in a given named graph by name or IRI. If the group is not found an error is signaled.

◆ find_group_condition_by_iri()

VAL.DBA.find_group_condition_by_iri	(	varchar	serviceId,
		varchar	uri,
		varchar	realm
	)

This is a helper function which only exists to avoid code duplication in acl.group.*

It finds a group condition by IRI. If the group is not found an error is signaled.

Returns: the uri of the group the condition belongs to.

◆ find_oauth_session_for_service()

VAL.DBA.find_oauth_session_for_service	(	varchar	serviceId,
		varchar	service,
		varchar	requiredScope = `null`
	)

Get an OAuth session id (OAUTH..CLI_SESSIONS:CS_SID) for the given serviceId and the given service and scope. The service can be any of the VAL-supported OAuth services.

The serviceId doe not have to be for the given service, as long as a owl:sameAs relation exists.

Parameters

serviceId	The authenticated person in need of an OAuth session for service `service`.
service	The service for which an OAUth session is required.
requiredScope	The scope of the required OAuth session. If `null` any session can be used.

Returns: The OAuth session ID or null if no session matching the request could be found.

◆ find_restriction_by_iri()

VAL.DBA.find_restriction_by_iri	(	varchar	serviceId,
		varchar	uri,
		varchar	realm
	)

Check if a given restriction exists. If serviceId is given and is not the personal uri of dba, then the foaf:maker of the restriction is also checked.

Throws a signal in case the restriction is not found.

◆ find_rule_by_iri()

VAL.DBA.find_rule_by_iri	(	varchar	serviceId,
		varchar	uri,
		varchar	realm
	)

This is a helper function which only exists to avoid code duplication in acl_rule*

It finds a rule for a given service uri and IRI. If the rule is not found an error is signaled.

◆ foaf_iri()

VAL.DBA.foaf_iri ( varchar s )

Create a foaf URI. The procedure simply appends the given s to the foaf namespace.

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_accept_mime_type()

VAL.DBA.get_accept_mime_type ( varchar format = null )

Get the mime type requested by the client from the request headers. Falling back to turtle and allowing to override with a parameter.

◆ get_content_mime_type()

VAL.DBA.get_content_mime_type ( )

Get the mime type of the content provided by the client from the request headers.

◆ get_ownership_graph_uri()

VAL.DBA.get_ownership_graph_uri ( varchar scope )

Internal procedure which returns the URI of the graph used to store ownership relations maintained by VAL itself via VAL.DBA.set_resource_ownership() and friends.

◆ get_profile_graph_uri()

VAL.DBA.get_profile_graph_uri ( varchar serviceId )

The graph URI for a given service id.

VAL does store certain profile details for all users that authenticated at some point via VAL. These details are stored in a private graph which only the person in question has read access to (see also VAL.DBA.store_profile_details()).

Since the Sponger already uses the service id itself as graph URI we use our own internal graph based on the service id and a urn prefix.

Returns: The profile graph URI or null if serviceId is null or empty.

◆ get_realm_config_value()

VAL.DBA.get_realm_config_value	(	varchar	realm,
		varchar	property
	)

Convinience procedure to get a config value from the given realm.

VAL typically stores configuration by application realm. This means that most configuration settings are tied to the realm URI within the private configuration graph (VAL.DBA.val_config_graph_uri()).

This procedure simply returns the configured value for the given property or null if there is none.

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

◆ get_service_client_key()

VAL.DBA.get_service_client_key	(	varchar	service,
		any	clientId
	)

Get the key and secret for the given service API.

This procedure reads client id and secret from OAUTH.DBA.APP_REG.

Parameters

service	The name of the service.
clientId[out]	A vector containing the client ID and secret on success.

Returns: On success 1 is returned, 0 otherwise.

◆ get_sparql_html_footer()

VAL.DBA.get_sparql_html_footer ( varchar pageUrl )

Reads the HTML footer configured for the given web page and returns its contents or null if none was configured.

◆ get_sparql_permissions_for_sql_user()

VAL.DBA.get_sparql_permissions_for_sql_user ( varchar uname )

Find the SPARQL permissions for a given user. This refers to the system permissions which are defined by the three roles SPARQL_SELECT, SPARQL_SPONGE, and SPARQL_UPDATE.

Returns

A bitmask as follow:

1 for Read
2 for Write (returns 7 as write includes read and sponge)
4 for Sponge (returns 5 as sponge includes read)

◆ load_triples_into_tmp_graph()

VAL.DBA.load_triples_into_tmp_graph	(	varchar	data,
		varchar	format
	)

Load the triples in data into a tmp graph and return the graph IRI.

◆ normalize_dav_path()

VAL.DBA.normalize_dav_path ( varchar url )

Normalizes the path in a DAV url.

Virtuoso allows to create different virtual dirs which point to different locations in the DAV system. This procedure allows to determine the actual DAV path (/DAV/...) of the resource in question.

Supported are both http(s) URLs and the special dav:/ urls which are used to create access-protocol-independant ACL rules on dav resources.

Example:

Given a virtual dir /test which points to /DAV/test/foo the following values for url would all return the same path:

http://HOST/test/bar.txt
http://HOST/DAV/test/foo/bar.txt
dav:/DAV/test/foo/bar.txt All three would result in the normalized path /DAV/test/foo/bar.txt which can be used for internal DAV operations.

Returns: The normalized path of the DAV resource to which url refers, or, if the given url could not be mapped to any virtual dir, the path from the url is returned.

◆ normalize_host()

VAL.DBA.normalize_host	(	varchar	vhost,
		varchar	lhost
	)

Normalizes a vhost value in the same way VHOST_DEFINE does but also replaces ini and sslini with default values from the config.

Returns: The VD in the form HOST:PORT.

◆ normalize_vhost_and_lhost()

VAL.DBA.normalize_vhost_and_lhost	(	varchar	vhost,
		varchar	lhost
	)

Normalizes vhost and lhost values the same way VHOST_DEFINE does. Running vhost and lhost values through this procedure will allow a lookup in HTTP_PATH.

◆ oplacl_iri()

VAL.DBA.oplacl_iri ( varchar s )

Create an OPLACL URI. The procedure simply appends the given s to the oplacl namespace.

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;

◆ oplres_iri()

VAL.DBA.oplres_iri ( varchar s )

Create an OPLRES URI. The procedure simply appends the given s to the oplres namespace.

◆ prepare_sql_params()

VAL.DBA.prepare_sql_params	(	varchar	_sql,
		any	_sqlParams,
		any	_params
	)

◆ rdfs_iri()

VAL.DBA.rdfs_iri ( varchar s )

Create a RDFS URI. The procedure simply appends the given s to the RDFS namespace.

◆ remove_graph_ownership()

VAL.DBA.remove_graph_ownership	(	varchar	serviceId,
		varchar	graphIri
	)

◆ remove_resource_ownership()

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

◆ send_notification_email()

VAL.DBA.send_notification_email	(	varchar	recipient,
		varchar	subject,
		varchar	text
	)

Send a notification email to some email address from the system.

The email will be sent from an address that can be supplied in the vad config page. However, if one is not supplied the it will use "noreply@HOST" where HOST matches the value of http_host() stripped of the port.

This proc will signal an error if email sending fails.

Parameters

recipient	The email address to send to, like foo@b.nosp@m.ar.c.nosp@m.om
subject	The subject of the email.
text	The contents of the email.

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

◆ service_id_to_sql_user()

VAL.DBA.service_id_to_sql_user ( varchar serviceId )

Try to find a connected SQL account for a given serviceId.

Returns: The name of the SQL account or null if none was found.

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

◆ set_graph_context_query()

VAL.DBA.set_graph_context_query	(	varchar	serviceId,
		varchar	realm = `null`,
		any	certificate = `null`,
		varchar	webidGraph = `null`
	)

Set the required connection settings for the read-only graph security system.

Virtuoso has a secondary graph security system which improves the performance for read-only queries considerably as compared to the graph security callback system (see also DB.DBA.SPARQL_GS_APP_CALLBACK_VAL_SPARQL_PERMS()). The idea is that one query returns the list of graphs a person has access to. This list is then cached and reused on the next query, even between connections.

Warning: Since conditional groups can be arbitrary and VAL has no way of knowing when the membership changes, it is up to the application or the administrator to invalidate the cache whenever ACLs change.

◆ set_graph_ownership()

VAL.DBA.set_graph_ownership	(	varchar	serviceId,
		varchar	graphIri
	)

◆ set_keyword()

VAL.DBA.set_keyword	(	varchar	name,
		any	params,
		any	value
	)

◆ setup_val_host()

VAL.DBA.setup_val_host	(	varchar	httpVHost,
		varchar	httpLHost,
		varchar	httpsVHost,
		varchar	httpsLHost,
		varchar	httpsCert,
		varchar	httpsKey
	)

Setup a VAL host.

This procedure is used to setup an SSL-protected VAL installation. For this to work properly VAL needs to be able to map an http vhost to its https counterpart.

Without this setup WebID and OAuth services that require an https callback (like Box.com) will not work.

Example:

VAL.DBA.setup_val_host('*ini*', '*ini*', 'web.ods.openlinksw.com', ':443', 'db:https_key_web_ods', 'db:https_key_web_ods');

◆ sparql_access_modes_to_bitmask()

VAL.DBA.sparql_access_modes_to_bitmask ( any modes )

Create a bitmask from a vector of mode uris.

1 for Read
2 for Write (returns 7 as write includes read and sponge)
4 for Sponge (returns 5 as sponge includes read)

◆ thirdparty_authentication_default_callback()

VAL.DBA.thirdparty_authentication_default_callback	(	varchar	url,
		any	opts,
		varchar	service,
		varchar	serviceId,
		any	profile,
		any	oauthInfo,
		varchar	oauthSid
	)

Default callback procedure for VAL.DBA.thirdparty_authentication_url.

This callback procedure will create a session id and return the original url after setting a sid cookie. The session id can be mapped to the serviceId by querying VSPX_SESSION.

◆ thirdparty_authentication_default_error_callback()

VAL.DBA.thirdparty_authentication_default_error_callback	(	varchar	url,
		any	opts,
		varchar	service,
		any	_sqlState,
		any	_sqlMessage
	)

◆ thirdparty_callback()

VAL.DBA.thirdparty_callback ( varchar state )

Generic OAuth and OpenID callback. This procedure is exported as a public SOAP/HTTP call. It handles the results from the 3rd-party services and then continues on with the callback procedure as provided to VAL.DBA.thirdparty_authentication_url().

◆ thirdparty_service_labels()

VAL.DBA.thirdparty_service_labels ( )

A simple map of all supported third-party authentication services and their labels.

Deprecated:: Please use VAL.DBA.thirdparty_services() instead.

◆ update_graph_acl_cache()

VAL.DBA.update_graph_acl_cache	(	varchar	serviceId,
		varchar	realm = `null`,
		any	certificate = `null`,
		varchar	webidGraph = `null`,
		int	forced = `0`
	)

Update the named graph ACL cache VAL.DBA.VAL_GRAPH_ACL_CACHE.

◆ val_acl_group_graph()

VAL.DBA.val_acl_group_graph	(	varchar	realm,
		int	createGraph = `0`
	)

Get the graph the groups are stored in for the given user.

Parameters

realm	The application realm for which groups should be stored.
serviceId	The service id of the user or `null` for querying all groups.

◆ val_acl_rule_graph()

VAL.DBA.val_acl_rule_graph	(	varchar	realm,
		int	createGraph = `0`
	)

Get the graph the acl rules are stored in for the given user.

Parameters

realm	The application realm for which rules should be stored.
serviceId	The service id of the user or `null` for querying all rules.

◆ val_config_graph_uri()

VAL.DBA.val_config_graph_uri ( )

The graph which contains the VAL configuration.

◆ val_get_certificate_info()

VAL.DBA.val_get_certificate_info	(	int	detail,
		any	cert
	)

A simple replacement for get_certificate_info which will return null if the given cert is null.

◆ val_restrictions_graph()

VAL.DBA.val_restrictions_graph	(	varchar	realm = `null`,
		int	createGraph = `0`
	)

Get the graph the restrictions are stored in.

Parameters

realm The application realm for which restrictions should be stored. Leave null for system restrictions.

◆ vector_intersect()

VAL.DBA.vector_intersect	(	any	v1,
		any	v2
	)

Create the intersection of two vectors.

◆ vector_merge()

VAL.DBA.vector_merge	(	any	v1,
		any	v2
	)

Merge v2 into v1, eliminating duplicates.

Functions

Function Documentation

◆ acl_iri()

◆ add_default_vdirs()

◆ add_graph_ownership()

◆ add_same_as_relation()

◆ authentication_details_for_connection()

◆ authentication_service_icon_path()

◆ build_acl_rule_sparql_pattern()

◆ build_restriction_sparql_pattern()

◆ check_acl_group_condition()

◆ check_conditional_group_membership()

◆ clear_graph_acl_cache()

◆ create_acl_group_condition_uri()

◆ create_acl_group_uri()

◆ create_acl_rule_uri()

◆ create_restriction_uri()

◆ create_val_vhosts()

◆ dav_resource_owner_by_url()

◆ dav_resource_owner_get_service_accounts()

◆ ensure_control_permissions_on_res()

◆ exec_sparql()

◆ exec_sparql_with_format()

◆ exec_sql()

◆ extract_acl_group_conditions_from_blob()

◆ extract_acl_groups_from_blob()

◆ extract_acl_rules_from_blob()

◆ extract_restrictions_from_blob()

◆ find_group_by_name_or_iri()

◆ find_group_condition_by_iri()

◆ find_oauth_session_for_service()

◆ find_restriction_by_iri()

◆ find_rule_by_iri()

◆ foaf_iri()

◆ get_accept_mime_type()

◆ get_content_mime_type()

◆ get_ownership_graph_uri()

◆ get_profile_graph_uri()

◆ get_realm_config_value()

◆ get_service_client_key()

◆ get_sparql_html_footer()

◆ get_sparql_permissions_for_sql_user()

◆ load_triples_into_tmp_graph()

◆ normalize_dav_path()

◆ normalize_host()

◆ normalize_vhost_and_lhost()

◆ oplacl_iri()

◆ oplres_iri()

◆ prepare_sql_params()

◆ rdfs_iri()

◆ remove_graph_ownership()

◆ remove_resource_ownership()

◆ send_notification_email()

◆ service_id_to_sql_user()

◆ set_graph_context_query()

◆ set_graph_ownership()

◆ set_keyword()

◆ setup_val_host()

◆ sparql_access_modes_to_bitmask()

◆ thirdparty_authentication_default_callback()

◆ thirdparty_authentication_default_error_callback()

◆ thirdparty_callback()

◆ thirdparty_service_labels()

◆ update_graph_acl_cache()

◆ val_acl_group_graph()

◆ val_acl_rule_graph()

◆ val_config_graph_uri()

◆ val_get_certificate_info()

◆ val_restrictions_graph()

◆ vector_intersect()

◆ vector_merge()