Author: shawkins Date: 2010-06-28 10:47:10 -0400 (Mon, 28 Jun 2010) New Revision: 2309 Added: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml Modified: branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml Log: adding doc content and correcting javadoc Modified: branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java =================================================================== --- branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java 2010-06-28 14:43:04 UTC (rev 2308) +++ branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java 2010-06-28 14:47:10 UTC (rev 2309) @@ -64,7 +64,7 @@ /** * Obtain the query planner debug log from the last command * executed on this Statement, if it was requested with - * OPTION DEBUG. If no debug output was requested, this + * SHOWPLAN DEBUG. If no debug output was requested, this * method will return null. * @return Debug log or null if no log exists */ Added: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml =================================================================== --- branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml (rev 0) +++ branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml 2010-06-28 14:47:10 UTC (rev 2309) @@ -0,0 +1,28 @@ +<!-- +TODO: incorporate a performance chapter. + +The information about document materialization belongs in the reference though. And is not completely correct +w.r.t. the use of document projection. + + <para>Your application can use a statement object to execute queries that return XML documents. + The query must specify a valid document in VDB, or should have used SQL XML functions + to create a XMl document.</para> + <sect3> + <title>XML Streaming</title> + <para>XML documents are streamed from Teiid Server to the Teiid JDBC API.   + Normally, the document never materializes in the server memory, avoiding potential + out-of-memory issues and improving the first response time for large documents. + When using style sheets, or XQuery, the whole document + must be materialized on the server. Therefore memory issues may occur for large documents. + A result document can be obtained from the JDBC resultset using <code>getSQLXML</code> method. + </para> + <para>The document is broken into pieces when being created and streamed.  + The maximum size of each piece in the stream can be configured with the + <code>"lobChunkSizeInKB"</code> system property on the Server. The default value is 100 KB.  + At any given time, this is the maximum amount of memory that can be held by a particular + XML query against the system.  In heavily loaded or memory-constrained scenarios, + this value can decrease the amount of memory used.  As a side effect, streaming will occur in smaller pieces, reducing initial document response time while + increasing full response time (as this is less efficient).</para> + </sect3> + + --> \ No newline at end of file Property changes on: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml =================================================================== --- branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml 2010-06-28 14:43:04 UTC (rev 2308) +++ branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml 2010-06-28 14:47:10 UTC (rev 2309) @@ -3,7 +3,7 @@ <chapter id="custom_security"> <title>Teiid Security</title> <para>The Teiid system provides a range of built-in and extensible security features to enable the - secure access of data.  </para> + secure access of data.</para> <sect1> <title>Authentication</title> <para>JDBC clients may use simple passwords to authenticate a user.</para> @@ -11,6 +11,13 @@ identity of the user can be discerned by the password credential alone.  In any case it is up to the configured security domain to determine whether a user can be authenticated.</para> + + <note><para>By default, access to Teiid is NOT secure. The default login modules are only + backed by file based authentication, which has a well known user + name and password. + The same is true for making connections to the Admin Console application. + We DO NOT recommend leaving the default security profile as defined when you + are exposing sensitive data.</para></note> </sect1> <sect1> <title>Authorization</title> @@ -59,6 +66,14 @@ Details of the failed attempt including invalid users, which domains were consulted, etc. will be in the server log with appropriate levels of severity.</para> + <note> + <para>The security-domain defined for the JDBC connection and Admin connections are separate. + The default name of JDBC connection's security-domain is "teiid-security". The default name for Admin connection + is "jmx-console". For the Admin connection's security domain, the user is allowed + to change which LoginModule that "jmx-console" pointing to, however should not change the name of the domain, as this name is + shared between the "admin-console" application.</para> + </note> + <sect2> <title>Built-in LoginModules</title> <para>JBossAS provides several LoginModules for common authentication needs, such as authenticating from text files or LDAP.</para> @@ -71,12 +86,52 @@ If you want use a your own Custom Login module, check out the Developer's Guide for instructions. </para> </sect2> + </sect1> - <note> - <para>The security-domain defined for the JDBC connection and Admin connections are separate. - The default name of JDBC connection's security-domain is "teiid-security". The default name for Admin connection - is "jmx-console". For the Admin connection's security domain, the user is allowed - to change which LoginModule that "jmx-console" pointing to, however should not change the name of the domain, as this name is - shared between the "admin-console" application.</para> - </note> + + <sect1 id="connfigure_server"> + <title>Configuring SSL</title> + <para>The Teiid's configuration file + <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy/teiid/teiid-jboss-beans.xml</code>, + contains the properties to configure SSL.</para> + <itemizedlist> + <para>There are two separate connection profiles:</para> + <listitem><para>JDBC Connection - The <code>JdbcSslConfiguration</code> bean configuration defines this.</para></listitem> + <listitem><para>Admin Connection - The <code>AdminSslConfiguration</code> bean configuration defines this.</para></listitem> + </itemizedlist> + <example><title>Example Configuration</title> + <programlisting><![CDATA[<bean name="JdbcSslConfiguration" class="org.teiid.transport.SSLConfiguration"> + <property name="sslEnabled">false</property> + <property name="keystoreFilename">cert.keystore</property> + <property name="keystorePassword">passwd</property> + <property name="keystoreType">JKS</property> + <property name="sslProtocol">SSLv3</property> + <property name="keymanagementAlgorithm">false</property> + <property name="truststoreFilename">cert.truststore</property> + <property name="truststorePassword">passwd</property> + <!-- 1-way, 2-way, anonymous --> + <property name="authenticationMode">1-way</property> + <property name="clientEncryptionEnabled">true</property> +</bean>]]></programlisting> +</example> + <orderedlist> + <title>Properties</title> + <listitem><para>sslEnabled - true|false, SSL usage either turned ON or OFF </para></listitem> + <listitem><para>sslProtocol- Type of SSL protocol to be used. Default is SSLv3</para></listitem> + <listitem><para>keystoreType - Keystore type created by the keytool. Default "JKS" is used.</para></listitem> + <listitem><para>authenticationMode - anonymous|1-way|2-way, Type of SSL mode, see + above about different <link linkend="ssl_modes">SSL modes</link> available.</para></listitem> + <listitem><para>keymanagementAlgorithm - Type of key algorithm used. Default + is based upon the VM, e.g. "SunX509"</para></listitem> + <listitem><para>keystoreFilename - The file name of the keystore, which contains the + private key of the Server. This must be available in the classpath of Teiid Server</para></listitem> + <listitem><para>keystorePassword - password for the keystore.</para></listitem> + <listitem><para>truststoreFilename - if "authenticationMode" is chosen + as "2-way", then this property must be provided. This is the truststore that contains the + public key for the client. Depending upon how you created the keystore and truststores, + this may be same file as defined under "keystoreFilename" property.</para></listitem> + <listitem><para>truststorePassword - password for the truststore. </para></listitem> + </orderedlist> + + </sect1> </chapter> \ No newline at end of file Modified: branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml =================================================================== --- branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml 2010-06-28 14:43:04 UTC (rev 2308) +++ branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml 2010-06-28 14:47:10 UTC (rev 2309) @@ -53,6 +53,7 @@ <xi:include href="content/scalar_functions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/procedures.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/transaction_support.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/entitlements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/system_schema.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/translators.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="content/federated_planning.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Added: branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml =================================================================== --- branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml (rev 0) +++ branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml 2010-06-28 14:47:10 UTC (rev 2309) @@ -0,0 +1,122 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd"> +%CustomDTD; +]> +<chapter id="entitlements"> + <title>Data Roles</title> + <para>Data roles, also called entitlements, are sets of permissions that are defined + per VDB that dictate data access (create, read, update, delete). The use of data roles is controlled system wide with the property in + <code>&lt;jboss-install&gt;/server/&lt;profile&gt;/deploy/teiid/teiid-jboss-beans.xml</code> file + in bean configuration section of <code>RuntimeEngineDeployer</code> with property <code>useEntitlements</code>.</para> + + <para>Once data roles are enabled, the access permissions defined in a VDB will be enforced by the Teiid Server.</para> + + <sect1> + <title>Permissions</title> + <orderedlist> + <para>To process a <code>SELECT</code> statement or a stored procedure execution, the user account requires the following access rights:</para> + <listitem> <para><code>READ</code> - on the Table(s) being accessed or the procedure being called.</para></listitem> + <listitem> <para><code>READ</code> - on every column referenced.</para></listitem> + </orderedlist> + + <orderedlist> + <para>To process an <code>INSERT</code> statement, the user account requires the following access rights:</para> + <listitem> <para><code>CREATE</code> - on the Table being inserted into.</para></listitem> + <listitem> <para><code>CREATE</code> - on every column being inserted on that Table.</para></listitem> + </orderedlist> + + <orderedlist> + <para>To process an <code>UPDATE</code> statement, the user account requires the following access rights:</para> + <listitem> <para><code>UPDATE</code> - on the Table being updated.</para></listitem> + <listitem> <para><code>UPDATE</code> - on every column being updated on that Table.</para></listitem> + <listitem> <para><code>READ</code> - on every column referenced in the criteria.</para></listitem> + </orderedlist> + + <orderedlist> + <para>To process a <code>DELETE</code> statement, the user account requires the following access rights:</para> + <listitem> <para><code>DELETE</code> - on the Table being deleted.</para></listitem> + <listitem> <para><code>READ</code> - on every column referenced in the criteria.</para></listitem> + </orderedlist> + </sect1> + + <sect1> + <title>XML Definition</title> + <para>Data roles are defined inside the <code>vdb.xml</code> file (inside the .vdb Zip archive under META-INF/vdb.xml) if you used Designer. + This example will show a sample "vdb.xml" file with few simple data rules.</para> + + <para>For example, if a VDB defines a table "TableA" in schema "modelName" with columns (column1, column2) - note that the column types do not matter. And we wish to define three roles "RoleA", "RoleB", "RoleC" with following permissions: + <orderedlist> + <listitem><para>RoleA has privileges to read, write access to TableA, but can not delete.</para></listitem> + <listitem><para>RoleB has no privileges that allow access to TableA</para></listitem> + <listitem><para>RoleC has privileges that only allow read access to TableA.column1</para></listitem> + </orderedlist> + </para> + <example><title>vdb.xml defining RoleA, RoleB, and RoleC</title> + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<vdb name="sample" version="1"> + + <model name="modelName"> + <source name="source-name" translator-name="oracle" connection-jndi-name="java:myDS" /> + </model> + + <data-policy name="RoleA"> + <description>Allow all, except Delete</description> + + <permission> + <resource-name>modelName.TableA</resource-name> + <allow-create /> + <allow-read /> + <allow-update /> + </permission> + + <permission> + <resource-name>modelName.TableA.colum1</resource-name> + <allow-create /> + <allow-read /> + <allow-update /> + </permission> + + <permission> + <resource-name>modelName.TableA.column2</resource-name> + <allow-create /> + <allow-read /> + <allow-update /> + </permission> + + <mapped-role-name>role1</mapped-role-name> + + </data-policy> + + <data-policy name="RoleC"> + <description>Allow read only</description> + + <permission> + <resource-name>modelName.TableA</resource-name> + <allow-read /> + </permission> + + <permission> + <resource-name>modelName.TableA.colum1</resource-name> + <allow-read /> + </permission> + + <mapped-role-name>role2</mapped-role-name> + </data-policy> +</vdb>]]></programlisting> +</example> + <para>The above XML defined two data roles, "RoleA" which allows everything except delete on the table, "RoleC" that + allows only read operation on the table. Since Teiid uses deny by default, there is no explict data-policy entry needed for "RoleB". The "mapped-role-name" defines the "role" to whom these policies are applicable. Each data-policy + must define a "role" to be enforced by the Teiid Server.</para> + + <para>For assigning the roles to your users, in the JBoss AS, + check out the instructions for the selected Login Module. Check "Admin Guide" for configuring Login Modules.</para> + + <para>"vdb.xml" file is checked against the schema file <code>vdb-deployer.xsd</code>, check the documents sections of the Teiid kit + to find a copy of the schema file.</para> + + <note><para>Currently there is no GUI tooling support in the Designer or any other management tool to create this data roles + permissions xml, however this is in our roadmap for future releases to provide.</para></note> + </sect1> + +</chapter> \ No newline at end of file Property changes on: branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml ___________________________________________________________________ Name: svn:mime-type + text/plain