35 Administration of Oracle XML DB

Authentication Considerations for a Database Installation

In a default database installation, digest authentication is enabled, and basic authentication is disallowed. Digest verifiers are automatically generated for all users.

Authentication Considerations for a Database Upgrade

After an upgrade from a release prior to Oracle Database 12c Release 1 (12.1.0.1), digest authentication is appended to the list of allowed authentication mechanisms. But basic authentication remains the current authentication method if it was enabled before the upgrade.

This is for backward compatibility only: Oracle recommends that your database administrator disable basic authentication as soon as possible after upgrading. The reason that basic authentication remains in effect after such an upgrade is to allow users to change their passwords using a Web browser that does not support digest authentication.

For such an upgrade, digest verifiers are computed for all new users and for all previously existing users whose passwords changed during the upgrade. Other users do not have digest verifiers.

After an upgrade, a DBA can use database view DBA_DIGEST_VERIFIERS to check which users have digest verifiers and take appropriate action, as follows:

1. Configure basic authentication as the first allowed authentication mechanism in the Oracle XML DB configuration file, xdbconfig.xml. This ensures that basic authentication can be used for HTTP access.

2. Expire all passwords for those users who do not have digest verifiers. This query returns those users:

   SELECT USERNAME FROM DBA_DIGEST_VERIFIERS
     WHERE HAS_DIGEST_VERIFIERS = 'NO' AND DIGEST_TYPE is NULL;
   

3. After the passwords for all such users have been changed, configure xdbconfig.xml to re-enable digest as the first or (preferably) the only allowed authentication mechanism.

Authentication Considerations for a Database Downgrade

If you downgrade to a release where digest authentication was not supported, digest authentication is disabled and made unavailable as an authentication choice.

All digest verifiers are erased during a downgrade. This means, in particular, that if a downgrade is followed by an upgrade then users who were able to authenticate prior to the downgrade are denied digest authentication after the downgrade and the subsequent upgrade.

Element xdbconfig (Top-Level)

Element xdbconfig is the top-level element. Its structure is as follows:

<xdbconfig> 
    <sysconfig> ... </sysconfig> 
    <userconfig> ... </userconfig> 
</xdbconfig>

Element sysconfig defines system-specific, built-in parameters. Element userconfig lets you store new custom parameters.

Element sysconfig (Child of xdbconfig)

Element sysconfig is a child of xdbconfig. Its structure is as follows:

<sysconfig> 
    general parameters
    <protocolconfig> ... </protocolconfig> 
</sysconfig> 

Element sysconfig includes as content several general parameters that apply to all of Oracle XML DB, such as the maximum age of an access control list (ACL). Child element protocolconfig contains protocol-specific parameters.

Element userconfig (Child of xdbconfig)

Element userconfig is a child of xdbconfig. It contains any parameters that you may want to add.

Element protocolconfig (Child of sysconfig)

Element protocolconfig is a child of sysconfig. Its structure is as follows:

<protocolconfig> 
  <common> ... </common> 
  <ftpconfig> ... </ftpconfig> 
  <httpconfig> ... </httpconfig> </protocolconfig> 

Under element common, Oracle Database stores parameters that apply to all protocols, such as MIME-type information. Parameters that are specific to protocols FTP and HTTP(S) are in elements ftpconfig and httpconfig, respectively.

Element httpconfig (Child of protocolconfig)

Element httpconfig is a child of protocolconfig. Its structure is as follows:

<httpconfig>
  ...
  <webappconfig>
    ...
    <servletconfig>
      ...
      <servlet-list>
        <servlet> ... </servlet>
        ...
      </servlet-list>
    </servletconfig>
  </webappconfig>
  ...
  <plsql> ... </plsql>
</httpconfig>

Element httpconfig has the following child elements, in addition to others:

• webappconfig – used to configure Web-based applications. This includes Web application-specific parameters, such as icon name, display name for the application, and a list of servlets.

  Element servletconfig is a child of webappconfig that is used to define servlets. It has child element servlet-list, which has child element servlet (see "Element servlet (Descendant of httpconfig)").

• plsql^Foot 1  – used to define global configuration parameters when configuring the embedded PL/SQL gateway. Each global parameter is defined with a child element of plsql. The element name is the same as the global parameter name. The element content is the same as the parameter value.

  The recommended way to configure the embedded PL/SQL gateway is to use the procedures in PL/SQL package DBMS_EPG, not to edit file xdbconfig.xml.

Element servlet (Descendant of httpconfig)

Element servlet is a descendent of element httpconfig – see "Element httpconfig (Child of protocolconfig)". It is used to configure servlets, including Java servlets and embedded PL/SQL gateway servlets.

An optional element plsql, child of servletFootref 1, configures the embedded PL/SQL gateway servlet. However, the recommended way to configure the embedded gateway is to use the procedures in PL/SQL package DBMS_EPG, not to edit file xdbconfig.xml.

Element plsql has a child element for each embedded PL/SQL DAD attribute^Foot 2  that is needed to configure the embedded gateway. All such children are optional. The element name is the same as the DAD attribute name. The element content is the same as the DAD-attribute value.

Oracle XML DB Configuration File Example

The following is a sample Oracle XML DB configuration file:

<xdbconfig xmlns="http://xmlns.oracle.com/xdb/xdbconfig.xsd" 
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xsi:schemaLocation="http://xmlns.oracle.com/xdb/xdbconfig.xsd 
                                    http://xmlns.oracle.com/xdb/xdbconfig.xsd">
   <sysconfig>
      <acl-max-age>900</acl-max-age>
      <acl-cache-size>32</acl-cache-size> 
      <invalid-pathname-chars>,</invalid-pathname-chars>
      <case-sensitive>true</case-sensitive>       
      <call-timeout>300</call-timeout>
      <max-link-queue>65536</max-link-queue> 
      <max-session-use>100</max-session-use>
      <persistent-sessions>false</persistent-sessions> 
      <default-lock-timeout>3600</default-lock-timeout>
      <xdbcore-logfile-path>/sys/log/xdblog.xml</xdbcore-logfile-path>
      <xdbcore-log-level>0</xdbcore-log-level>
      <resource-view-cache-size>1048576</resource-view-cache-size> 
    
      <protocolconfig> 
          <common>
             <extension-mappings>
                <mime-mappings>
                  <mime-mapping>
                    <extension>au</extension>
                    <mime-type>audio/basic</mime-type>
                  </mime-mapping>
                  <mime-mapping>
                    <extension>avi</extension>
                    <mime-type>video/x-msvideo</mime-type>
                  </mime-mapping>
                  <mime-mapping>
                    <extension>bin</extension>
                    <mime-type>application/octet-stream</mime-type>
                  </mime-mapping>
                </mime-mappings> 

                <lang-mappings>
                  <lang-mapping>
                    <extension>en</extension>
                    <lang>english</lang>
                  </lang-mapping>
                </lang-mappings>

                <charset-mappings>
                </charset-mappings>

                <encoding-mappings>
                  <encoding-mapping>
                    <extension>gzip</extension>
                    <encoding>zip file</encoding>      
                  </encoding-mapping>
                  <encoding-mapping>
                    <extension>tar</extension>
                    <encoding>tar file</encoding>        
                  </encoding-mapping>
                </encoding-mappings>
             </extension-mappings>

             <session-pool-size>50</session-pool-size>
             <session-timeout>6000</session-timeout>
          </common>

          <ftpconfig>
            <ftp-port>2100</ftp-port>
            <ftp-listener>local_listener</ftp-listener>
            <ftp-protocol>tcp</ftp-protocol>
            <logfile-path>/sys/log/ftplog.xml</logfile-path>
            <log-level>0</log-level>
            <session-timeout>6000</session-timeout>
            <buffer-size>8192</buffer-size> 
          </ftpconfig>

          <httpconfig>
            <http-port>8080</http-port>
            <http-listener>local_listener</http-listener>
            <http-protocol>tcp</http-protocol>
            <max-http-headers>64</max-http-headers> 
            <session-timeout>6000</session-timeout>
            <server-name>XDB HTTP Server</server-name>
            <max-header-size>16384</max-header-size>
            <max-request-body>2000000000</max-request-body>
            <logfile-path>/sys/log/httplog.xml</logfile-path>
            <log-level>0</log-level>    
            <servlet-realm>Basic realm="XDB"</servlet-realm>
            <webappconfig>
              <welcome-file-list>
                <welcome-file>index.html</welcome-file>
                <welcome-file>index.htm</welcome-file>
              </welcome-file-list>
              <error-pages>
              </error-pages>
              <servletconfig> 
                <servlet-mappings>
                  <servlet-mapping>
                    <servlet-pattern>/oradb/*</servlet-pattern>
                    <servlet-name>DBURIServlet</servlet-name>
                  </servlet-mapping>
                </servlet-mappings>
                               
                <servlet-list>
                  <servlet>
                    <servlet-name>DBURIServlet</servlet-name>
                    <display-name>DBURI</display-name>
                    <servlet-language>C</servlet-language>
                    <description>Servlet for accessing DBURIs</description>
                    <security-role-ref>
                      <role-name>authenticatedUser</role-name>
                      <role-link>authenticatedUser</role-link>
                    </security-role-ref>
                  </servlet>
                </servlet-list>
              </servletconfig>
            </webappconfig>
          </httpconfig> 
      </protocolconfig>
    <xdbcore-xobmem-bound>1024</xdbcore-xobmem-bound> 
    <xdbcore-loadableunit-size>16</xdbcore-loadableunit-size> 
   </sysconfig>
</xdbconfig>

Oracle XML DB Configuration API

You can access the Oracle XML DB configuration file, xdbconfig.xml, the same way you access any other XML schema-based resource in the hierarchy. It can be accessed using FTP, HTTP(S), WebDAV, Oracle Enterprise Manager, or any of the resource and Document Object Model (DOM) APIs for Java, PL/SQL, or C (OCI).

For convenience, you can use PL/SQL package DBMS_XDB_CONFIG package for configuration access. It exposes the following functions and procedures:

• cfg_get – Returns the configuration information for the current session.

• cfg_refresh – Refreshes the session configuration information using the current configuration file. Typical uses of cfg_refresh include the following:

  • You have modified the configuration and now want the session to pick up the latest version of the configuration information.

  • It has been a long running session, the configuration has been modified by a concurrent session, and you want the current session to pick up the latest version of the configuration information.

• cfg_update – Updates the configuration information, writing the configuration file. A COMMIT is performed.

Example 35-2 updates parameters ftp-port and http-port in the configuration file.

DECLARE
  v_cfg XMLType;
BEGIN
  SELECT XMLQuery('declare default element namespace
                   "http://xmlns.oracle.com/xdb/xdbconfig.xsd";
                   copy $i := $cfg 
                   modify for $j in $i/xdbconfig
                   return (replace value of node $j/descendant::ftp-port with
                             "2121",
                           replace value of node $j/descendant::http-port with
                             "19090")
                   return $i'
                  PASSING DBMS_XDB_CONFIG.cfg_get() AS "cfg"
                  RETURNING CONTENT)
    INTO v_cfg FROM DUAL; 
  DBMS_XDB_CONFIG.cfg_update(v_cfg);
END;
/ 

If you have many parameters to update, then it can be easier to use FTP, HTTP(S), or Oracle Enterprise Manager to update the configuration.

Configuring Default Namespace to Schema Location Mappings

Oracle XML DB identifies schema-based XMLType instances by pre-parsing the input XML document. If the appropriate xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute is found, then the specified schema location URL is used to consult the registered schema. If the appropriate xsi: attribute is not found, the XML document is considered to be non-schema-based.Oracle XML DB provides a mechanism to configure default schema location mappings. If the appropriate xsi: attribute is not specified in the XML document, the default schema location mappings is used. Element schemaLocation-mappings of the Oracle XML DB configuration XML schema, xdbconfig.xsd, can be used to specify the mapping between (namespace, element) pairs and the default schema location. If the element value is empty, the mapping applies to all global elements in the specified namespace. If the namespace value is empty, it corresponds to the null namespace.

The definition of the schemaLocation-mappings element is as follows:

 <element name="schemaLocation-mappings"
          type="xdbc:schemaLocation-mapping-type" minOccurs="0"/> 
 <complexType name="schemaLocation-mapping-type"><sequence>
      <element name="schemaLocation-mapping"
               minOccurs="0" maxOccurs="unbounded">
      <complexType><sequence>
        <element name="namespace" type="string"/>
        <element name="element" type="string"/>
        <element name="schemaURL" type="string"/>
      </sequence></complexType>
      </element></sequence> 
 </complexType> 

The schema location used depends on mappings in the Oracle XML DB configuration file for the namespace used and the root document element. For example, assume that the document does not have the appropriate xsi: attribute to indicate the schema location. Consider a document root element R in namespace N. The algorithm for identifying the default schema location is as follows:

1. If the Oracle XML DB configuration file has a mapping for N and R, the corresponding schema location is used.

2. If the configuration file has a mapping for N, but not R, the schema location for N is used.

3. If the document root R does not have any namespace, the schema location for R is used.

For example, suppose that your Oracle XML DB configuration file includes the following mapping:

      <schemaLocation-mappings>
         <schemaLocation-mapping>
            <namespace>http://www.oracle.com/example</namespace>
            <element>root</element>
            <schemaURL>http://www.oracle.com/example/sch.xsd</schemaURL>
         </schemaLocation-mapping>
         <schemaLocation-mapping>
            <namespace>http://www.oracle.com/example2</namespace>
            <element></element>
            <schemaURL>http://www.oracle.com/example2/sch.xsd</schemaURL>
         </schemaLocation-mapping>
         <schemaLocation-mapping>
           <namespace></namespace>
           <element>specialRoot</element>
           <schemaURL>http://www.oracle.com/example3/sch.xsd</schemaURL>
         </schemaLocation-mapping>
      </schemaLocation-mappings>
 

The following schema locations are used:

• Root element = root

  • Namespace = http://www.oracle.com/example

  • Schema URL = http://www.oracle.com/example/sch.xsd

  This mapping is used when the instance document specifies:

  <root xmlns="http://www.oracle.com/example/">
  

• Root element = null (any global element in the namespace)

  • Namespace = http://www.oracle.com/example2

  • Schema URL = http://www.oracle.com/example2/sch.xsd

  This mapping is used when the instance document specifies:

  <root xmlns="http://www.oracle.example2">
  

• Root element = specialRoot

  • Namespace = null (i.e null namespace)

  • Schema URL = http://www.oracle.com/example3/sch.xsd

  This mapping is used when the instance document specifies:

  <specialRoot>
  

Configuring XML File Extensions

Oracle XML DB Repository treats certain files as XML documents, based on their file extensions. When such files are inserted into the repository, Oracle XML DB pre-parses them to identify the schema location (or uses the default mapping if present) and inserts the document into the appropriate default table. By default, the following extensions are considered as XML file extensions: xml, xsd, xsl, xlt. In addition, Oracle XML DB provides a mechanism for applications to specify other file extensions as XML file extensions. The xml-extensions element is defined in the configuration schema, http://xmlns.oracle.com/xdb/xdbconfig.xsd, as follows:

 <element name="xml-extensions"
          type="xdbc:xml-extension-type" minOccurs="0"/>
 
 <complexType name="xml-extension-type"><sequence>
      <element name="extension" type="xdbc:exttype"
               minOccurs="0" maxOccurs="unbounded">
      </element></sequence> 
  </complexType> 

For example, the following fragment from the Oracle XML DB configuration file, xdbconfig.xml, specifies that files with extensions vsd, vml, and svgl should be treated as XML files:

 <xml-extensions>
   <extension>vsd</extension>
   <extension>vml</extension>
   <extension>svgl</extension>
 </xml-extensions>