You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by an...@apache.org on 2013/03/29 14:11:14 UTC

svn commit: r1462463 - /jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext

Author: andy
Date: Fri Mar 29 13:11:13 2013
New Revision: 1462463

URL: http://svn.apache.org/r1462463
Log:
Add  paramertized-sparql-string.mdtext

Added:
    jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext

Added: jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext?rev=1462463&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext (added)
+++ jena/site/trunk/content/documentation/query/paramertized-sparql-string.mdtext Fri Mar 29 13:11:13 2013
@@ -0,0 +1,99 @@
+Title: Parameterized SPARQL String
+
+A Parameterized SPARQL String is a SPARQL query/update into which values
+may be injected.
+
+### Injecting Values
+
+Values may be injected in several ways:
+
+-   By treating a variable in the SPARQL string as a parameter
+-   Using JDBC style positional parameters
+-   Appending values directly to the command text being built
+
+Variable Parameters
+
+Any variable in the command may have a value injected to it, injecting a
+value replaces all usages of that variable in the command i.e.
+substitutes the variable for a constant, injection is done by textual
+substitution.
+
+#### Positional Parameters
+
+You can use JDBC style positional parameters if you prefer, a JDBC style
+parameter is a single <tt>?</tt> followed by whitespace or certain
+punctuation characters (currently <tt>; , .</tt>). Positional parameters
+have a unique index which reflects the order in which they appear in the
+string. Positional parameters use a zero based index.
+
+Buffer Usage
+
+Additionally you may use this purely as a <code>StringBuffer</code>
+replacement for creating queries since it provides a large variety of
+convenience methods for appending things either as-is or as nodes (which
+causes appropriate formatting to be applied).
+
+### Intended Usage
+
+The intended usage of this is where using a <code>QuerySolutionMap</code> as
+initial bindings is either inappropriate or not possible e.g.
+
+-   Generating query/update strings in code without lots of error prone
+    and messy string concatenation
+-   Preparing a query/update for remote execution
+-   Where you do not want to simply say some variable should have a
+    certain value but rather wish to insert constants into the
+    query/update in place of variables
+-   Defending against SPARQL injection when creating a query/update
+    using some external input, see SPARQL Injection notes for
+    limitations.
+-   Provide a more convenient way to prepend common prefixes to your
+    query
+
+This class is useful for preparing both queries and updates hence the
+generic name as it provides programmatic ways to replace variables in
+the query with constants and to add prefix and base declarations. A
+<code>Query</code> or <code>UpdateRequest</code> can be created using 
+the <code>asQuery()</code> and <code>asUpdate()</code> methods assuming the command an
+instance represents is actually valid as a query/update.
+
+### Warnings
+
+1.  Note that this class does not in any way check that your command is
+    syntactically correct until such time as you try and parse it as a
+    <code>Query</code> or <code>UpdateRequest</code>.
+2.  Also note that injection is done purely based on textual
+    replacement, it does not understand or respect variable scope in any
+    way. For example if your command text contains sub queries you
+    should ensure that variables within the sub query which you don't
+    want replaced have distinct names from those in the outer query you
+    do want replaced (or vice versa)
+
+### SPARQL Injection Notes
+
+While this class was in part designed to prevent SPARQL injection it is
+by no means foolproof because it works purely at the textual level. The
+current version of the code addresses some possible attack vectors that
+the developers have identified but we recognize that there are some
+cases that we cannot prevent. In particular you should never surround a
+variable which you intend to replace with double quotes e.g.
+
+    String str = "PREFIX : <http://example/>\nINSERT DATA { <s> <p> \"?\" }";
+    ParameterizedSparqlString pss = new ParameterizedSparqlString(str);
+
+While the class will recognize and prevent this as an error this
+protection is trivially defeated by placing some white space around the
+variable definition e.g
+
+    String str = "PREFIX : <http://example/>\nINSERT DATA { <s> <p> \" r \" }";
+    ParameterizedSparqlString pss = new ParameterizedSparqlString(str);
+
+This latter case cannot be easily detected and prevented because we
+can't easily distinguish between a possible injection vulnerability and
+a variable that merely occurs between two literals.
+
+Therefore, we <b>strongly</b> recommend that users concerned about SPARQL
+Injection attacks perform their own validation on provided parameters
+and test their use of this class to avoid known attack vectors. We also
+recommend that users do not use easily guessable variable names for
+their parameters as these can allow a chained injection attack.