ALTER TRUSTED CONTEXT statement

Use the ALTER TRUSTED CONTEXT statement to modify the current options and attributes (including the ENABLED or DISABLED mode) of a trusted-context object.

This statement is an extension to the ANSI/ISO standard for the SQL language.

Syntax

Authorized User Clause

Notes:

¹ Use this path no more than once


Element	Description	Restrictions	Syntax
address	Communication address of the client connection to the database server	Must be unique among communication addresses of clients for this trusted-context object. For additional address restrictions, see ADDRESS attributes below.	Quoted String
context	Name of the trusted-context object	Must exist among trusted contexts of the database server instance, and cannot begin with the characters `SYS`	Identifier
role	An existing user-defined or built-in role	Must exist in the database, and must be unique among attributes of this trusted-context object	Owner name
user	Authorization identifier of a user	Must be a valid authorization identifier. Cannot be longer than 32 bytes. Must not be the authorization ID of the user who issues this statement. The REPLACE USE FOR clause must not specify this user more than once.	Owner name

Usage

You must hold the database security administrator (DBSECADM) role to run this statement. If the statement is embedded in an application program, the privileges are those of the owner. If the statement is run in a trusted context with a role, the set of privileges is the union of these discretionary access privileges:

the set of privileges held by the role that is associated with the primary authorization ID,
and the set of privileges held by each role that the statement references.

When the ALTER TRUSTED CONTEXT statement executes successfully, any changes to the trusted-context object, its attributes, and its list of authorized users are registered in these tables in the sysuser database of the HCL OneDB™ database server instance:

systrustedcontext
systcxattributes
systcxusers.

ADDRESS attributes

The ALTER ATTRIBUTES, ADD ATTRIBUTES, and DROP ATTRIBUTES options can specify lists of one or more communication addresses for connections to the database server, whose status as connection trust attributes, on which the trusted-context object is defined, are to be modified. The following restrictions apply to communication addresses that the ALTER TRUSTED CONTEXT or the CREATE TRUSTED CONTEXT statements reference:

Each must be unique among communication addresses of clients for this trusted-context object.
Each must conform to the TCP/IP protocol.
Each must be an IPv4 address, an IPv6 address, or a secure domain name.
An IPv4 address or IPv6 address must be a real host address (not a local host), and must not contain leading blank spaces.
An IPv6 address, in addition, must not be an IPv4-mapped IPv6 address.
A secure domain name must not be a Dynamic Host Configuration Protocol (DHCP) address.

If a new address value is the name of a secure domain, that name is converted to an IP address by the domain-name server, where a resulting IPv4 or IPv6 address is determined. When a domain name is converted to an IP address, the result of this conversion might be a set of one or more IP addresses. In this case, the database server interprets a subsequent incoming connection request as matching the ADDRESS attribute of a trusted-context object if the IP address from which the connection originates matches any of the IP addresses to which the domain name was converted.

The ALTER ATTRIBUTES clause replaces existing values for specified attributes with the new values. If an attribute is not currently part of the trusted-context object definition, an error is returned. Attributes that are not specified retain their previous values.

Specified ADDRESS values for the trusted-context object are removed by the ALTER ATTRIBUTESclause and by the DROP ATTRIBUTES clause. The ADDRESS attribute can be specified multiple times, but each address value must be unique for the set of attributes.

The ADD ATTRIBUTES clause specifies a list of one or more new trust attributes on which the trusted-context object is defined.

The DROP ATTRIBUTES clause specifies that one or more attributes are to be dropped from the definition of the trusted-context object. If the attribute is not currently part of the trusted-context object definition, an error is returned.

Attention:

If you have an existing application with an ALTER TRUSTED CONTEXT statement that includes the ENCRYPTION or WITH ENCRYPTION options in the ATTRIBUTES clause, the database server does not issue an SQL error. Except, however, for the WITH ENCRYPTION 'NONE' and the ENCRYPTION 'NONE' keyword options, the encryption options of the ALTER TRUSTED CONTEXT statement are not supported for HCL OneDB database servers.

DEFAULT ROLE attributes

The DEFAULT ROLE role option to the ALTER clause identifies a role that already exists on the current database server. This role can be used by a user who does not hold a user-specific role that was defined as part of the definition of the trusted-context object.

The NO DEFAULT ROLE keywords specify that the trusted-context object does not have a default role.

If a trusted connection for this trusted context is active, changes to the DEFAULT ROLE attribute take effect on the next new connection request, or on the next request to switch users.

ENABLE and DISABLE options of the ALTER clause

The ENABLE attribute specifies that the trusted-context object is enabled.

The DISABLE attribute specifies that the trusted-context object is in a disabled state, and is not enabled for any new trusted connections that are established.

You cannot use the SET Database Object Mode statement of SQL to change the ENABLE or DISABLE attributes of trusted contexts.

ADD USE FOR clause

The ADD USE FOR clause specifies additional users who can establish a trusted connection based on this trusted-context object. The PUBLIC attribute specifies that a trusted connection that is based on this trusted-context object can be used by any user.

The PUBLIC attribute must not already be specified for the trusted-context object, and PUBLIC must not be specified more than once in the ADD USE FOR clause. If the definition of a trusted-context object allows access by PUBLIC and also by one or more users, the user specifications override the PUBLIC specifications.

REPLACE USE FOR clause

The REPLACE USE FOR clause specifies that the way in which a specified user or the PUBLIC group uses the trusted-context object is to change. When you use the REPLACE USE FOR clause on PUBLIC, the trusted-context object must already be defined to allow use by PUBLIC, and PUBLIC must not be specified more than once in the REPLACE USE FOR clause.

The REPLACE USE FOR can specify a different role name, which must be a role that is defined on the database server. The role explicitly specified for the user overrides the default role, if a default role is currently associated with the trusted context.

The REPLACE USE FOR clause can also change the current authentication requirement for a user or for the PUBLIC group.

AUTHENTICATION attributes

The REPLACE USE FOR and ADD USE FOR clause can specify the authentication requirement for trusted connections based on this trusted-context object. The default is WITHOUT AUTHENTICATION.

The WITH AUTHENTICATION attribute specifies that switching the current user on a connection based on this trusted-context object to this user requires authentication.

The WITHOUT AUTHENTICATION attribute specifies that switching the current user does not require authentication.

DROP USE FOR clause

The DROP USE FOR clause specifies who can no longer use the trusted-context object. The users who are removed from the definition of the trusted-context object are those users who are currently allowed to use the trusted-context object. If one or more, but not all, users can be removed from the definition of the trusted-context object, the specified users are removed and a warning is returned. If none of the specified users can be removed from the definition of the trusted-context object, an error is returned.

If you use the DROP USE FOR clause on PUBLIC, it removes the ability of all users (except the SYSTEM AUTHID user ID, and any other individual users whose identifiers have been explicitly enabled) to use this trusted-context object.

Examples of modifying a trusted-context

For the following example, assume that trusted-context object appserver exists and that it is enabled. The following ALTER TRUSTED CONTEXT statement resets the object mode of the appserver trusted-context object to DISABLE. While in that mode, the appserver trusted context continues to exist, but it cannot be used to access the database server.

   ALTER TRUSTED CONTEXT appserver
     DISABLE;

For the following example, assume that trusted-context object secure_role exists. Issue an ALTER TRUSTED CONTEXT statement to modify the existing user joe to use the trusted-context object with authentication and to add everyone else to use the trusted-context object without authentication.

   ALTER TRUSTED CONTEXT securerole
     REPLACE USE FOR joe WITH AUTHENTICATION
     ADD USE FOR PUBLIC WITHOUT AUTHENTICATION;

The following example modifies the trusted-context object securerole to use an IPv4 address that is different from what it was originally defined to use.

   ALTER TRUSTED CONTEXT securerole
     ALTER ATTRIBUTES (ADDRESS '9.12.155.200');