CREATE TRUSTED CONTEXT statement
The CREATE TRUSTED CONTEXT statement defines a trusted context at the current server.
Invocation for CREATE TRUSTED CONTEXT
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 for CREATE TRUSTED CONTEXT
- 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 for CREATE TRUSTED CONTEXT
- 1 This clause and the clauses that follow can be specified in any order. Each clause must not be specified more than one time.
- 2 ENCRYPTION must not be specified more than one time.
- 3 Each pair of attribute name and corresponding value must be unique.
user-options:
Description for CREATE TRUSTED CONTEXT
- 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.
authorization-name must not be associated with an existing trusted context.
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 - 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. If an authorization ID is permitted to use more than one
specified profile-name, the role that is specified for
profile-name can be associated with the process if the user authentication
satisfies the AUTHENTICATION definition. This role can hold additional privileges that are available
to the process.
- 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
- 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
- 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
- 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
Notes for CREATE TRUSTED CONTEXT
Owner privileges: There are no specific privileges on a trusted context.
Requirement for trusted connections: If you set field 1 (RESTART or DEFER) to DEFER and set field 2 (objects to restart or defer) to ALL in installation panel DSNTIPS, you cannot use trusted connections.
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 for CREATE TRUSTED CONTEXT
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;
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;