11 Oracle Database Real Application Security PL/SQL Packages

CREATE_SESSION Procedure

The CREATE_SESSION procedure creates a new application session for the specified user name. It returns a session identifier that you can use to reference the session in future calls.

The session can be created with a regular application user or an external application user. The session can be created in trusted mode or secure mode. In trusted mode, data security checks are bypassed; in secure mode, they are enforced.

The combination of regular session in trusted mode is not supported. Other combinations, regular session in secure mode, external session in trusted mode, or external session in secure mode are supported.

The namespaces parameter is a list of triplet namespaces to be created, the attribute to be created, and the attribute value to be set. This is an optional parameter. The default value is NULL. The XS$GLOBAL_VAR and XS$SESSION namespaces and their attributes are always available to the session.

This function does not attach the current traditional session to the newly created application session. Use the ATTACH_SESSION Procedure to perform this task.

The user executing the procedure must have the CREATE_SESSION application privilege for the application user specified by the username parameter. You can also specify a list of namespaces to be created when the session is created. If you specify namespaces during creation of the session, the caller is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or be granted the ADMIN_NAMESPACE system privilege.

Syntax

CREATE_SESSION (
 username      IN  VARCHAR2,
 sessionid     OUT NOCOPY RAW,
 is_external   IN  BOOLEAN DEFAULT FALSE,
 is_trusted    IN  BOOLEAN DEFAULT FALSE,
 namespaces    IN  DBMS_XS_NSATTRLIST DEFAULT NULL,
 cookie        IN  VARCHAR2 DEFAULT NULL); 

Parameters

SELECT NAME FROM DBA_XS_USERS;

SELECT NAME FROM DBA_XS_ROLES;

SELECT NAME FROM DBA_XS_DYNAMIC_ROLES;

Examples

DECLARE
  nsList DBMS_XS_NSATTRLIST;
  sessionid RAW(16);
BEGIN
    nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
    SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid, FALSE, FALSE, nsList);
END;

ATTACH_SESSION Procedure

The ATTACH_SESSION procedure attaches the current traditional database session to the application session identified by the session ID (session_id). The attached session enables the roles granted (directly or indirectly) to the application user with which the session was created and the session scope dynamic application roles that were enabled until the last detach of this session. If you execute ATTACH_SESSION with a list of dynamic application roles using the optional parameter enable_dynamic_roles, the provided dynamic application roles are enabled for the session. To disable a list of dynamic roles, specify the list using the optional parameter disable_dynamic_roles.

You can specify a list of triplet values (namespace, attribute, attribute value) during the attach operation. The namespaces and attributes are then created and attribute values set. This is in addition to any namespaces and attributes that were present in the session.

To execute this procedure, the traditional session user must have the ATTACH_SESSION application privilege. If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege.

A self password change is allowed using the SQL*Plus PASSWORD command if invoked from an explicitly attached session (a session attached using the ATTACH_SESSION procedure or the attachSession() method in Java), provided that session has the ALTER_USER privilege and the user name is provided with the PASSWORD command.

Syntax

ATTACH_SESSION (
 sessionid              IN RAW,
 enable_dynamic_roles   IN XS$NAME_LIST         DEFAULT NULL,
 disable_dynamic_roles  IN XS$NAME_LIST         DEFAULT NULL,
 external_roles         IN XS$NAME_LIST         DEFAULT NULL,
 authentication_time    IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
 namespaces             IN DBMS_XS_NSATTRLIST   DEFAULT NULL);

Parameters

SELECT NAME, TYPE FROM DBA_XS_PRINCIPALS; 

Examples

DECLARE
  nsList DBMS_XS_NSATTRLIST;
  sessionid RAW(16);
BEGIN
    nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
    SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
    SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid, NULL, NULL, NULL, NULL, nsList);  
END;

ASSIGN_USER Procedure

The ASSIGN_USER procedure assigns a named application user to the currently attached anonymous application session.

Roles enabled in the current session are retained after this operation. The optional parameters enable_dynamic_roles and disable_dynamic_roles specify the additional lists of dynamic roles to be enabled or disabled. If the assigned user is external, you can specify a list of external roles to be enabled.

You can specify a list of triplet values (namespace, attribute, attribute value) during the assign operation. The namespaces and attributes are then created in the session and attribute values set. This is in addition to any namespaces and attributes that were already present in the session.

To execute this procedure, the dispatcher or connection user must have the ASSIGN_USER application privilege. If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege.

Syntax

DBMS_XS_SESSIONS.ASSIGN_USER (
 username              IN VARCHAR2, 
 is_external           IN BOOLEAN                  DEFAULT FALSE,
 enable_dynamic_roles  IN XS$NAME_LIST             DEFAULT NULL,
 disable_dynamic_roles IN XS$NAME_LIST             DEFAULT NULL,
 external_roles        IN XS$NAME_LIST             DEFAULT NULL,
 authentication_time   IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
 namespaces            IN DBMS_XS_NSATTRLIST       DEFAULT NULL);

Parameters

SELECT NAME FROM DBA_XS_PRINCIPALS;

SELECT NAME FROM DBA_XS_DYNAMIC_ROLES;

Examples

DECLARE
  nsList DBMS_XS_NSATTRLIST;
  sessionid RAW(16);
BEGIN 
  nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DB);
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.ASSIGN_USER(username => 'lwuser2',
                               namespaces => nsList);
END;

SWITCH_USER Procedure

The SWITCH_USER procedure switches the application user in the currently attached session. The current application user must be a proxy user for the target application user before performing the switch operation by using the XS_PRINCIPAL.ADD_PROXY_USER PL/SQL API to acquire the proxy of another application user privilege. The list of filtering application roles of the target user gets enabled in the session.

You can retain current application namespaces of the session or discard them. You can also specify a list of namespaces to be created and attribute values to be set after the switch. If you specify namespaces, then the user is required to be granted application privileges MODIFY_NAMESPACE or MODIFY_ATTRIBUTE on the namespaces, or ADMIN_NAMESPACE system privilege.

Syntax

SWITCH_USER (
 username          IN VARCHAR2,
 keep_state        IN BOOLEAN              DEFAULT FALSE, 
 namespaces        IN DBMS_XS_NSATTRLIST   DEFAULT NULL);

Parameters

SELECT NAME FROM DBA_XS_USERS;

Examples

DECLARE
  nsList := DBMS_XS_NSATTRLIST(DBMS_XS_NSATTR('ns1'),DBMS_XS_NSATTR('ns2'));
  sessionid RAW(16);
BEGIN 
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.ATTACH_SESSION(sessionid);
  SYS.DBMS_XS_SESSIONS.SWITCH_USER(username => 'lwuser2',
                               keep_state => TRUE,
                               namespaces => nsList);
END;

CREATE_NAMESPACE Procedure

The CREATE_NAMESPACE procedure creates a new namespace in the currently attached application session. The namespace template corresponding to the namespace must exist in the system, else this operation throws an error. After this operation, the namespace along with its attributes as they are created in the template are available to the session.

The calling user must have the MODIFY_NAMESPACE application privilege.

Syntax

CREATE_NAMESPACE( 
 namespace      IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.CREATE_NAMESPACE('J_NS1');
END;

CREATE_ATTRIBUTE Procedure

The CREATE_ATTRIBUTE procedure creates a new custom attribute in the specified namespace in the currently attached application session. If the namespace is not already available in the session or no such namespace templates exist, an error is thrown.

The calling user is required to be granted the MODIFY_ATTRIBUTE application privilege.

Syntax

PROCEDURE create_attribute(
namespace IN VARCHAR2,
attribute IN VARCHAR2,
value     IN VARCHAR2    DEFAULT NULL,
eventreg  IN PLS_INTEGER DEFAULT NULL);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.CREATE_ATTRIBUTE('NS1','NS1CUSTOM','NS1CUSTOMDEFAULT');
END;

-- Example with firstRead event set
BEGIN
 SYS.DBMS_XS_SESSIONS.create_Attribute('ns1','attr4',NULL,
                                   DBMS_XS_SESSIONS.attribute_first_read_event);
END;

SET_ATTRIBUTE Procedure

The SET_ATTRIBUTE procedure sets a new value for the specified attribute in the namespace associated with the currently attached session. The handler function is called if the update event is set for the attribute. If the namespace does not exist or is deleted, an error is thrown. If there is no template corresponding to the namespace that exists, an error is thrown.

The calling user is required to be granted the MODIFY_ATTRIBUTE application privilege.

Syntax

SET_ATTRIBUTE (
 namespace    IN VARCHAR2,
 attribute    IN VARCHAR2,
 value        IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.SET_ATTRIBUTE('J_NS','JohnNSAttr1','John bio');
END;

GET_ATTRIBUTE Procedure

The GET_ATTRIBUTE procedure gets the value of the specified attribute in the namespace in the currently attached session. If no template corresponding to the namespace exists, an error is thrown. If the specified attribute does not exist, it returns empty string.

If the attribute value is NULL, the firstRead event is set, and it is the first time that the attribute value is being fetched, then the handler function for the attribute is called.

The calling user is not required to be granted any privileges.

Syntax

GET_ATTRIBUTE (
 namespace   IN         VARCHAR2,
 attribute   IN         VARCHAR2,
 value       OUT NOCOPY VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.GET_ATTRIBUTE('J_NS1','JohnNS1Attr1',attrVal);
END;

RESET_ATTRIBUTE Procedure

The RESET_ATTRIBUTE procedure resets the value of an attribute to its default value (if present) or to NULL in the namespace in the current attached session. If the attribute has a default value specified, then the value is reset to the default value. If the attribute was created without a default value and marked for the attribute_first_read_event, then the value is set to NULL and the attribute is marked as uninitialized. If the attribute was created without a default value and not marked for the attribute_first_read_event, then the value is set to NULL.

The calling user is required to be granted the MODIFY_ATTRIBUTE application privilege.

Syntax

PROCEDURE reset_attribute(
namespace   IN VARCHAR2,
attribute   IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.RESET_ATTRIBUTE('ns2','attr1');
END;

DELETE_ATTRIBUTE Procedure

The DELETE_ATTRIBUTE procedure deletes the specified attribute and its associated value from the specified namespace in the currently attached session. Only custom attributes can be deleted. Template attributes cannot be deleted. If the specified attribute does not exist, an error is thrown.

The calling application is required to be granted the MODIFY_ATTRIBUTE application privilege.

Syntax

DELETE_ATTRIBUTE (
 namespace     IN VARCHAR2,
 attribute     IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.DELETE_ATTRIBUTE('JohnNS1','JohnNS1Attr1');
END;

DELETE_NAMESPACE Procedure

The DELETE_NAMESPACE procedure deletes a namespace and its attributes from the currently attached application session.

The calling user must have the MODIFY_NAMESPACE application privilege.

Syntax

DELETE_NAMESPACE (
 namespace   IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.DELETE_NAMESPACE('JohnNS1');
END;

ENABLE_ROLE Procedure

The ENABLE_ROLE procedure enables a real application role in the currently attached application session. If the role is already enabled, then ENABLE_ROLE procedure performs no action. This procedure can only enable a regular application role directly granted to the current application user. You cannot enable dynamic application roles.

This operation does not require the calling user to have any additional privilege.

Syntax

ENABLE_ROLE (
 role   IN VARCHAR2);

Parameters

SELECT ROLE_NAME FROM V$XS_SESSION_ROLES;

SELECT SESSIONID, ROLE FROM DBA_XS_SESSION_ROLES;

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.ENABLE_ROLE('auth2_role');
END;

DISABLE_ROLE Procedure

The DISABLE_ROLE procedure disables a real application role from the specified application session. If the role is already disabled or not enabled in the currently attached application session, then DISABLE_ROLE performs no action. You cannot disable dynamic application roles. You can only disable a regular application role, which is directly granted to the application user with which the session is created.

This operation does not require the calling user to have any additional privilege.

Syntax

DISABLE_ROLE (
 role   IN VARCHAR2);

Parameters

SELECT ROLE_NAME FROM V$XS_SESSION_ROLES;

SELECT SESSIONID, ROLE FROM DBA_XS_SESSION_ROLES;

Examples

BEGIN
  SYS.DBMS_XS_SESSIONS.DISABLE_ROLE('auth1_role');
END;

SET_SESSION_COOKIE Procedure

The SET_SESSION_COOKIE procedure sets a new cookie value with the specified session ID. If the specified session does not exist or the cookie name is not unique among all the user application sessions, then an error is thrown.

To execute this procedure, the user is required to be granted the MODIFY_SESSION application privilege.

Syntax

SET_SESSION_COOKIE (
 cookie      IN VARCHAR2, 
 sessionid   IN RAW DEFAULT NULL);

Parameters

Examples

DECLARE
   sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.SET_SESSION_COOKIE('cookie1', sessionid);
END;

REAUTH_SESSION Procedure

The REAUTH_SESSION procedure updates the last authentication time for the specified session ID as the current time. Applications must call this procedure when it has reauthenticated an application user.

Use the REAUTH_SESSION procedure to enable a role that has timed out because of a lack of recent authentication in the application or middle-tier server. You can also call the reauthSession Java method.

To execute this function, the user is required to be granted the MODIFY_SESSION application privilege.

Syntax

REAUTH_SESSION (
 sessionid IN RAW DEFAULT NULL);

Parameters

Examples

DECLARE
  sessionid RAW(16);
BEGIN
 SYS.DBMS_XS_SESSIONS.REAUTH_SESSION(sessionid);
END;

SET_INACTIVITY_TIMEOUT Procedure

The SET_INACTIVITY_TIMEOUT procedure sets an inactivity time-out value, in minutes, for the current attached session. The inactivity time-out value represents the maximum period of inactivity allowed before Oracle Database terminates the application session and the resource is reclaimed. Trying to set a negative value for the time parameter throws an error. If an invalid session ID is specified or the session does not exist, an error is thrown.

Another way to set the time-out value is to use the setInactivityTimeout Java method. You can set a default global time-out value in the xmlconfig.xml configuration file. Oracle recommends 240 (4 hours).

An application session cannot time-out due to inactivity while a traditional session is attached. The last access time is updated each time a traditional session attaches to the application session.

To execute this procedure, the calling user is required to be granted the MODIFY_SESSION application privilege.

Syntax

SET_INACTIVITY_TIMEOUT (
 time        IN NUMBER, 
 sessionid   IN RAW DEFAULT NULL);

Parameters

Examples

DECLARE
  sessionid RAW(16);
BEGIN
  SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwuser1', sessionid);
  SYS.DBMS_XS_SESSIONS.SET_INACTIVITY_TIMEOUT (300, sessionid);
END;
/

SAVE_SESSION Procedure

The SAVE_SESSION procedure saves all changes performed in the currently attached session and remains attached to the session as it was before saving changes.

The calling user requires no privileges to perform this operation.

Syntax

SAVE_SESSION;

Parameters

None.

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.SAVE_SESSION;
END;

DETACH_SESSION Procedure

The DETACH_SESSION procedure detaches the current traditional database session from the application session to which it is attached. The database sessions goes back to the context it was in prior to attaching to the application session. Any user can execute this procedure as the operation does not require any privileges to execute.

Syntax

DETACH_SESSION (abort IN BOOLEAN DEFAULT FALSE);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.DETACH_SESSION;
END;

DESTROY_SESSION Procedure

The DESTROY_SESSION procedure destroys the specified session. This procedure also implicitly detaches all traditional sessions from the application session. After the session is destroyed no further attaches can be made to the session. This operation cannot destroy sessions created through direct logon of the application user.

To execute this procedure, the user must have the TERMINATE_SESSION application privilege.

Syntax

DESTROY_SESSION (
 sessionid IN RAW,
 force     IN BOOLEAN DEFAULT FALSE);

Parameters

Examples

DECLARE
  sessionid RAW(16);
BEGIN
 SYS.DBMS_XS_SESSIONS.CREATE_SESSION('lwtSession1', sessionid);
 SYS.DBMS_XS_SESSIONS.DESTROY_SESSION (sessionid);
END;

ADD_GLOBAL_CALLBACK Procedure

The ADD_GLOBAL_CALLBACK procedure registers an existing PL/SQL procedure as the event handler with the session operation specified by the event_type parameter. You can add more than one event handler for the same session operation for execution when the associated event occurs. Adding the global callback procedure automatically enables the callback procedure for execution. If more than one callback is added for the same session event, they are executed in according to their registration sequence, that is, the callback procedure that was registered first, is executed first. This procedure throws an error if an invalid event type is specified or the callback procedure does not exist.

Successful execution of this procedure requires the CALLBACK application privilege. This role can be obtained through PROVISIONER database role.

Syntax

ADD_GLOBAL_CALLBACK(
  event_type         IN PLS_INTEGER, 
  callback_schema    IN VARCHAR2, 
  callback_package   IN VARCHAR2,
  callback_procedure IN VARCHAR2);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.ADD_GLOBAL_CALLBACK (
  DBMS_XS_SESSIONS.CREATE_SESSION_EVENT, 
  'APPS1_SCHEMA','APPS2_PKG','CREATE_SESSION_CB');
END;

ENABLE_GLOBAL_CALLBACK Procedure

The ENABLE_GLOBAL_CALLBACK procedure enables or disables the global callback procedure for execution. If a callback procedure associated with this event is not specified, all callback procedures associated with this global callback are enabled or disabled. If an invalid event type is specified or invalid callback procedure is specified, an error is thrown.

Syntax

ENABLE_GLOBAL_CALLBACK(
  event_type         IN PLS_INTEGER,
  enable             IN BOOLEAN  DEFAULT TRUE,
  callback_schema    IN VARCHAR2 DEFAULT NULL,
  callback_package   IN VARCHAR2 DEFAULT NULL,
  callback_procedure IN VARCHAR2 DEFAULT NULL);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.ENABLE_GLOBAL_CALLBACK (
  DBMS_XS_SESSIONS.CREATE_SESSION_EVENT, 
  TRUE, 'APPS1_SCHEMA','APPS2_PKG','CREATE_SESSION_CB');
END;

DELETE_GLOBAL_CALLBACK Procedure

The DELETE_GLOBAL_CALLBACK procedure removes the global callback from registration. (It does not delete the global callback itself.) If a callback procedure is not specified, all callback procedures associated with this global callback are deleted. If an invalid event type is specified, an error is thrown.

Syntax

DELETE_GLOBAL_CALLBACK(
  event_type         IN PLS_INTEGER,
  callback_schema    IN VARCHAR2 DEFAULT NULL, 
  callback_package   IN VARCHAR2 DEFAULT NULL,
  callback_procedure IN VARCHAR2 DEFAULT NULL);

Parameters

Examples

BEGIN
 SYS.DBMS_XS_SESSIONS.DELETE_GLOBAL_CALLBACK (
  DBMS_XS_SESSIONS.CREATE_SESSION_EVENT, 
  'APPS1_SCHEMA','APPS2_PKG','CREATE_SESSION_CB');
END;

CREATE_ACL Procedure

The CREATE_ACL procedure creates a new Access Control List (ACL).

Syntax

XS_ACL.CREATE_ACL (  name            IN VARCHAR2,
  ace_list        IN XS$ACE_LIST,
  sec_class       IN VARCHAR2 := NULL,
  parent          IN VARCHAR2 := NULL,
  inherit_mode    IN PLS_INTEGER := NULL,
  description     IN VARCHAR2 := NULL); 

Parameters

Examples

The following example creates an ACL called HRACL. This ACL includes ACEs contained in ace_list. The privileges used in ace_list are part of the HRPRIVS security class.

DECLARE  
  ace_list XS$ACE_LIST;  
BEGIN 
  ace_list := XS$ACE_LIST(
      XS$ACE_TYPE(privilege_list=>XS$NAME_LIST('"SELECT"','VIEW_SENSITIVE_INFO'), 
                  granted=>true, 
                  principal_name=>'HRREP'),
      XS$ACE_TYPE(privilege_list=>XS$NAME_LIST('UPDATE_INFO'),
                  granted=>true,
                  principal_name=>'HRMGR'));
  SYS.XS_ACL.CREATE_ACL(name=>'HRACL',
                    ace_list=>ace_list,
                    sec_class=>'HRPRIVS',
                    description=>'HR Representative Access');
END;

APPEND_ACES Procedure

The APPEND_ACES procedure adds one or more ACE to an existing ACL.

Syntax

XS_ACL.APPEND_ACES (
  acl      IN VARCHAR2,
  ace      IN XS$ACE_TYPE); 

XS.ACL.APPEND_ACES (
  acl      IN VARCHAR2,
  ace_list IN XS$ACE_LIST); 

Parameters

Examples

The following example adds an ACE to the HRACL ACL. The ACE grants the SELECT privilege to the DB_HR database user.

DECLARE  
  ace_entry XS$ACE_TYPE;  
BEGIN 
  ace_entry := XS$ACE_TYPE(privilege_list=>XS$NAME_LIST('"SELECT"'), 
                           granted=>true,
                           principal_name=>'DB_HR',
                           principal_type=>XS_ACL.PTYPE_DB);
  SYS.XS_ACL.APPEND_ACES('HRACL',ace_entry);
END;

REMOVE_ACES Procedure

The REMOVE_ACES procedure removes all ACEs from an ACL.

Syntax

XS_ACL.REMOVE_ACES (
  acl IN VARCHAR2); 

Parameters

Examples

The following example removes all ACEs from the ACL called HRACL:

BEGIN
  SYS.XS_ACL.REMOVE_ACES('HRACL');
END;

SET_SECURITY_CLASS Procedure

The SET_SECURITY_CLASS procedure sets or modifies the security class for an ACL.

Syntax

XS_ACL.SET_SECURITY_CLASS (
  acl       IN VARCHAR2,
  sec_class IN VARCHAR2);

Parameters

Examples

The following example associates the HRPRIVS security class with the HRACL ACL:

BEGIN
  SYS.XS_ACL.SET_SECURITY_CLASS('HRACL','HRPRIVS');
END;

SET_PARENT_ACL Procedure

The SET_PARENT_ACL sets or modifies the parent ACL for an ACL.

Syntax

XS_ACL.SET_PARENT_ACL(
  acl            IN VARCHAR2,
  parent         IN VARCHAR2,
  inherit_mode   IN PLS_INTEGER);

Parameters

Examples

The following example sets the AllDepACL ACL as the parent ACL for the HRACL ACL. The inheritance type is set to EXTENDED.

BEGIN
  SYS.XS_ACL.SET_PARENT_ACL('HRACL','AllDepACL',XS_ACL.EXTENDED);
END;

ADD_ACL_PARAMETER Procedure

The ADD_ACL_PARAMETER adds an ACL parameter value for a data security policy.

Syntax

XS_ACL.ADD_ACL_PARAMETER (
  acl         IN VARCHAR2,
  policy      IN VARCHAR2,
  parameter   IN VARCHAR2,
  value       IN NUMBER); 

XS_ACL.ADD_ACL_PARAMETER (
  acl         IN VARCHAR2,
  policy      IN VARCHAR2,
  parameter   IN VARCHAR2,
  value       IN VARCHAR2);

Parameters

Examples

The following example adds the REGION parameter for ACL1. The name of the data security policy for which the ACL parameter is created is TEST_DS. The value of the REGION parameter is WEST.

BEGIN
  SYS.XS_ACL.ADD_ACL_PARAMETER('ACL1','TEST_DS','REGION', 'WEST');
END;

REMOVE_ACL_PARAMETERS Procedure

The REMOVE_ACL_PARAMETERS removes the specified ACL parameter for an ACL. If no parameter name is specified, then all ACL parameters for the ACL are removed.

Syntax

XS_ACL.REMOVE_ACL_PARAMETERS (
  acl        IN VARCHAR2,
  parameter  IN VARCHAR2); 

XS_ACL.REMOVE_ACL_PARAMETERS (
  acl IN VARCHAR2); 

Parameters

Examples

The following example removes the REGION parameter from the ACL1 ACL:

BEGIN
  SYS.XS_ACL.REMOVE_ACL_PARAMETERS('ACL1', 'REGION');
END;

The following example removes all ACL parameters for ACL1.

BEGIN
  SYS.XS_ACL.REMOVE_ACL_PARAMETERS('ACL1');
END;

SET_DESCRIPTION Procedure

The SET_DESCRIPTION procedure sets a description string for an ACL.

Syntax

XS_ACL.SET_DESCRIPTION (
  acl         IN VARCHAR2,
  description IN VARCHAR2);

Parameters

Examples

The following example sets a description for the HRACL ACL:

BEGIN
  SYS.XS_ACL.SET_DESCRIPTION('HRACL','Grants privileges to HR representatives and 
                          managers.');
END;

DELETE_ACL Procedure

The DELETE_ACL procedure deletes the specified ACL.

Syntax

XS_ACL.DELETE_ACL (
  acl           IN VARCHAR2,
  delete_option IN PLS_INTEGER := XS_ADMIN_UTIL.DEFAULT_OPTION);

Parameters

Examples

The following example deletes the HRACL ACL using the default delete option:

BEGIN
  SYS.XS_ACL.DELETE_ACL('HRACL');
END;

GRANT_SYSTEM_PRIVILEGE Procedure

The GRANT_SYSTEM_PRIVILEGE procedure is used to grant a Real Application Security system privilege to a user or role. Only the user with SYS privilege can perform this operation.

Syntax

XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE (
  priv_name      IN VARCHAR2,
  user_name      IN VARCHAR2,
  user_type      IN  PLS_INTEGER := XS_ADMIN_UTIL.PTYPE_DB);

Parameters

Examples

SYS.XS_ADMIN_UTIL.GRANT_SYSTEM_PRIVILEGE('CREATE_USER', 'user1', XS_ADMIN_UTIL.PTYPE_DB);

REVOKE_SYSTEM_PRIVILEGE Procedure

The REVOKE_SYSTEM_PRIVILEGE is used to revoke a Real Application Security system privilege from a user or role. Only the user with SYS privilege can perform this operation.

Syntax

XS_ADMIN_UTIL.REVOKE_SYSTEM_PRIVILEGE (
  priv_name      IN VARCHAR2,
  user_name      IN VARCHAR2,
  user_type      IN  PLS_INTEGER := XS_ADMIN_UTIL.PTYPE_DB);

Parameters

Examples

SYS.XS_ADMIN_UTIL.REVOKE_SYSTEM_PRIVILEGE('DROP_USER','user1', XS_ADMIN_UTIL.PTYPE_DB);

CREATE_POLICY Procedure

The CREATE_POLICY procedure creates a new data security policy.

Syntax

XS_DATA_SECURITY.CREATE_POLICY ( 
  name                   IN VARCHAR2,
  realm_constraint_list  IN XS$REALM_CONSTRAINT_LIST,
  column_constraint_list IN XS$COLUMN_CONSTRAINT_LIST := NULL,
  description            IN VARCHAR2 :=NULL) ;

Parameters

Examples

The following example creates a data security policy called USER1.EMPLOYEES_DS. It uses a data realm constraint to protect data related to department numbers 60 and 100. In addition, access to the SALARY column (attribute) is restricted using an column constraint.

DECLARE
  realm_cons XS$REALM_CONSTRAINT_LIST;      
  column_cons XS$COLUMN_CONSTRAINT_LIST;
BEGIN  
  realm_cons := 
    XS$REALM_CONSTRAINT_LIST(
      XS$REALM_CONSTRAINT_TYPE(realm=> 'DEPARTMENT_ID in (60, 100)',
                               acl_list=> XS$NAME_LIST('HRACL')));
  
  column_cons := 
    XS$COLUMN_CONSTRAINT_LIST(
      XS$COLUMN_CONSTRAINT_TYPE(column_list=> XS$LIST('SALARY'),
                            privilege=> 'VIEW_SENSITIVE_INFO'));
 
  SYS.XS_DATA_SECURITY.CREATE_POLICY(
          name=>'USER1.EMPLOYEES_DS',
          realm_constraint_list=>realm_cons,
          column_constraint_list=>column_cons);
END;

APPEND_REALM_CONSTRAINTS Procedure

The APPEND_REALM_CONSTRAINTS procedure adds one or more data realm constraints to an existing data security policy.

Syntax

XS_DATA_SECURITY.APPEND_REALM_CONSTRAINTS (
  policy           IN VARCHAR2,
  realm_constraint IN XS$REALM_CONSTRAINT_TYPE);

XS_DATA_SECURITY.APPEND_REALM_CONSTRAINTS (
  policy                IN VARCHAR2,
  realm_constraint_list IN XS$REALM_CONSTRAINT_LIST);

Parameters

Examples

The following example appends a new data realm constraint to the EMPLOYEES_DS data security policy.

DECLARE
  realm_cons XS$REALM_CONSTRAINT_TYPE;      
BEGIN  
  realm_cons := 
      XS$REALM_CONSTRAINT_TYPE(realm=> 'DEPARTMENT_ID in (40, 50)',
                               acl_list=> XS$NAME_LIST('HRACL'));
 
  SYS.XS_DATA_SECURITY.APPEND_REALM_CONSTRAINTS(
          policy=>'EMPLOYEES_DS',
          realm_constraint=>realm_cons);
END;

REMOVE_REALM_CONSTRAINTS Procedure

The REMOVE_REALM_CONSTRAINTS procedure removes all data realm constraints from a data security policy.

Syntax

XS_DATA_SECURITY.REMOVE_REALM_CONSTRAINTS (
  policy IN VARCHAR2);

Parameters

Examples

The following example removes all data realm constraints from the EMPLOYEES_DS data security policy.

BEGIN 
  SYS.XS_DATA_SECURITY.REMOVE_REALM_CONSTRAINTS('EMPLOYEES_DS');
END; 

ADD_COLUMN_CONSTRAINTS Procedure

The ADD_COLUMN_CONSTRAINTS procedure adds one or more column constraint to a data security policy.

Syntax

XS_DATA_SECURITY.ADD_COLUMN_CONSTRAINTS (
  policy            IN VARCHAR2,
  column_constraint IN XS$COLUMN_CONSTRAINT_TYPE);

XS_DATA_SECURITY.ADD_COLUMN_CONSTRAINTS (
  policy                 IN VARCHAR2,
  column_constraint_list IN XS$COLUMN_CONSTRAINT_LIST);

Parameters

Examples

The following example adds a column constraint on the COMMISSION_PCT column in the EMPLOYEES_DS data security policy:

DECLARE
  column_cons XS$COLUMN_CONSTRAINT_TYPE;
BEGIN  
  column_cons := 
      XS$COLUMN_CONSTRAINT_TYPE(column_list=> XS$LIST('COMMISSION_PCT'),
                            privilege=> 'VIEW_SENSITIVE_INFO');
 
  SYS.XS_DATA_SECURITY.ADD_COLUMN_CONSTRAINTS(
          policy=>'EMPLOYEES_DS',
          column_constraint=>column_cons);
END;

REMOVE_COLUMN_CONSTRAINTS Procedure

The REMOVE_COLUMN_CONSTRAINTS procedure removes all column constraints from a data security policy.

Syntax

XS_DATA_SECURITY.REMOVE_COLUMN_CONSTRAINTS (
  policy IN VARCHAR2,);

Parameters

Examples

The following example removes all column constraints from the EMPLOYEES_DS data security policy:

BEGIN 
  SYS.XS_DATA_SECURITY.REMOVE_COLUMN_CONSTRAINTS('EMPLOYEES_DS');
END; 

CREATE_ACL_PARAMETER Procedure

The CREATE_ACL_PARAMETER procedure creates an ACL parameter for a data security policy.

Syntax

XS_DATA_SECURITY.CREATE_ACL_PARAMETER (
  policy     IN VARCHAR2,
  parameter  IN VARCHAR2,
  param_type IN NUMBER);

Parameters

Examples

The following examples creates an ACL parameter, called DEPT_POLICY, for the EMPLOYEES_DS data security policy:

BEGIN 
  SYS.XS_DATA_SECURITY.CREATE_ACL_PARAMETER('EMPLOYEES_DS','DEPT_POLICY',1);
END; 

DELETE_ACL_PARAMETER Procedure

The DELETE_ACL_PARAMETER procedure deletes an ACL parameter for a data security policy.

Syntax

XS_DATA_SECURITY.DELETE_ACL_PARAMETER (
  policy                IN VARCHAR2,
  parameter             IN VARCHAR2,
  delete_option         IN PLS_INTEGER := XS_ADMIN_UTIL.DEFAULT_OPTION);

Parameters

Examples

The following example deletes the DEPT_POLICY ACL parameter from the EMPLOYEES_DS data security policy, using the default option.

BEGIN
  SYS.XS_DATA_SECURITY.DELETE_ACL_PARAMETER('EMPLOYEES_DS','DEPT_POLICY',
                                         XS_ADMIN_UTIL.DEFAULT_OPTION);
END; 

SET_DESCRIPTION Procedure

The SET_DESCRPTION procedure sets a description string for the specified data security policy.

Syntax

XS_DATA_SECURITY.SET_DESCRIPTION (
  policy         IN VARCHAR2,
  description    IN VARCHAR2);

Parameters

Examples

The following example sets a description string for the EMPLOYEES_DS data security policy:

BEGIN 
  SYS.XS_DATA_SECURITY.SET_DESCRIPTION('EMPLOYEES_DS',
                                   'Data Security Policy for HR.EMPLOYEES');
END; 

DELETE_POLICY Procedure

The DELETE_POLICY procedure deletes a data security policy.

Syntax

XS_DATA_SECURITY.DELETE_POLICY( 
  policy        IN VARCHAR2,
  delete_option IN PLS_INTEGER := XS_ADMIN_UTIL.DEFAULT_OPTION); 

Parameters

Examples

The following example deletes the EMPLOYEES_DS data security policy using the default option.

BEGIN
  SYS.XS_DATA_SECURITY.DELETE_POLICY('EMPLOYEES_DS',
                                        XS_ADMIN_UTIL.DEFAULT_OPTION); 
END;

ENABLE_OBJECT_POLICY Procedure

The ENABLE_OBJECT_POLICY procedure enables the data security policy for the specified table or view. ENABLE_OBJECT_POLICY enables the ACL-based row level security policy for the table or view.

You may want to enable data security policies after you perform an import or export on the tables that it affects, or for debugging purposes.

To find the status of the data security policies for tables or views available for the current user, query the DBA_XS_APPLIED_POLICIES data dictionary view.

Syntax

XS_DATA_SECURITY.ENABLE_OBJECT_POLICY (
 policy  IN VARCHAR2,
 schema  IN VARCHAR2,
 object  IN VARCHAR2);

Parameters

Examples

The following example enables XDS for the products table in the sales schema.

BEGIN
  SYS.XS_DATA_SECURITY.ENABLE_OBJECT_POLICY(policy =>'CUST_DS', schema=>'sales', object=>'products');
END;

DISABLE_OBJECT_POLICY Procedure

The DISABLE_OBJECT_POLICY procedure disables the data security policy for the specified table or view. DISABLE_OBJECT_POLICY disables the ACL-based row level security policy for the table or view.

You may want to disable Real Application Security if you are performing an import or export on the tables that it affects, or for debugging purposes.

To find the status of the data security policies for tables or views available for the current user, query the DBA_XS_APPLIED_POLICIES data dictionary view.

Syntax

XS_DATA_SECURITY.DISABLE_OBJECT_POLICY (
 policy  IN VARCHAR2,
 schema  IN VARCHAR2,
 object  IN VARCHAR2);

Parameters

Examples

The following example disables XDS for the products table in the sales schema.

BEGIN
  SYS.XS_DATA_SECURITY.DISABLE_OBJECT_POLICY(policy =>'CUST_DS', schema=>'sales', object=>'products');
END;

REMOVE_OBJECT_POLICY Procedure

The REMOVE_OBJECT_POLICY procedure drops the data security policy from the specified table or view without deleting it. REMOVE_OBJECT_POLICY drops the ACL Materialized View built by ENABLE_XDS on a static data realm constraint.

To find the status of the data security policies for tables or views available for the current user, query the DBA_XS_APPLIED_POLICIES data dictionary view.

Syntax

XS_DATA_SECURITY.REMOVE_OBJECT_POLICY (
 policy  IN VARCHAR2,
 schema  IN VARCHAR2,
 object  IN VARCHAR2);

Parameters

Examples

The following example drops the CUST_DS data security policy from the products table in the sales schema.

BEGIN 
  SYS.XS_DATA_SECURITY.REMOVE_OBJECT_POLICY(policy=>'CUST_DS', schema=>'sales', object=>'products');
END;

APPLY_OBJECT_POLICY Procedure

The APPLY_OBJECT_POLICY procedure enables or reenables the data security policy for the specified database table or view.

To find the status of the data security policies for tables or views available for the current user, query the DBA_XS_APPLIED_POLICIES data dictionary view.

Syntax

XS_DATA_SECURITY.APPLY_OBJECT_POLICY (
 policy          IN VARCHAR2,
 schema          IN VARCHAR2, 
 object          IN VARCHAR2, 
 row_acl         IN BOOLEAN DEFAULT FALSE,
 owner_bypass    IN BOOLEAN DEFAULT FALSE,
 statement_types IN VARCHAR2 DEFAULT NULL,
 aclmv           IN VARCHAR2 DEFAULT NULL );

Parameters

Examples

The following example enables the DEPT_POLICY data security policy for the EMP table in the HR schema.

BEGIN
  sys.xs_data_security.apply_object_policy(
           policy => 'HR.EMPLOYEES_DS',
           schema => 'HR',
           object => 'EMPLOYEES',
           statement_types => 'SELECT',
           owner_bypass => true);
END;

SCHEDULE_STATIC_ACL_REFRESH Procedure

The SCHEDULE_STATIC_ACL_REFRESH procedure is used to invoke or schedule automatic refresh for static ACL to a user table. It can start the refresh immediately if NULL value is passed into the start_date and repeat_interval parameters.

To find the status of all latest static ACL refresh jobs done for tables or views available for the current user, query the ALL_XDS_LATEST_ACL_REFSTAT, DBA_XDS_LATEST_ACL_REFSTAT, and USER_XDS_LATEST_ACL_REFSTAT data dictionary views. All static ACL refresh job status history can be found in ALL_XDS_ACL_REFSTAT, DBA_XDS_ACL_REFSTAT, and USER_XDS_ACL_REFSTAT data dictionary views.

Syntax

XS_DATA_SECURITY_UTIL.SCHEDULE_STATIC_ACL_REFRESH (
  schema_name      IN VARCHAR2 DEFAULT NULL,
  table_name       IN VARCHAR2,
  start_date       IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
  repeat_interval  IN VARCHAR2 DEFAULT NULL,
  comments         IN VARCHAR2 DEFAULT NULL );

Parameters

Examples

SYS.XS_DATA_SECURITY_UTIL.SCHEDULE_STATIC_ACL_REFRESH('aclmvuser', 'sales', SYSTIMESTAMP, 'freq=hourly; interval=2');

ALTER_STATIC_ACL_REFRESH Procedure

The ALTER_STATIC_ACL_REFRESH procedure is used to change the ACL refresh mode to on-commit or on-demand refresh.

Syntax

XS_DATA_SECURITY_UTIL.ALTER_STATIC_ACL_REFRESH (
  schema_name      IN VARCHAR2 DEFAULT NULL,
  table_name       IN VARCHAR2,
  refresh_mode     IN VARCHAR2);

Parameters

Examples

SYS.XS_DATA_SECURITY_UTIL.ALTER_STATIC_ACL_REFRESH('aclmvuser','sales', refresh_mode=>'ON COMMIT');

VALIDATE_PRINCIPAL Function

The VALIDATE_PRINCIPAL function validates the principal. This function returns TRUE if the object is valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

Syntax

validate_principal(name         IN VARCHAR2, 
                   error_limit  IN PLS_INTEGER := 1) 
   RETURN BOOLEAN;

Parameters

Examples

Validate the principal, user user1, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_principal('user1', 100) then
    dbms_output.put_line('The user is valid.');
  else
    dbms_output.put_line('The user is invalid.');
  end if;
end;
/
select * from xs$validation_table;

Validate the principal, role role1, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_principal('role1', 100) then
    dbms_output.put_line('The role is valid.');
  else
    dbms_output.put_line('The role is invalid.');
  end if;
end;
/
select * from xs$validation_table;

VALIDATE_SECURITY_CLASS Function

The VALIDATE_SECURITY_CLASS function validates the security class. This function returns TRUE if the object is valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

Syntax

validate_security_class(name         IN VARCHAR2, 
                        error_limit  IN PLS_INTEGER := 1)
   RETURN BOOLEAN;

Parameters

Examples

Validate the security class, sec1, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_security_class('sec1', 100) then
    dbms_output.put_line('The security class is valid.');
  else
    dbms_output.put_line('The security class is invalid.');
  end if;
end;
/
select * from xs$validation_table;

VALIDATE_ACL Function

The VALIDATE_ACL function validates the ACL. This function returns TRUE if the object is valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

Syntax

validate_acl(name         IN VARCHAR2, 
             error_limit  IN PLS_INTEGER := 1) 
   RETURN BOOLEAN;

Parameters

Examples

Validate the ACL, acl1, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_acl('acl1', 100) then
    dbms_output.put_line('The ACL is valid.');
  else
    dbms_output.put_line('The ACL is invalid.');
  end if;
end;
/
select * from xs$validation_table;

VALIDATE_DATA_SECURITY Function

The VALIDATE_DATA_SECURITY function validates the data security. This function returns TRUE if the object is valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

This function has three styles of policy validation.

• When policy is not NULL and table_name is NULL, the function validates the policy against all the tables to which the policy is applied. Note that when table_name is NULL, table_owner is ignored even if it is not NULL.

• When both policy and table_name are not NULL, the function validates the policy against the specific table. If table_owner is not provided, the current schema is used.

• When policy is NULL and table_name is not NULL, the function validates all policies applied to the table against the table. If table_owner is not provided, the current schema is used.

Syntax

validate_data_security(policy       IN VARCHAR2 :=NULL,
                       table_owner  IN VARCHAR2 :=NULL,
                       table_name   IN VARCHAR2 :=NULL,
                       error_limit  IN PLS_INTEGER := 1) 
   RETURN BOOLEAN;

Parameters

Examples

Validate a policy, policy1 on all the applied tables, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_data_security(policy      => 'policy1',
                                    error_limit => 100) then
    dbms_output.put_line('The policy is valid on all the applied tables.');
  else
    dbms_output.put_line('The policy is invalid on some of the applied tables.');
  end if;
end;
/
select * from xs$validation_table;

Validate a policy, policy1 on a given table, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_data_security(policy      => 'policy1',
                                    table_owner => 'HR',
                                    table_name  => 'EMPLOYEES',
                                    error_limit => 100) then
    dbms_output.put_line('The policy is valid on the table.');
  else
    dbms_output.put_line('The policy is invalid on the table.');
  end if;
end;
/
select * from xs$validation_table;

Validate all the policies applied to a given table, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_data_security(table_owner => 'HR',
                                    table_name  => 'EMPLOYEES',
                                    error_limit => 100) then
    dbms_output.put_line('All the applied policies on the table are valid.');
  else
    dbms_output.put_line('Some applied policies on the table are invalid');
  end if;
end;
/
select * from xs$validation_table;

VALIDATE_NAMESPACE_TEMPLATE Function

The VALIDATE_NAMESPACE_TEMPLATE function validates the namespace. This function returns TRUE if the object is valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

Syntax

validate_namespace_template(name         IN VARCHAR2,
                            error_limit  IN PLS_INTEGER := 1)
   RETURN BOOLEAN;

Parameters

Examples

Validate the namespace, ns1, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_namespace_template('ns1', 100) then
    dbms_output.put_line('The namespace template is valid.');
  else
    dbms_output.put_line('The namespace template is invalid.');
  end if;
end;
/
select * from xs$validation_table;

VALIDATE_WORKSPACE Function

The VALIDATE_WORKSPACE function validates all the artifacts, in other words, it validates all objects that exist in the work space by using this one function. This function returns TRUE if all the objects are valid; otherwise, it returns FALSE. For each identified inconsistency, a row is inserted into the XS$VALIDATION_TABLE validation table until the maximum number of inconsistencies that can be stored is reached. Users must query this validation table to find out what caused the validation failure.

Syntax

validate_workspace(error_limit  IN PLS_INTEGER := 1)
   RETURN BOOLEAN;

Parameters

Examples

Validate all the objects in the workspace, then query the validation table in case there are inconsistencies.

begin
  if sys.xs_diag.validate_workspace(100) then
    dbms_output.put_line('The objects are valid.');
  else
    dbms_output.put_line('The objects are invalid.');
  end if;
end;
/
select * from xs$validation_table;

CREATE_TEMPLATE Procedure

The CREATE_TEMPLATE procedure creates a new namespace template.

Syntax

XS_NAMESPACE.CREATE_TEMPLATE (
  name             IN VARCHAR2,
  attr_list        IN XS$NS_ATTRIBUTE_LIST := NULL,
  schema           IN VARCHAR2 := NULL,
  package          IN VARCHAR2 := NULL,
  function         IN VARCHAR2 := NULL,
  acl              IN VARCHAR2 := 'SYS.NS_UNRESTRICTED_ACL'
  description      IN VARCHAR2 := NULL);

Parameters

Examples

The following example creates a namespace template called POAttrs. The namespace template contains a list of attributes defined by attrlist. The handler function for the namespace template is called Populate_Order_Func. This handler function is part of the Orders_Pckg package, which is contained in the SCOTT schema. The namespace template has NS_UNRESTRICTED_ACL set on the template, which allows unrestricted operation on namespaces created from the template.

DECLARE
  attrlist XS$NS_ATTRIBUTE_LIST;
BEGIN
  attrlist := XS$NS_ATTRIBUTE_LIST();
  attrlist.extend(2);
  attrlist(1) := XS$NS_ATTRIBUTE('desc', 'general');
  attrlist(2) := XS$NS_ATTRIBUTE(name=>'item_no',
                 attribute_events=>XS_NAMESPACE.FIRSTREAD_EVENT);
  SYS.XS_NAMESPACE.CREATE_TEMPLATE('POAttrs', attrlist, 'SCOTT',
                               'Orders_Pckg','Populate_Order_Func',
                               'SYS.NS_UNRESTRICTED_ACL',
                               'Purchase Order Attributes');
END;

ADD_ATTRIBUTES Procedure

The ADD_ATTRIBUTES procedure adds one or more attributes to an existing namespace template.

Syntax

XS_NAMESPACE.ADD_ATTRIBUTES ( 
  template         IN VARCHAR2,
  attribute        IN VARCHAR2,
  default_value    IN VARCHAR2 := NULL,
  attribute_events IN PLS_INTEGER := XS_NAMESPACE.NO_EVENT);

XS_NAMESPACE.ADD_ATTRIBUTES ( 
  template  IN VARCHAR2,
  attr_list IN XS$NS_ATTRIBUTE_LIST); 

Parameters

Examples

The following example adds an attribute called item_type to the POAttrs namespace. It also specifies a default value and attribute event for the new attribute that is added.

BEGIN
  SYS.XS_NAMESPACE.ADD_ATTRIBUTES(template=>'POAttrs',attribute=>'item_type',
                                default_value=>'generic',
                                attribute_events=>XS_NAMESPACE.update_event);
END;

REMOVE_ATTRIBUTES Procedure

The REMOVE_ATTRIBUTES procedure removes one or more attributes from a namespace template. If no attribute names are specified, then all attributes are removed from the namespace template.

Syntax

XS_NAMESPACE.REMOVE_ATTRIBUTES ( 
  template  IN VARCHAR2,
  attribute IN VARCHAR2); 

XS_NAMESPACE.REMOVE_ATTRIBUTES ( 
  template  IN VARCHAR2,
  attr_list IN XS$LIST); 

XS_NAMESPACE.REMOVE_ATTRIBUTES ( 
  template   IN VARCHAR2); 

Parameters

Examples

The following example removes the item_type attribute from the POAttrs namespace.

BEGIN
  SYS.XS_NAMESPACE.REMOVE_ATTRIBUTES('POAttrs','item_type');
END;

The following example removes all attributes from the POAttrs namespace template.

BEGIN
  SYS.XS_NAMESPACE.REMOVE_ATTRIBUTES('POAttrs');
END;

SET_HANDLER Procedure

The SET_HANDLER procedure assigns a handler function for the specified namespace template.

Syntax

XS_NAMESPACE.SET_HANDLER (
  template         IN VARCHAR2,
  schema           IN VARCHAR2,
  package          IN VARCHAR2,
  function         IN VARCHAR2);

Parameters

Examples

The following example sets a handler function, called Populate_Order_Func, for the POAttrs namespace template.

BEGIN
  SYS.XS_NAMESPACE.SET_HANDLER('POAttrs','SCOTT',
                             'Orders_Pckg','Populate_Order_Func');
END;

SET_DESCRIPTION Procedure

The SET_DESCRIPTION procedure sets a description string for the specified namespace template.

Syntax

XS_NAMESPACE.SET_DESCRIPTION (
  template     IN VARCHAR2,
  description  IN VARCHAR2);

Parameters

Examples

The following example sets a description string for the POAttrs namespace template.

BEGIN
  SYS.XS_NAMESPACE.SET_DESCRIPTION('POAttrs','Purchase Order Attributes');
END;

DELETE_TEMPLATE Procedure

The DELETE_TEMPLATE procedure deletes the specified namespace template.

Syntax

XS_NAMESPACE.DELETE_TEMPLATE( 
  template      IN VARCHAR2,
  delete_option IN PLS_INTEGER := XS_ADMIN_UTIL.DEFAULT_OPTION); 

Parameters

Examples

The following example deletes the POAttrs namespace template using the default delete option.

BEGIN
  SYS.XS_NAMESPACE.DELETE_TEMPLATE('POAttrs',XS_ADMIN_UTIL.DEFAULT_OPTION);
END;

CREATE_USER Procedure

The CREATE_USER procedure creates a new application user. You need the CREATE USER system privilege to create an application user.

You can use the DBA_XS_USERS data dictionary view to get a list of all application users.

Syntax

CREATE_USER ( 
  name            IN VARCHAR2,
  schema          IN VARCHAR2    := NULL,
  status          IN PLS_INTEGER := ACTIVE,
  start_date      IN TIMESTAMP WITH TIME ZONE  := NULL,
  end_date        IN TIMESTAMP WITH TIME ZONE  := NULL,
  guid            IN RAW         := NULL,
  external_source IN VARCHAR2    := NULL,
  description     IN VARCHAR2    := NULL); 

Parameters

Examples

The following example creates a user:

BEGIN
 XS_PRINCIPAL.CREATE_USER('TEST1');
END;

The following example creates a user, and also specifies a schema and start date for the user:

DECLARE 
st_date TIMESTAMP WITH TIME ZONE;
BEGIN
  st_date := TO_TIMESTAMP_TZ('2010-06-18 11:00:00 -5:00','YYYY-MM-DD HH:MI:SS
  TZH:TZM');
  SYS.XS_PRINCIPAL.CREATE_USER(name=>'u2',
                           schema=>'scott',
                           start_date=>st_date);
END;

CREATE_ROLE Procedure

The CREATE_ROLE procedure creates a new application role. You need the CREATE ROLE system privilege to create a regular application role.

You can use the DBA_XS_ROLES data dictionary view to get the list of application roles together with their attributes, like start date and end date

Syntax

CREATE_ROLE (   name            IN VARCHAR2,
  enabled         IN BOOLEAN  := FALSE,
  start_date      IN TIMESTAMP WITH TIME ZONE := NULL,
  end_date        IN TIMESTAMP WITH TIME ZONE := NULL,
  guid            IN RAW      := NULL,
  external_source IN VARCHAR2 := NULL,
  description     IN VARCHAR2 := NULL); 

Parameters

Examples

The following example creates an application role, called hrmgr:

BEGIN
  SYS.XS_PRINCIPAL.CREATE_ROLE('hrmgr');
END;

The following example creates an application role called hrrep. It also enables the role, and assigns the current date as start date for the role.

DECLARE 
  st_date TIMESTAMP WITH TIME ZONE;
BEGIN
  st_date := SYSTIMESTAMP;
  SYS.XS_PRINCIPAL.CREATE_ROLE(name=>'hrrep',
                           enabled=>true,
                           start_date=>st_date);
END;

CREATE_DYNAMIC_ROLE Procedure

The CREATE_DYNAMIC_ROLE procedure creates a new dynamic application role. Dynamic application roles can be dynamically enabled or disabled by an application, based on the criteria defined by the application. You need the CREATE ROLE system privilege to create an dynamic application role.

You can use the DBA_XS_DYNAMIC_ROLES data dictionary view to get a list of all dynamic application roles together with their attributes, like duration.

Syntax

CREATE_DYNAMIC_ROLE (
  name        IN VARCHAR2,
  duration    IN PLS_INTEGER := NULL, 
  scope       IN PLS_INTEGER := XS_PRINCIPAL.SESSION_SCOPE,
  description IN VARCHAR2    := NULL);

Parameters

Examples

The following example creates a dynamic application role, called sslrole:

BEGIN
  SYS.XS_PRINCIPAL.CREATE_DYNAMIC_ROLE('sslrole');
END;

The following example creates a dynamic application role called reprole. It also specifies a duration of 100 minutes for the role, and chooses the request scope for the role.

BEGIN
  SYS.XS_PRINCIPAL.CREATE_DYNAMIC_ROLE(name=>'reprole',
                                   duration=>100,
                                   scope=>XS_PRINCIPAL.REQUEST_SCOPE);
END;

GRANT_ROLES Procedure

The GRANT_ROLES procedure grants one or more application roles to an application principal. You need the GRANT ANY ROLE system privilege to grant application roles.

You can use the DBA_XS_ROLE_GRANTS data dictionary view to get the list of all role grants together with their details, like start date and end date.

Syntax

GRANT_ROLES (
grantee       IN VARCHAR2,
role          IN VARCHAR2,
start_date    IN TIMESTAMP WITH TIME ZONE:= NULL,
end_date      IN TIMESTAMP WITH TIME ZONE:= NULL,);

GRANT_ROLES (
grantee   IN VARCHAR2,
role_list IN XS$ROLE_GRANT_LIST);

Parameters

Examples

The following example grants the HRREP role to user SMAVRIS with a start date and an end date specified:

DECLARE 
  st_date TIMESTAMP WITH TIME ZONE;
  end_date TIMESTAMP WITH TIME ZONE;
BEGIN
  st_date := TO_TIMESTAMP_TZ('2010-06-18 11:00:00 -5:00','YYYY-MM-DD HH:MI:SS
                              TZH:TZM');
  end_date := TO_TIMESTAMP_Tz('2011-06-18 11:00:00 -5:00','YYYY-MM-DD HH:MI:SS
                               TZH:TZM');
  SYS.XS_PRINCIPAL.GRANT_ROLES('SMAVRIS', 'HRREP', st_date, end_date);
END;

The following example grants the HRREP and HRMGR roles to user SMAVRIS:

DECLARE 
  rg_list XS$ROLE_GRANT_LIST; 
BEGIN
  rg_list := XS$ROLE_GRANT_LIST(XS$ROLE_GRANT_TYPE('HRREP'),
                                XS$ROLE_GRANT_TYPE('HRMGR'));
 
  SYS.XS_PRINCIPAL.GRANT_ROLES('SMAVRIS', rg_list);
END;

REVOKE_ROLES Procedure

The REVOKE_ROLES procedure revokes the specified role(s) from the specified grantee. If no roles are specified, then all application roles are revoked from the grantee.You need the GRANT ANY ROLE system privilege to grant or revoke roles.

You can use the DBA_XS_ROLE_GRANTS data dictionary view to get the list of all role grants together with their details, like start date and end date.

Syntax

REVOKE_ROLES (
  grantee   IN VARCHAR2,
  role      IN VARCHAR2);

REVOKE_ROLES (
  grantee   IN VARCHAR2,
  role_list IN XS$NAME_LIST); 

REVOKE_ROLES (
  grantee IN VARCHAR2);

Parameters

Examples

The following example revokes the HRREP role from user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.REVOKE_ROLES('SMAVRIS','HRREP');
END;

The following example revokes the HRREP and HRMGR roles from user SMAVRIS:

DECLARE
  role_list XS$NAME_LIST; 
BEGIN
  role_list := XS$NAME_LIST('HRREP','HRMGR');
  SYS.XS_PRINCIPAL.REVOKE_ROLES('SMAVRIS', role_list);
END;

The following example revokes all granted roles from user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.REVOKE_ROLES('SMAVRIS');
END;

ADD_PROXY_USER Procedure

The ADD_PROXY_USER adds a target user for the specified application user. This allows the application user to proxy as the target user. There are two signatures for this procedure. The first signature allows you to specify a subset of roles of the target user using the target_roles parameter that are to be assigned to the proxy user. For the second signature there is no target_roles parameter, so all roles of the target user are assigned to the proxy user.

You need the ALTER USER system privilege to add or remove a proxy user.

Syntax

ADD_PROXY_USER (
  target_user  IN VARCHAR2,
  proxy_user   IN VARCHAR2,
  target_roles IN XS$NAME_LIST);

ADD_PROXY_USER (
  target_user  IN VARCHAR2,
  proxy_user   IN VARCHAR2);

Parameters

Examples

The following example enables user DJONES to proxy as target user SMAVRIS. The target roles granted to DJONES are HRREP and HRMGR.

DECLARE
  pxy_roles XS$NAME_LIST; 
BEGIN
  pxy_roles := XS$NAME_LIST('HRREP','HRMGR');
  SYS.XS_PRINCIPAL.ADD_PROXY_USER('SMAVRIS','DJONES', pxy_roles);
END;

The following example passes an explicit NULL value for the target role; in other words, it assigns no roles of the target user 'SMAVRIS' to the proxy user 'DJONES'.

BEGIN
  SYS.XS_PRINCIPAL.ADD_PROXY_USER('SMAVRIS','DJONES', NULL);
END;

The following example assigns all roles of target user 'SMAVRIS' to proxy user 'DJONES'.

BEGIN
  SYS.XS_PRINCIPAL.ADD_PROXY_USER('SMAVRIS','DJONES');
END;

REMOVE_PROXY_USERS Procedure

The REMOVE_PROXY_USERS procedure disassociates one or all proxy users for a target application user. The associated proxy roles are automatically removed for the proxy users.

You need the ALTER USER system privilege to add or remove a proxy user.

Syntax

REMOVE_PROXY_USERS (
  target_user  IN VARCHAR2); 

REMOVE_PROXY_USERS (
  target_user IN VARCHAR2,
  proxy_user  IN VARCHAR2);

Parameters

Examples

The following example removes all proxy users for target user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.REMOVE_PROXY_USERS('SMAVRIS');
END;

The following example disassociates the proxy user DJONES from the target user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.REMOVE_PROXY_USERS('SMAVRIS','DJONES');
END;

ADD_PROXY_TO_DBUSER

The ADD_PROXY_TO_DBUSER adds the specified target proxy application user to the specified database user. The application user must be a direct logon user. This allows the application user to proxy as the target database user. By default, all roles assigned to the target user can be used by the proxy user. Similar to Oracle Database, the default roles of the target database users would be enabled after connection. Other roles assigned to the target database user can be set by using the SET ROLE statement.

You need the ALTER USER system privilege to add a proxy user to a database user.

Syntax

ADD_PROXY_TO_DBUSER (
  database_user  IN VARCHAR2,
  proxy_user     IN VARCHAR2,
  is_external    IN BOOLEAN := FALSE);

Parameters

Examples

The following example enables application user DJONES to proxy as target database user SMAVRIS.

BEGIN
  SYS.XS_PRINCIPAL.ADD_PROXY_TO_DBUSER('SMAVRIS','DJONES', TRUE);
END;

REMOVE_PROXY_FROM_DBUSER

The REMOVE_PROXY_FROM_DBUSER procedure disassociates a proxy application user from a database user. The associated proxy roles are automatically removed from the application user.

You need the ALTER USER system privilege to remove a proxy user from a database user.

Syntax

REMOVE_PROXY_FROM_DBUSER (
  database_user IN VARCHAR2,
  proxy_user    IN VARCHAR2);

Parameters

Examples

The following example disassociates the proxy user DJONES from the target database user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.REMOVE_PROXY_FROM_DBUSER('SMAVRIS','DJONES');
END;

SET_EFFECTIVE_DATES Procedure

The SET_EFFECTIVE_DATES procedure sets or modifies the effective dates for an application user or role. If the start_date and end_date values are specified as NULL by default, then the application user is not currently effective, so the session for the particular application user cannot be created.

You need the ALTER USER system privilege to run this procedure for an application user. You need the ALTER ANY ROLE system privilege to run this procedure for an application role.

Syntax

SET_EFFECTIVE_DATES (
  principal         IN VARCHAR2,
  start_date        IN TIMESTAMP WITH TIME ZONE:= NULL,
  end_date          IN TIMESTAMP WITH TIME ZONE:= NULL);

Parameters

Examples

The following example sets the effective dates for user DJONES.

DECLARE 
  st_date TIMESTAMP WITH TIME ZONE;
  end_date TIMESTAMP WITH TIME ZONE;
BEGIN
  st_date := TO_TIMESTAMP_TZ('2010-06-18 11:00:00 -5:00','YYYY-MM-DD HH:MI:SS
                              TZH:TZM');
  end_date := TO_TIMESTAMP_Tz('2011-06-18 11:00:00 -5:00','YYYY-MM-DD HH:MI:SS
                               TZH:TZM');
  SYS.XS_PRINCIPAL.SET_EFFECTIVE_DATES(principal=>'DJONES', 
                                   start_date=>st_date,end_date=>end_date);
END;

SET_DYNAMIC_ROLE_DURATION Procedure

The SET_DYNAMIC_ROLE_DURATION procedure sets or modifies the duration for a dynamic application role. The duration is specified in minutes.

You need the ALTER ANY ROLE system privilege to modify a role.

Syntax

SET_DYNAMIC_ROLE_DURATION (
  role      IN VARCHAR2,
  duration  IN PLS_INTEGER);

Parameters

Examples

The following example sets the duration of the reprole dynamic application role to 60 minutes.

BEGIN
  SYS.XS_PRINCIPAL.SET_DYNAMIC_ROLE_DURATION('reprole',60);
END;

SET_DYNAMIC_ROLE_SCOPE Procedure

The SET_DYNAMIC_ROLE_SCOPE procedure sets or modifies the scope of a dynamic application role. The session (SESSION_SCOPE) or request (REQUEST_SCOPE) scopes can be chosen.

You need the ALTER ANY ROLE system privilege to modify a role.

Syntax

SET_DYNAMIC_ROLE_SCOPE (
  role      IN VARCHAR2,
  scope     IN PLS_INTEGER);

Parameters

Examples

The following example sets the scope of the reprole dynamic application role to request scope:

BEGIN
  SYS.XS_PRINCIPAL.SET_DYNAMIC_ROLE_SCOPE('reprole',XS_PRINCIPAL.REQUEST_SCOPE);
END;

ENABLE_BY_DEFAULT Procedure

The ENABLE_BY_DEFAULT procedure enables or disables a regular application role.

If enabled, then the application role is automatically enabled for the principal to which it is granted. If disabled, then the privileges associated with the application role are not enabled even if the application role is granted to a principal.

You need the ALTER ANY ROLE system privilege to modify an application role.

Syntax

ENABLE_BY_DEFAULT ( 
  role       IN VARCHAR2,
  enabled    IN BOOLEAN := TRUE);

Parameters

Examples

The following example sets the enabled attribute for the HRREP application role to TRUE:

BEGIN
  SYS.XS_PRINCIPAL.ENABLE_BY_DEFAULT('HRREP',TRUE);
END;

ENABLE_ROLES_BY_DEFAULT Procedure

The ENABLE_ROLES_BY_DEFAULT procedure enables or disables all application roles that have been directly granted to an application user.

You need the ALTER USER system privilege to run this procedure for an application user.

Syntax

ENABLE_ROLES_BY_DEFAULT (
  user       IN VARCHAR2,
  enabled    IN BOOLEAN := TRUE);

Parameters

Examples

The following example enables all directly granted roles for application user SMAVRIS:

BEGIN
  SYS.XS_PRINCIPAL.ENABLE_ROLES_BY_DEFAULT('SMAVRIS',TRUE);
END;

SET_USER_SCHEMA Procedure

The SET_USER_SCHEMA procedure sets the database schema for an application user.

You need the ALTER USER system privilege to run this procedure for an application user.

Syntax

SET_USER_SCHEMA (
  user        IN VARCHAR2,
  schema      IN VARCHAR2);

Parameters

Examples

The following example associates the HR schema with user DJONES.

BEGIN
  SYS.XS_PRINCIPAL.SET_USER_SCHEMA('DJONES','HR');
END;

SET_GUID Procedure

The SET_GUID procedure sets the GUID for a principal. The principal must be an external user or role, and the current GUID must be NULL.

You need the ALTER USER system privilege to run this procedure for an application user. You need the ALTER ANY ROLE system privilege to run this procedure for an application role.

Syntax

SET_GUID (
  principal IN VARCHAR2,
  guid      IN RAW);

Parameters

Examples

The following example sets a GUID for user Alex:

BEGIN
  SYS.XS_PRINCIPAL.SET_GUID('ALEX','7b6cb3a98f8a4e20ac31a37419cc7fa3');
END;

SET_PROFILE Procedure

The SET_PROFILE procedure sets the application user's profile. The profile is a set of resource limits and password parameters that restrict database usage and database instance resources for a Real Application Security application user. Both the application user and the profile must be existing entities.

The user executing this procedure must have the ALTER_USER privilege.

If a profile that is assigned to an application user is dropped using the cascade option, then the default profile would automatically become activated for that user.

Syntax

SET_PROFILE (
  user     IN VARCHAR2,
  profile  IN VARCHAR2);

Parameters

Examples

The following example creates a profile named prof and then sets the profile named prof to an application user named xsuser.

CREATE PROFILE prof LIMIT PASSWORD_REUSE_TIME 1/1440 PASSWORD_REUSE_MAX 3 PASSWORD_VERIFY_FUNCTION Verify_Pass;

BEGIN
  SYS.XS_PRINCIPAL.SET_PROFILE('xsuser','prof');
END;

SET_USER_STATUS Procedure

The SET_USER_STATUS procedure sets or modifies the status of an application user account.

You need the ALTER_USER privilege to run this procedure for an application user.

Syntax

SET_USER_STATUS (
  user        IN VARCHAR2,
  status      IN PLS_INTEGER);

Parameters

Examples

The following example sets the user status to LOCKED for user DJONES.

BEGIN
  SYS.XS_PRINCIPAL.SET_USER_STATUS('DJONES',XS_PRINCIPAL.LOCKED);
END;

SET_PASSWORD Procedure

The SET_PASSWORD procedure sets or modifies the password for an application user account. When you use the SET_PASSWORD procedure, it creates a verifier for you based on the password and the type parameter and then inserts the verifier and the value of the type parameter into the dictionary table.

A direct login Real Application Security user can change his or her own password by providing its value using the oldpass parameter. If value of the old password is incorrect, then the failed login count is incremented with each attempt, returning an ORA-28008: invalid old password error. The new password is not set until the old supplied password is correct.

You need the ALTER_USER privilege to run this procedure for an application user or if you are changing the password of other Real Application Security users.

Native Real Application Security users synchronized from external ID stores are not allowed to change their own password. These users must change their password in the originating ID store.

The SET_PASSWORD operation and the SQL*Plus PASSWORD command are both blocked on the logical standby database.

Syntax

SET_PASSWORD (
  user      IN VARCHAR2,
  password  IN VARCHAR2,
  type      IN PLS_INTEGER := XS_SHA512,
  opassword IN VARCHAR2 :=NULL);

Parameters

Examples

The following example sets a password for application user SMAVRIS. It also specifies the XS_SHA512 verifier type for the password.

BEGIN
  SYS.XS_PRINCIPAL.SET_PASSWORD('SMAVRIS','2Hrd2Guess',XS_PRINCIPAL.XS_SHA512);
END;

SET_VERIFIER Procedure

The SET_VERIFIER procedure sets or modifies the verifier for an application user account. When you use the SET_VERIFIER procedure, the procedure directly inserts the verifier and the value of the type parameter into the dictionary table. This enables administrators to migrate users into Real Application Security with knowledge of the verifier and not the password.

You need the ALTER_USER privilege to run this procedure for an application user.

The SET_VERIFIER operation and the SQL*Plus PASSWORD command are both blocked on the logical standby database.

Syntax

set_verifier ( 
  user      IN VARCHAR2,
  verifier  IN VARCHAR2,
  type      IN PLS_INTEGER := XS_SHA512);

Parameters

Examples

The following example sets a verifier for the user SMAVRIS.

BEGIN
  SYS.XS_PRINCIPAL.SET_VERIFIER('SMAVRIS','6DFF060084ECE67F',XS_PRINCIPAL.XS_SHA512);
END;

SET_DESCRIPTION Procedure

The SET_DESCRIPTION procedure is used to set the description for an application principal.

You need the ALTER USER system privilege to run this procedure for an application user. You need the ALTER ANY ROLE system privilege to run this procedure for an application role.

Syntax

SET_DESCRIPTION (  principal   IN VARCHAR2,  description IN VARCHAR2);

Parameters

Examples

The following example sets a description for the application role HRREP:

BEGIN
  SYS.XS_PRINCIPAL.SET_DESCRIPTION('HRREP','HR Representative role');
END;

DELETE_PRINCIPAL Procedure

The DELETE_PRINCIPAL procedure drops an application user or application role.

You need the DROP USER system privilege to run this procedure for an application user. You need the DROP ANY ROLE system privilege to run this procedure for an application role.

Syntax

delete_principal (
  principal     IN VARCHAR2,
  delete_option IN PLS_INTEGER:=XS_ADMIN_UTIL.DEFAULT_OPTION);

Parameters

Examples

The following example deletes the user SMAVRIS using the DEFAULT_OPTION:

BEGIN
  SYS.XS_PRINCIPAL.DELETE_PRINCIPAL('SMAVRIS');
END;

CREATE_SECURITY_CLASS Procedure

The CREATE_SECURITY_CLASS creates a new security class.

Syntax

XS_SECURITY_CLASS.CREATE_SECURITY_CLASS ( 
  name         IN VARCHAR2,
  priv_list    IN XS$PRIVILEGE_LIST,
  parent_list  IN XS$NAME_LIST := NULL,
  description  IN VARCHAR2 := NULL);

Parameters

Examples

The following example creates a security class called HRPRIVS. The security class includes a set of privileges defined in priv_list. The security class uses the DML class as its parent security class.

DECLARE
  pr_list  XS$PRIVILEGE_LIST;
BEGIN
  pr_list :=XS$PRIVILEGE_LIST(
     XS$PRIVILEGE(name=>'VIEW_SENSITIVE_INFO'),
     XS$PRIVILEGE(name=>'UPDATE_INFO',
                  implied_priv_list=>XS$NAME_LIST
                  ('"UPDATE"', '"DELETE"', '"INSERT"')));
 
  SYS.XS_SECURITY_CLASS.CREATE_SECURITY_CLASS(
     name=>'HRPRIVS', 
     priv_list=>pr_list,
     parent_list=>XS$NAME_LIST('DML'));
END;

ADD_PARENTS Procedure

The ADD_PARENTS procedure adds one or more parent security classes for the specified security class.

Syntax

XS_SECURITY_CLASS.ADD_PARENTS (
  sec_class   IN VARCHAR2,
  parent      IN VARCHAR2);

XS_SECURITY_CLASS.ADD_PARENTS (
  sec_class   IN VARCHAR2,
  parent_list IN XS$NAME_LIST);

Parameters

Examples

The following example adds the parent security class GENPRIVS to the HRPRIVS security class.

BEGIN
  SYS.XS_SECURITY_CLASS.ADD_PARENTS('HRPRIVS','GENPRIVS');
END;

REMOVE_PARENTS Procedure

The REMOVE_PARENTS procedure removes one or more parent classes for the specified security class.

Syntax

XS_SECURITY_CLASS.REMOVE_PARENTS (
  sec_class IN VARCHAR2);

XS_SECURITY_CLASS.REMOVE_PARENTS (
  sec_class IN VARCHAR2,
  parent    IN VARCHAR2);

XS_SECURITY_CLASS.REMOVE_PARENTS (
  sec_class   IN VARCHAR2,
  parent_list IN XS$NAME_LIST);

Parameters

Examples

The following example removes the parent security class GENPRIVS from the HRPRIVS security class.

BEGIN
  SYS.XS_SECURITY_CLASS.REMOVE_PARENTS('HRPRIVS','GENPRIVS');
END;

ADD_PRIVILEGES Procedure

The ADD_PRIVILEGES procedure adds one or more privileges to a security class.

Syntax

XS_SECURITY_CLASS.ADD_PRIVILEGES (
  sec_class         IN VARCHAR2,
  priv              IN VARCHAR2,
  implied_priv_list IN XS$NAME_LIST := NULL,
  description       IN VARCHAR2 := NULL);

XS_SECURITY_CLASS.ADD_PRIVILEGES (
  sec_class  IN VARCHAR2,
  priv_list  IN XS$PRIVILEGE_LIST);

Parameters

Examples

The following example adds an aggregate privilege called UPDATE_INFO to the HRPRIVS security class. The aggregate privilege contains the implied privileges, UPDATE, DELETE, and INSERT.

BEGIN
  SYS.XS_SECURITY_CLASS.ADD_PRIVILEGES(sec_class=>'HRPRIVS',priv=>'UPDATE_INFO',
                                   implied_priv_list=>XS$NAME_LIST('"UPDATE"',
                                                    '"DELETE"', '"INSERT"'));
END;

REMOVE_PRIVILEGES Procedure

The REMOVE_PRIVILEGES procedure removes one or more privileges from the specified security class. If no privilege name or list is specified, then all privileges are removed from the specified security class.

Syntax

XS_SECURITY_CLASS.REMOVE_PRIVILEGES (
  sec_class   IN VARCHAR2,
  priv        IN VARCHAR2);

XS_SECURITY_CLASS.REMOVE_PRIVILEGES (
  sec_class    IN VARCHAR2,
  priv_list    IN XS$NAME_LIST);

XS_SECURITY_CLASS.REMOVE_PRIVILEGES (
  sec_class IN VARCHAR2);

Parameters

Examples

The following example removes the UPDATE_INFO privilege from the HRPRIVS security class.

BEGIN
  SYS.XS_SECURITY_CLASS.REMOVE_PRIVILEGES('HRPRIVS','UPDATE_INFO');
END;

The following example removes all privileges from the HRPRIVS security class.

BEGIN
  SYS.XS_SECURITY_CLASS.REMOVE_PRIVILEGES('HRPRIVS');
END;

ADD_IMPLIED_PRIVILEGES Procedure

The ADD_IMPLIED_PRIVILEGES procedure adds one or more implied privileges to an aggregate privilege.

Syntax

XS_SECURITY_CLASS.ADD_IMPLIED_PRIVILEGES (
  sec_class    IN VARCHAR2,
  priv         IN VARCHAR2,
  implied_priv IN VARCHAR2);

XS_SECURITY_CLASS.ADD_IMPLIED_PRIVILEGES (
  sec_class         IN VARCHAR2,
  priv              IN VARCHAR2,
  implied_priv_list IN XS$NAME_LIST);

Parameters

Examples

The following example adds a list of implied privileges for the aggregate privilege UPDATE_INFO to the HRPRIVS security class:

BEGIN
  SYS.XS_SECURITY_CLASS.ADD_IMPLIED_PRIVILEGES(sec_class=>'HRPRIVS', priv=>'UPDATE_INFO', implied_priv_list=>XS$NAME_LIST('"UPDATE"', '"DELETE"', '"INSERT"'));
END;

REMOVE_IMPLIED_PRIVILEGES Procedure

The REMOVE_IMPLIED_PRIVILEGES procedure removes the specified implied privileges from an aggregate privilege. If no implied privileges are specified, then all implied privileges are removed from the aggregate privilege.

Syntax

XS_SECURITY_CLASS.REMOVE_IMPLIED_PRIVILEGES (
  sec_class    IN VARCHAR2,
  priv         IN VARCHAR2,
  implied_priv IN VARCHAR2);

XS_SECURITY_CLASS.REMOVE_IMPLIED_PRIVILEGES (
  sec_class         IN VARCHAR2,
  priv              IN VARCHAR2,
  implied_priv_list IN XS$NAME_LIST);

XS_SECURITY_CLASS.REMOVE_IMPLIED_PRIVILEGES (
  sec_class   IN VARCHAR2,
  priv        IN VARCHAR2);

Parameters

Examples

The following example removes the implicit privilege DELETE from the aggregate privilege UPDATE_INFO from the HRPRIVS security class:

BEGIN
  SYS.XS_SECURITY_CLASS.REMOVE_IMPLIED_PRIVILEGES('HRPRIVS','UPDATE_INFO','"DELETE"');
END;

The following example removes all implicit privileges from the aggregate privilege UPDATE_INFO from the HRPRIVS security class.

BEGIN
  SYS.XS_SECURITY_CLASS.REMOVE_IMPLIED_PRIVILEGES('HRPRIVS','UPDATE_INFO');
END;

SET_DESCRIPTION Procedure

The SET_DESCRIPTION procedure sets a description string for the specified security class.

Syntax

XS_SECURITY_CLASS.SET_DESCRIPTION (
  sec_class   IN VARCHAR2,
  description IN VARCHAR2);

Parameters

Examples

The following example sets a description string for the HRPRIVS security class:

BEGIN
  SYS.XS_SECURITY_CLASS.SET_DESCRIPTION(
    'HRPRIVS','Contains privileges required to manage HR data');
END;

DELETE_SECURITY_CLASS Procedure

The DELETE_SECURITY_CLASS procedure deletes the specified security class.

Syntax

XS_SECURITY_CLASS.DELETE_SECURITY_CLASS ( 
  sec_class     IN VARCHAR2,
  delete_option IN NUMBER:=XS_ADMIN_UTIL.DEFAULT_OPTION); 

Parameters

Examples

The following example deletes the HRPRIVS security class using the default option:

BEGIN
  SYS.XS_SECURITY_CLASS.DELETE_SECURITY_CLASS('HRPRIVS',XS_ADMIN_UTIL.DEFAULT_OPTION);
END;