CREATE TRUSTED CONTEXT

The CREATE TRUSTED CONTEXT statement defines a trusted context at the current server.

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 privileges that are held by the owner of the plan or package. If the application is bound in a trusted context with the ROLE AS OBJECT OWNER clause specified, a role is the owner. Otherwise, an authorization ID is the owner.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process unless the process is within a trusted context and the ROLE AS OBJECT OWNER clause is specified. In that case, the privileges set is the privileges that are held by the role that is associated with the primary authorization ID of the process.

Syntax

>>-CREATE TRUSTED CONTEXT--context-name------------------------->

>--BASED UPON CONNECTION USING SYSTEM AUTHID--authorization-name-->

   .-NO DEFAULT ROLE-------------------------------------------------------.   
>--+-----------------------------------------------------------------------+-->
   |                          .-WITHOUT ROLE AS OBJECT OWNER-------------. |   
   '-DEFAULT ROLE--role-name--+------------------------------------------+-'   
                              '-WITH ROLE AS OBJECT OWNER--AND QUALIFIER-'     

   .-DISABLE-.  .-NO DEFAULT SECURITY LABEL-------------.   
>--+---------+--+---------------------------------------+------->
   '-ENABLE--'  '-DEFAULT SECURITY LABEL--seclabel-name-'   

                        .-,------------------------------------.            
              (1)       V                                      |   (3)      
>--ATTRIBUTES------(--+---+-ADDRESS--address-value-----------+-+-+------)-->
                      |   |                              (2) |   |          
                      |   +-ENCRYPTION--encryption-value-----+   |          
                      |   '-SERVAUTH--servauth-value---------'   |          
                      | .-,----------------------.               |          
                      | V                        |               |          
                      '---JOBNAME--jobname-value-+---------------'          

>--+-------------------------------------------------------------------------------------+-><
   |               .-,-----------------------------------------------------------------. |   
   |               V                                                                   | |   
   '-WITH USE FOR----+-authorization-name--+------------------+----------------------+-+-'   
                     |                     '-| user-options |-'                      |       
                     +-EXTERNAL SECURITY PROFILE--profile-name--+------------------+-+       
                     |                                          '-| user-options |-' |       
                     |         .-WITHOUT AUTHENTICATION-.                            |       
                     '-PUBLIC--+------------------------+----------------------------'       
                               '-WITH AUTHENTICATION----'

Notes:

This clause and the clauses that follow can be specified in any order. Each clause must not be specified more than one time.
ENCRYPTION must not be specified more than one time.
Each pair of attribute name and corresponding value must be unique.

user-options:

    (1)                                                          .-WITHOUT AUTHENTICATION-.   
>>-------+-----------------+--+-------------------------------+--+------------------------+-><
         '-ROLE--role-name-'  '-SECURITY LABEL--seclabel-name-'  '-WITH AUTHENTICATION----'

Notes:

These clauses can be specified in any order. Each clause must not be specified more than one time.

Description

context-name

Names the trusted context. The name must not identify a trusted context that exists at the current server.

BASED UPON CONNECTION USING SYSTEM AUTHID authorization-name

Specifies that the context is a connection that is established by the authorization ID that is specified by authorization-name. The system authorization ID is the primary authorization ID. For a remote connection, it is derived from the system user ID that is provided by an 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.

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.
NO DEFAULT ROLE is the default.
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.

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 and 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 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 for the CURRENT SCHEMA special register and the SQL PATH.

DISABLE or ENABLE

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

DISABLE: Specified that the trusted context is disabled when it is created. A trusted context that is disabled is not considered when a trusted connection is established. DISABLE is the default.
ENABLE: Specifies that the trusted context is enabled when it is created.

NO DEFAULT SECURITY LABEL or DEFAULT SECURITY LABEL seclabel-name

Specifies whether the trusted connection has a default security label.

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

ATTRIBUTES

Specifies a list of one or more connection trust attributes that are used to define the trusted context.

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. 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 defined values 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 CREATE 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).

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.

The following table summarizes when a trusted context can be used depending on the encryption that is used by the existing connection. If the trusted context cannot be used for the connection, a warning is returned.

Table 2. Summary of when trusted context can be used by an existing connection
Encryption that is used by the existing connection	Value of the ENCRYPTION clause for the trusted context	Can the trusted context be used for the connection?
No encryption	NONE	Yes
No encryption	LOW	No
No encryption	HIGH	No
Low encryption (64-bit)	NONE	Yes
Low encryption (64-bit)	LOW	Yes
Low encryption (64-bit)	HIGH	No
High encryption (128-bit)	NONE	Yes
High encryption (128-bit)	LOW	Yes
High encryption (128-bit)	HIGH	Yes

JOBNAME jobname-value

Specifies the z/OS® job name or started task name (depending on the source of the address space) for local applications. 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 value that specifies the job name or the started task name. The 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 begin with 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 3. 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®. 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 CREATE TRUSTED CONTEXT statement is processed.

WITH USE FOR

Specifies 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 be specified more than one time in the WITH 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.

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. If a trusted connection is established locally, the authentication token is the password that is provided by the CONNECT statement with the USER and USING clauses. If the trusted connection is established from a remote client, the authentication token can be one of the following tokens:

password
RACF Passticket
Kerberos token

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 be specified more than one time in the WITH USE FOR clause.

ROLE role-name

Specifies that role-name is the role that is used when a trusted connection is used by any authorization ID 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.

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

password
RACF Passticket
Kerberos token

PUBLIC

Specifies that a trusted connection that is based on the specified trusted context can be used by any user. 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

password
RACF Passticket
Kerberos token

Notes

Owner privileges: There are no specific privileges on a trusted context.

Requirement for trusted connections: To use trusted connections, you cannot set the ALL subsystem parameter to ALL and set the RESTART subsystem parameter to DEFER on installation panel DSNTIPS.

Order of precedence for users of a trusted connection: 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, and PUBLIC WITH AUTHENTICATION. Users JOE and SAM are permitted to use the RACF PROFILE SPROFILE. 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 user SALLY uses the trusted connection, authentication is required.

User-clause SYSTEM AUTHID considerations: If the authorization-name that is specified in the SYSTEM AUTHID clause is the same as the authorization-name that is specified in the user-clause authorization-name, the role or the security label that is specified for authorization-name takes precedence over the default value. The value that is specified for the profile-name, is permitted to use the profile. If the authorization name that is specified in the SYSTEM AUTHID clause is permitted to use one of the profile names and is not defined in authorization-name, the role or the security label that is specified for that profile-name takes precedence over the default value.

If authentication is required for SYSTEM AUTHID, either by specification of the AUTHENTICATION clause in the user-clause or by setting the value of the TCP/IP Already Verified subsystem parameter to NO, the authentication requirement takes precedence when establishing a remote trusted connection. For example, if authorization-name is the same as the authorization name that is specified for SYSTEM AUTHID and the WITHOUT AUTHENTICATION clause is specified, but the TCP/IP Already Verified subsystem parameter is set to NO, an authentication token 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, an authentication token is still required for SYSTEM AUTHID.

Specifying a role in the definition of a trusted context: The definition of a trusted context can designate a role for a specific authorization ID, and a default role for use for an authorization ID for which a specific role has not been specified in the definition of the trusted context. This role can be used with a trusted connection that is based on the trusted context, but it does not make the role available outside of a trusted connection that is based on the trusted context. When an SQL statement that is not a CREATE, GRANT, or REVOKE statement is issued using a trusted connection, the privileges that are held by a role that is in effect for the authorization ID within the definition of the associated trusted context are considered in addition to other privileges that are directly held by the authorization ID of the statement. The CREATE, GRANT, and REVOKE statements only consider the privileges of the role that is in effect for the trusted connection, or the authorization ID of the statement if a role is not in effect for the trusted connection. If ROLE AS OBJECT OWNER is in effect for a trusted connection, the role that is in effect for the authorization ID for the trusted connection becomes the owner of any object that is created while using the trusted connection.

When a newly created trusted context takes effect: The newly created trusted context takes effect after the CREATE TRUSTED CONTEXT statement is committed. If the CREATE TRUSTED CONTEXT statement results in an error or is rolled back, no trusted context is created.

Examples

Example 1: The following statement creates a trusted context called CTX1, which is based on a connection and can only be used by users JOE and SAM. Authentication information is required for JOE to use the trusted connection. The trusted context specifies a default role called CTXROLE. However, when JOE uses the trusted connection, the default role is overridden by the user role, ROLE1. When SAM uses the trusted connection, SAM uses the default role. CTX1 is enabled when it is created.

   CREATE TRUSTED CONTEXT CTX1
       BASED UPON CONNECTION USING SYSTEM AUTHID ADMF001
       ATTRIBUTES (ADDRESS '9.30.131.203',
                   ENCRYPTION 'LOW')
       DEFAULT ROLE CTXROLE
       ENABLE
       WITH USE FOR SAM, JOE ROLE ROLE1 WITH AUTHENTICATION;

Example 2: The following statement creates a trusted context, CTX2, for a started task, WASPROD. CTX2 is based on a connection, can be used by user SALLY, specifies a default role CTXROLE, and is enabled when it is created. SALLY uses the default role that is associated with the trusted context.

   CREATE TRUSTED CONTEXT CTX2
        BASED UPON CONNECTION USING SYSTEM AUTHID ADMF002
        ATTRIBUTES (JOBNAME 'WASPROD')
        DEFAULT ROLE CTXROLE WITH ROLE AS OBJECT OWNER AND QUALIFIER
        ENABLE
        WITH USE FOR SALLY;