ALTER TRUSTED CONTEXT

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

• SYSADM authority
• SECADM authority

Privilege set: If the statement is embedded in an application program, the privilege set is the set of privileges that are held by the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the union of the set of privileges that are held by each authorization ID of the process. If the statement is run in a trusted context with a role, the privilege set is the union of the set of privileges that are held by the role that is associated with the primary authorization ID and the set of privileges that are held by each authorization ID of the process.

Description

context-name

Identifies the trusted context to alter. context-name must refer to a trusted context that exists at the current server.

ALTER

Specifies that changes are to be made to the definition of an existing trusted context.

SYSTEM AUTHID authorization-name

Specifies that authorization-name is the system authorization ID for the trusted context. The system authorization ID is the primary authorization ID of the DB2® system that establishes the connection. For a remote connection, the authorization ID is derived from the system used ID that is provided by the external entity, such as a middleware server. For a local connection, the system authorization ID is derived depending on the sources, as specified in Table 1.

Table 1. System authorization ID for a local connection

Source of local connection	System authorization ID
Started task (RRSAF)	USER parameter on JOB statement or RACF® USER.
TSO	TSO logon ID
BATCH	USER parameter on JOB statement

authorization-name must not be associated with an existing trusted context.

NO DEFAULT ROLE or DEFAULT ROLE role-name

Specifies whether a default role is associated with a trusted connection that is based on the specified trusted context. If a trusted connection for the specified context is active, the change goes into effect at the next connection reuse attempt or when a new connection is requested.

NO DEFAULT ROLE

Specifies that the trusted context does not have a default role. The authorization ID of the process is the owner of any object that is created using a trusted connection that is based on this trusted context. That authorization ID must possess all of the privileges that are necessary to create that object.

DEFAULT ROLE role-name

Specifies that role-name is the role for the trusted context. role-name must identify a role that exists at the current server. This role is used with the user in a trusted connection that is based on the specified trusted context when the user does not have a user-specified role that is defined as part of the definition of this trusted context.

WITHOUT ROLE AS OBJECT OWNER or WITH ROLE AS OBJECT OWNER AND QUALIFIER

Specifies whether a role is used as the owner of objects that are created using a trusted connection that is based on the specified trusted context. If a trusted connection for the specified context is active, the change goes into effect at the next connection reuse attempt or when a new connection is requested.

WITHOUT ROLE AS OBJECT OWNER

Specifies that a role is not used as the owner of the objects that are created using a trusted connection that is based on the specified trusted context. The authorization ID of the process is the owner of any object that is the created using a trusted connection that is based on this trusted context. That authorization ID must possess all of the privileges that are necessary to create the object.

WITHOUT ROLE AS OBJECT OWNER is the default.

WITH ROLE AS OBJECT OWNER AND QUALIFIER

Specifies that the context assigned role is the owner of the objects that are created using a trusted connection that is based on this trusted context. That role must possess all of the privileges that are necessary to create the object. The context assigned role is the role that is defined for the user within this trusted context, if one is defined. Otherwise, the role is the default role that is associated with the trusted context. The role is also used as the grantor for any GRANT statements that are issued, and the revoker for any REVOKE statement that are issued using a trusted connection that is based on this trusted context.

AND QUALIFIER

Specifies that the role-name will be used as the default for the CURRENT SCHEMA special register. The role-name will also be included in the SQL PATH (in place of CURRENT SQLID).

When WITH ROLE AS OBJECT OWNER AND QUALIFIER is not specified, there is no change to the default of the CURRENT SCHEMA special register and SQL PATH.

DISABLE or ENABLE

Specifies whether the trusted context is in the enabled or disabled state.

DISABLE

Specified that the trusted context is disabled. A trusted context that is disabled is not considered when a trusted connection is established.

ENABLE

Specifies that the trusted context is enabled.

NO DEFAULT SECURITY LABEL or DEFAULT SECURITY LABELseclabel-name

Specifies whether a default security label is associated with a trusted connection that is based on this trusted context. If a trusted connection for the specified context is active, the change goes into effect at the next connection reuse attempt or when a new connection is requested.

NO DEFAULT SECURITY LABEL

Specifies that the trusted context does not have a default security label.

DEFAULT SECURITY LABEL seclabel-name

Specifies that seclabel-name is the default security label for the trusted context. seclabel-name is the security label that is used for multilevel security verification. seclabel-name must identify one of the RACF SECLABEL values that is defined for the SYSTEM AUTHID. This security label is used in a trusted connection that is based on the specified trusted context when the user does not have a specific security label defined as part of the definition of this trusted context. In this case, seclabel-name must also identify one of the RACF SECLABEL values that is defined for the user.

ALTER ATTRIBUTES or ADD ATTRIBUTES

Specifies a list of one or more connection trust attributes to change or add to the definition of a trusted context. The connection trust attributes are used to define the trusted context. If ALTER ATTRIBUTES is specified and the attribute is not currently part of the definition of the specified trusted context, an error is returned. Existing specifications for the specified attributes are changed to the new value if ALTER is specified. Attributes that are not specified retain the previously specified values.

ADDRESS address-value

Specifies the actual communication address that is used by the connection to communicate with the database manager. The protocol supported is only for TCP/IP. Previously specified ADDRESS values are removed when ALTER ATTRIBUTES is specified. The ADDRESS attribute can be specified multiple times, but each address-value must be unique.

When establishing a trusted connection, if multiple values are defined for the ADDRESS attribute for a trusted context, a candidate connection is considered to match this attribute if the address that is used by a connection matches any of the values that are defined for the ADDRESS attribute of the trusted context.

address-value specifies a string constant that contains the value that is associated with the ADDRESS trust attribute. address-value must be an IPv4 address, an IPv6 address, or a secure domain name with a length no greater than 254 bytes. No validation of address-value is done at the time the ALTER TRUSTED CONTEXT statement is processed. address-value must be left justified within the string constant.

• An IPv4 address is represented as a dotted decimal address. An example of an IPv4 address is 9.112.46.111.
• An IPv6 address is represented as a colon hexadecimal address. An example of an IPv6 address is 2001:0DB8:0000:0000:0008:0800:200C:417A. This address can also be express in a compressed form as 2001:DB8::8:800:200C:417A.
• A domain name is converted to an IP address by the domain name server where a resulting IPv4 or IPv6 address is determined. An example of a domain name is www.ibm.com. The gethostbyname socket call is used to resolve the domain name.

ENCRYPTION encryption-value

Specifies the minimum level of encryption of the data stream (network encryption) for the connection.

encryption-value specifies a string constant that contains the value that is associated with the ENCRYPTION trust attribute. encryption-value must be left justified within the string constant. ENCRYPTION must not be specified more than one time in the statement. encryption-value must be one of the following:

• NONE, which specifies that no specific level of encryption is required.
• LOW, which specifies that a minimum of light encryption is required. LOW corresponds to 64-bit DRDA encryption.
• HIGH, which specifies that strong encryption is required. HIGH corresponds to SSL encryption.

ENCRYPTION cannot be specified if ADD ATTRIBUTES is specified. See CREATE TRUSTED CONTEXT for more information about the ENCRYPTION attribute.

JOBNAME jobname-value

Specifies the z/OS® job name or started task name (depending on the source of the address space) for local applications. Previously specified values for JOBNAME are removed when ALTER ATTRIBUTES is specified. The JOBNAME attribute can be specified multiple times, but each jobname-value must be unique.

jobname-value specifies a string constant that contains the value that is associated with the JOBNAME trust attribute. jobname-value is an EBCDIC 8 byte job name or started task name. jobname-value must be left justified within the string constant. The last character in the name can be a wildcard character (*) if the first character is an alphabetic character. If the job name ends with a wildcard, any job names that match the specified characters are considered for establishing the trusted connection.

The following table lists possible values for the job name depending on the source of the address space).

Table 2. Job name for local connection

Source of the address space	Job name
RRSAF	Job name or started task name
TSO	TSO logon ID
BATCH	Job name on JOB statement

SERVAUTH servauth-value

Specifies the name of a resource in the RACF SERVAUTH class. This resource is the network access security zone name that contains the IP address of the connection that is used to communicate with DB2. Previously specified values for SERVAUTH are removed when ALTER ATTRIBUTES is specified. The SERVAUTH attribute can be specified multiple times but each servauth-value must be unique.

servauth-value specifies a string constant that contains the value that is associated with the SERVAUTH trust attribute. servauth-value is an EBCDIC 64 byte RACF SERVAUTH CLASS resource name. servauth-value must be left justified in the string constant. No validation of servauth-value is done at the time the ALTER TRUSTED CONTEXT statement is processed.

DROP ATTRIBUTES

Specifies that one or more attributes are dropped from the definition of a trusted context. If the attribute is not currently specified as part of the definition of a trusted context, an error is returned. The specification of DROP ATTRIBUTES must not attempt to drop all of the existing attributes for a trusted context.

ADDRESS address-value

Specifies that the identified communication address is removed from the definition of the trusted context. address-value specifies a string constant that contains the value of an existing ADDRESS trust attribute.

JOBNAME jobname-value

Specifies that the identified job name is removed from the definition of the trusted context. jobname-value specifies a string constant that contains the value of an existing JOBNAME trust attribute.

SERVAUTH servauth-value

Specifies that the identified servauth that is removed from the definition of the trusted context. servauth-value specifies a string constant that contains the value of an existing SERVAUTH trust attribute.

ADD USE FOR

Specifies additional users who can use a trusted connection that is based on the specified trusted context.

authorization-name

Specifies that the trusted connection can be used by the specified authorization-name. This is the DB2 primary authorization ID. The authorization-name must not identify an authorization ID that is already defined to use the trusted context, and must not be specified more than one time in the ADD USE FOR clause.

ROLE role-name

Specifies that role-name is the role that is used when a trusted connection is used by the specified authorization-name. The role-name must identify a role that exists at the current server. The role that is explicitly specified for the user overrides any default role that is associated with the trusted context.

SECURITY LABEL seclabel-name

Specifies that seclabel-name is the security label to use for multilevel security verification when the trusted connection is used by the specified authorization-name. The seclabel-name must be one of the RACF SECLABEL values that is defined for the user. The security label that is explicitly specified for the user overrides any default security label that is associated with the trusted context.

EXTERNAL SECURITY PROFILE profile-name

Specifies that the trusted connection can be used by the DB2 primary authorization IDs that are permitted to use the specified profile-name in RACF. profile-name must not already be defined to use the trusted context, and must not be specified more than one time in the ADD USE FOR clause.

After you specify an external security profile, any user who is permitted access to the RACF profile can use the trusted context in addition to any users that are specified using the ADD USE FOR authorization-name clause.

ROLE role-name

Specifies that role-name is the role that is used when a trusted connection is used by any authorization ID that is permitted to use the specified profile-name in RACF. The role-name must identify a role that exists at the current server. The role that is explicitly specified for the profile overrides any default role that is associated with the trusted context.

SECURITY LABEL seclabel-name

Specifies that seclabel-name is the security label to use for multilevel security verification when the trusted connection is used by any authorization ID that is permitted to use the specified profile-name in RACF. The seclabel-name must be one of the RACF SECLABEL values that is defined for the user. The security label that is explicitly specified for the profile overrides any default security label that is associated with the trusted context.

PUBLIC

Specifies that a trusted connection that is based on the specified trusted context can be used by any user. PUBLIC must not already be defined to use the trusted context and must not be specified more than one time in the ADD USE FOR clause.

All users that are using a trusted connection that is defined with PUBLIC use the privileges that are associated with the default role for the associated trusted context. If the default role is not defined for the trusted context, there is no role associated with the users that use a trusted connection that is based on the specified trusted context.

If the default security label for the trusted context is defined, all users that are using the trusted context must have the security label defined as one of the RACF SECLABEL values for the user. The default security label is used for multilevel security verification with all users that are using the trusted context.

The specifications for a user are determined in the following order of precedence:

• authorization-name
• EXTERNAL SECURITY PROFILE profile-name
• PUBLIC

For example, assume that a trusted context is defined with use for JOE WITH AUTHENTICATION, EXTERNAL SECURITY PROFILE SPROFILE WITHOUT AUTHENTICATION (with JOE and SAM permitted to use the RACF PROFILE SPROFILE), and PUBLIC WITH AUTHENTICATION. If the trusted connection is used by JOE, authentication is required. If the trusted connection is used by SAM, authentication is not required. However, if the trusted connection is used by SALLY, authentication is required.

REPLACE USE FOR

Specifies a change to the specified user or PUBLIC for who can use the trusted context.

authorization-name

Specifies the authorization-name that is changed for use of the trusted context. The trusted context must already be defined to allow use by authorization-name, and authorization-name must not be specified more than one time in the REPLACE USE FOR clause. The information that is associated with authorization-name is changed as indicated.

ROLE role-name

Specifies that role-name is the role that is used when a trusted connection is using the specified trusted context. The role-name must identify a role that exists at the current server. The role that is explicitly specified for the user overrides any default role that is associated with the trusted context.

SECURITY LABEL seclabel-name

Specifies that seclabel-name is the security label to use for multilevel security verification when the trusted connection is used by the specified authorization-name. The seclabel-name must be one of the RACF SECLABEL values that is defined for the user. The security label that is explicitly specified for the user overrides any default security label that is associated with the trusted context.

EXTERNAL SECURITY PROFILE profile-name

Specifies the profile-name to change attributes for use of the trusted connection. The trusted context must already be defined to allow the use of profile-name. profile-name must not be specified more than one time in the REPLACE USE FOR clause. The information that is associated with the profile name is changed as indicated.

ROLE role-name

Specifies that role-name is the role that is used when a trusted connection is used by any authorization ID that is permitted to use the specified profile-name in RACF. The role name must identify a role that exists at the current server. The role that is explicitly specified for the profile overrides any default role that is associated with the trusted context.

SECURITY LABEL seclabel-name

Specifies that seclabel-name is the security label to use for multilevel security verification when the trusted connection is used by any authorization ID that is permitted to use the specified profile-name in RACF. The seclabel-name must be one of the RACF SECLABEL values that is defined for the user. The security label that is explicitly specified for the user overrides any default security label that is associated with the trusted context.

PUBLIC

Specifies that the attributes for use of the trusted connection by PUBLIC are to be changed. PUBLIC must already be defined to use the trusted context, and PUBLIC must not be specified more than one time in the REPLACE USE FOR clause.

All users that are using a trusted connection that is defined with PUBLIC use the privileges that are associated with the default role for the associated trusted context. If the default role is not defined for the trusted context, there is no role associated with the users that use a trusted connection that is based on the specified trusted context.

If the default security label for the trusted context is defined, all users that are using the trusted context must have the security label defined as one of the RACF SECLABEL values for the user. The default security label is used for multilevel security verification with all users that are using the trusted context.

WITHOUT AUTHENTICATION or WITH AUTHENTICATION

Specifies whether use of the trusted connection requires authentication of the user.

WITHOUT AUTHENTICATION

Specifies that use of a trusted connection by the user does not require authentication. WITHOUT AUTHENTICATION is the default.

WITH AUTHENTICATION

Specifies that use of a trusted connection requires the authentication token with the authorization ID to authenticate the user.

DROP USE FOR

Specifies who can no longer use the trusted context. The users that are removed from the definition of the trusted context are the specified users (or PUBLIC) that are currently allowed to use the trusted context. If multiple users are specified to be dropped, and one or more of those users cannot be dropped, those users that can be dropped are dropped and a warning is returned. If none of the specified users can be removed from the definition of the trusted context, an error is returned.

authorization-name

Specifies the authorization-name that will no longer be able to use this trusted context.

EXTERNAL SECURITY PROFILE profile-name

Removes the ability for the specified profile-name to use the trusted context.

PUBLIC

Specifies that PUBLIC users will no longer be able to use this trusted context. The system authorization ID and individual authorization IDs that have been explicitly enabled can still use the trusted context.

Notes

Precedence for authorization-name and authentication requirements: If the authorization-name that is specified in the SYSTEM AUTHID clause is the same authorization name that is specified in the ADD or REPLACE USE FOR authorization-name clauses, the role or the security label that is specified for the authorization-name takes precedence over the default value and the value that is specified for the EXTERNAL SECURITY PROFILE profile-name (if one is specified). If the authorization name that is specified in the SYSTEM AUTHID clause is permitted to use one of the specified profile names and is not specified in ADD or REPLACE USE for authorization-name, the role or the security label that is specified for that profile-name takes precedence over the default value.

Authentication is required for SYSTEM AUTHID if the AUTHENTICATION clause is specified in the ADD or REPLACE USE FOR clauses, or if the subsystem parameter TCP/IP Already Verified is set to NO. For example, if authorization-name is the same as the authorization name that is specified in the SYSTEM AUTHID clause and the WITHOUT AUTHENTICATION clause is specified, but the TCP/IP Already Verified subsystem parameter is set to NO, authentication is required for SYSTEM AUTHID when the remote trusted connection is established. If authorization-name is the SYSTEM AUTHID and the WITH AUTHENTICATION clause is specified, but the TCP/IP Already Verified subsystem parameter is set to YES, authentication is still required for SYSTEM AUTHID.