Removed non-Defensive Coding Guide bits and promoted source to root

pot/Java/Java.pot

@@ -0,0 +1,19 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: title
+#, no-c-format
+msgid "The Java Programming Language"
+msgstr ""
+

pot/Java/Language.pot

@@ -0,0 +1,214 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: title
+#, no-c-format
+msgid "The core language"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Implementations of the Java programming language provide strong memory safety, even in the presence of data races in concurrent code. This prevents a large range of security vulnerabilities from occurring, unless certain low-level features are used; see <xref linkend=\"sect-Defensive_Coding-Java-LowLevel\" />."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Inceasing robustness when reading arrays"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "External data formats often include arrays, and the data is stored as an integer indicating the number of array elements, followed by this number of elements in the file or protocol data unit. This length specified can be much larger than what is actually available in the data source."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "To avoid allocating extremely large amounts of data, you can allocate a small array initially and grow it as you read more data, implementing an exponential growth policy. See the <function>readBytes(InputStream, int)</function> function in <xref linkend=\"ex-Defensive_Coding-Java-Language-ReadArray\" />."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Incrementally reading a byte array"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "When reading data into arrays, hash maps or hash sets, use the default constructor and do not specify a size hint. You can simply add the elements to the collection as you read them."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Resource management"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Unlike C++, Java does not offer destructors which can deallocate resources in a predictable fashion. All resource management has to be manual, at the usage site. (Finalizers are generally not usable for resource management, especially in high-performance code; see <xref linkend=\"sect-Defensive_Coding-Java-Language-Finalizers\" />.)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The first option is the <literal>try</literal>-<literal>finally</literal> construct, as shown in <xref linkend=\"ex-Defensive_Coding-Java-Language-Finally\" />. The code in the <literal>finally</literal> block should be as short as possible and should not throw any exceptions."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Resource management with a <literal>try</literal>-<literal>finally</literal> block"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Note that the resource allocation happens <emphasis>outside</emphasis> the <literal>try</literal> block, and that there is no <literal>null</literal> check in the <literal>finally</literal> block. (Both are common artifacts stemming from IDE code templates.)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "If the resource object is created freshly and implements the <literal>java.lang.AutoCloseable</literal> interface, the code in <xref linkend=\"ex-Defensive_Coding-Java-Language-TryWithResource\" /> can be used instead. The Java compiler will automatically insert the <function>close()</function> method call in a synthetic <literal>finally</literal> block."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Resource management using the <literal>try</literal>-with-resource construct"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "To be compatible with the <literal>try</literal>-with-resource construct, new classes should name the resource deallocation method <function>close()</function>, and implement the <literal>AutoCloseable</literal> interface (the latter breaking backwards compatibility with Java 6). However, using the <literal>try</literal>-with-resource construct with objects that are not freshly allocated is at best awkward, and an explicit <literal>finally</literal> block is usually the better approach."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "In general, it is best to design the programming interface in such a way that resource deallocation methods like <function>close()</function> cannot throw any (checked or unchecked) exceptions, but this should not be a reason to ignore any actual error conditions."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Finalizers"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Finalizers can be used a last-resort approach to free resources which would otherwise leak. Finalization is unpredictable, costly, and there can be a considerable delay between the last reference to an object going away and the execution of the finalizer. Generally, manual resource management is required; see <xref linkend=\"sect-Defensive_Coding-Java-Language-Resources\" />."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Finalizers should be very short and should only deallocate native or other external resources held directly by the object being finalized. In general, they must use synchronization: Finalization necessarily happens on a separate thread because it is inherently concurrent. There can be multiple finalization threads, and despite each object being finalized at most once, the finalizer must not assume that it has exclusive access to the object being finalized (in the <literal>this</literal> pointer)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Finalizers should not deallocate resources held by other objects, especially if those objects have finalizers on their own. In particular, it is a very bad idea to define a finalizer just to invoke the resource deallocation method of another object, or overwrite some pointer fields."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Finalizers are not guaranteed to run at all. For instance, the virtual machine (or the machine underneath) might crash, preventing their execution."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Objects with finalizers are garbage-collected much later than objects without them, so using finalizers to zero out key material (to reduce its undecrypted lifetime in memory) may have the opposite effect, keeping objects around for much longer and prevent them from being overwritten in the normal course of program execution."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "For the same reason, code which allocates objects with finalizers at a high rate will eventually fail (likely with a <literal>java.lang.OutOfMemoryError</literal> exception) because the virtual machine has finite resources for keeping track of objects pending finalization. To deal with that, it may be necessary to recycle objects with finalizers."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The remarks in this section apply to finalizers which are implemented by overriding the <function>finalize()</function> method, and to custom finalization using reference queues."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Recovering from exceptions and errors"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Java exceptions come in three kinds, all ultimately deriving from <literal>java.lang.Throwable</literal>:"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "<emphasis>Run-time exceptions</emphasis> do not have to be declared explicitly and can be explicitly thrown from any code, by calling code which throws them, or by triggering an error condition at run time, like division by zero, or an attempt at an out-of-bounds array access. These exceptions derive from from the <literal>java.lang.RuntimeException</literal> class (perhaps indirectly)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "<emphasis>Checked exceptions</emphasis> have to be declared explicitly by functions that throw or propagate them. They are similar to run-time exceptions in other regards, except that there is no language construct to throw them (except the <literal>throw</literal> statement itself). Checked exceptions are only present at the Java language level and are only enforced at compile time. At run time, the virtual machine does not know about them and permits throwing exceptions from any code. Checked exceptions must derive (perhaps indirectly) from the <literal>java.lang.Exception</literal> class, but not from <literal>java.lang.RuntimeException</literal>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "<emphasis>Errors</emphasis> are exceptions which typically reflect serious error conditions. They can be thrown at any point in the program, and do not have to be declared (unlike checked exceptions). In general, it is not possible to recover from such errors; more on that below, in <xref linkend=\"sect-Defensive_Coding-Java-Language-Exceptions-Errors\" />. Error classes derive (perhaps indirectly) from <literal>java.lang.Error</literal>, or from <literal>java.lang.Throwable</literal>, but not from <literal>java.lang.Exception</literal>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The general expection is that run-time errors are avoided by careful programming (e.g., not dividing by zero). Checked exception are expected to be caught as they happen (e.g., when an input file is unexpectedly missing). Errors are impossible to predict and can happen at any point and reflect that something went wrong beyond all expectations."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "The difficulty of catching errors"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Errors (that is, exceptions which do not (indirectly) derive from <literal>java.lang.Exception</literal>), have the peculiar property that catching them is problematic. There are several reasons for this:"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The error reflects a failed consistenty check, for example, <literal>java.lang.AssertionError</literal>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The error can happen at any point, resulting in inconsistencies due to half-updated objects. Examples are <literal>java.lang.ThreadDeath</literal>, <literal>java.lang.OutOfMemoryError</literal> and <literal>java.lang.StackOverflowError</literal>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The error indicates that virtual machine failed to provide some semantic guarantees by the Java programming language. <literal>java.lang.ExceptionInInitializerError</literal> is an example—it can leave behind a half-initialized class."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "In general, if an error is thrown, the virtual machine should be restarted as soon as possible because it is in an inconsistent state. Continuing running as before can have unexpected consequences. However, there are legitimate reasons for catching errors because not doing so leads to even greater problems."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Code should be written in a way that avoids triggering errors. See <xref linkend=\"sect-Defensive_Coding-Java-Language-ReadArray\" /> for an example."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "It is usually necessary to log errors. Otherwise, no trace of the problem might be left anywhere, making it very difficult to diagnose realted failures. Consequently, if you catch <literal>java.lang.Exception</literal> to log and suppress all unexpected exceptions (for example, in a request dispatching loop), you should consider switching to <literal>java.lang.Throwable</literal> instead, to also cover errors."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The other reason mainly applies to such request dispatching loops: If you do not catch errors, the loop stops looping, resulting in a denial of service."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "However, if possible, catching errors should be coupled with a way to signal the requirement of a virtual machine restart."
+msgstr ""
+

pot/Java/LowLevel.pot

@@ -0,0 +1,119 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: title
+#, no-c-format
+msgid "Low-level features of the virtual machine"
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "<literal>Reflection and private parts</literal>"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The <function>setAccessible(boolean)</function> method of the <literal>java.lang.reflect.AccessibleObject</literal> class allows a program to disable language-defined access rules for specific constructors, methods, or fields. Once the access checks are disabled, any code can use the <literal>java.lang.reflect.Constructor</literal>, <literal>java.lang.reflect.Method</literal>, or <literal>java.lang.reflect.Field</literal> object to access the underlying Java entity, without further permission checks. This breaks encapsulation and can undermine the stability of the virtual machine. (In contrast, without using the <function>setAccessible(boolean)</function> method, this should not happen because all the language-defined checks still apply.)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "This feature should be avoided if possible."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Java Native Interface (JNI)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The Java Native Interface allows calling from Java code functions specifically written for this purpose, usually in C or C++."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The transition between the Java world and the C world is not fully type-checked, and the C code can easily break the Java virtual machine semantics. Therefore, extra care is needed when using this functionality."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "To provide a moderate amount of type safety, it is recommended to recreate the class-specific header file using <application>javah</application> during the build process, include it in the implementation, and use the <option>-Wmissing-declarations</option> option."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Ideally, the required data is directly passed to static JNI methods and returned from them, and the code and the C side does not have to deal with accessing Java fields (or even methods)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "When using <function>GetPrimitiveArrayCritical</function> or <function>GetStringCritical</function>, make sure that you only perform very little processing between the get and release operations. Do not access the file system or the network, and not perform locking, because that might introduce blocking. When processing large strings or arrays, consider splitting the computation into multiple sub-chunks, so that you do not prevent the JVM from reaching a safepoint for extended periods of time."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "If necessary, you can use the Java <literal>long</literal> type to store a C pointer in a field of a Java class. On the C side, when casting between the <literal>jlong</literal> value and the pointer on the C side,"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "You should not try to perform pointer arithmetic on the Java side (that is, you should treat pointer-carrying <literal>long</literal> values as opaque). When passing a slice of an array to the native code, follow the Java convention and pass it as the base array, the integer offset of the start of the slice, and the integer length of the slice. On the native side, check the offset/length combination against the actual array length, and use the offset to compute the pointer to the beginning of the array."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Array length checking in JNI code"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "In any case, classes referring to native resources must be declared <literal>final</literal>, and must not be serializeable or cloneable. Initialization and mutation of the state used by the native side must be controlled carefully. Otherwise, it might be possible to create an object with inconsistent native state which results in a crash (or worse) when used (or perhaps only finalized) later. If you need both Java inheritance and native resources, you should consider moving the native state to a separate class, and only keep a reference to objects of that class. This way, cloning and serialization issues can be avoided in most cases."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "If there are native resources associated with an object, the class should have an explicit resource deallocation method (<xref linkend=\"sect-Defensive_Coding-Java-Language-Resources\" />) and a finalizer (<xref linkend=\"sect-Defensive_Coding-Java-Language-Finalizers\" />) as a last resort. The need for finalization means that a minimum amount of synchronization is needed. Code on the native side should check that the object is not in a closed/freed state."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Many JNI functions create local references. By default, these persist until the JNI-implemented method returns. If you create many such references (e.g., in a loop), you may have to free them using <function>DeleteLocalRef</function>, or start using <function>PushLocalFrame</function> and <function>PopLocalFrame</function>. Global references must be deallocated with <function>DeleteGlobalRef</function>, otherwise there will be a memory leak, just as with <function>malloc</function> and <function>free</function>."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "When throwing exceptions using <function>Throw</function> or <function>ThrowNew</function>, be aware that these functions return regularly. You have to return control manually to the JVM."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Technically, the <literal>JNIEnv</literal> pointer is not necessarily constant during the lifetime of your JNI module. Storing it in a global variable is therefore incorrect. Particularly if you are dealing with callbacks, you may have to store the pointer in a thread-local variable (defined with <literal>__thread</literal>). It is, however, best to avoid the complexity of calling back into Java code."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Keep in mind that C/C++ and Java are different languages, despite very similar syntax for expressions. The Java memory model is much more strict than the C or C++ memory models, and native code needs more synchronization, usually using JVM facilities or POSIX threads mutexes. Integer overflow in Java is defined, but in C/C++ it is not (for the <literal>jint</literal> and <literal>jlong</literal> types)."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "<literal>sun.misc.Unsafe</literal>"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The <literal>sun.misc.Unsafe</literal> class is unportable and contains many functions explicitly designed to break Java memory safety (for performance and debugging). If possible, avoid using this class."
+msgstr ""
+

pot/Java/SecurityManager.pot

@@ -0,0 +1,228 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: title
+#, no-c-format
+msgid "Interacting with the security manager"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The Java platform is largely implemented in the Java language itself. Therefore, within the same JVM, code runs which is part of the Java installation and which is trusted, but there might also be code which comes from untrusted sources and is restricted by the Java sandbox (to varying degrees). The <emphasis>security manager</emphasis> draws a line between fully trusted, partially trusted and untrusted code."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The type safety and accessibility checks provided by the Java language and JVM would be sufficient to implement a sandbox. However, only some Java APIs employ such a capabilities-based approach. (The Java SE library contains many public classes with public constructors which can break any security policy, such as <literal>java.io.FileOutputStream</literal>.) Instead, critical functionality is protected by <emphasis>stack inspection</emphasis>: At a security check, the stack is walked from top (most-nested) to bottom. The security check fails if a stack frame for a method is encountered whose class lacks the permission which the security check requires."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "This simple approach would not allow untrusted code (which lacks certain permissions) to call into trusted code while the latter retains trust. Such trust transitions are desirable because they enable Java as an implementation language for most parts of the Java platform, including security-relevant code. Therefore, there is a mechanism to mark certain stack frames as trusted (<xref linkend=\"sect-Defensive_Coding-Java-SecurityManager-Privileged\" />)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "In theory, it is possible to run a Java virtual machine with a security manager that acts very differently from this approach, but a lot of code expects behavior very close to the platform default (including many classes which are part of the OpenJDK implementation)."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Security manager compatibility"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "A lot of code can run without any additional permissions at all, with little changes. The following guidelines should help to increase compatibility with a restrictive security manager."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "When retrieving system properties using <function>System.getProperty(String)</function> or similar methods, catch <literal>SecurityException</literal> exceptions and treat the property as unset."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Avoid unnecessary file system or network access."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Avoid explicit class loading. Access to a suitable class loader might not be available when executing as untrusted code."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "If the functionality you are implementing absolutely requires privileged access and this functionality has to be used from untrusted code (hopefully in a restricted and secure manner), see <xref linkend=\"sect-Defensive_Coding-Java-SecurityManager-Privileged\" />."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Activating the security manager"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The usual command to launch a Java application, <command>java</command>, does not activate the security manager. Therefore, the virtual machine does not enforce any sandboxing restrictions, even if explicitly requested by the code (for example, as described in <xref linkend=\"sect-Defensive_Coding-Java-SecurityManager-Unprivileged\" />)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The <option>-Djava.security.manager</option> option activates the security manager, with the fairly restrictive default policy. With a very permissive policy, most Java code will run unchanged. Assuming the policy in <xref linkend=\"ex-Defensive_Coding-Java-SecurityManager-GrantAll\" /> has been saved in a file <filename>grant-all.policy</filename>, this policy can be activated using the option <option>-Djava.security.policy=grant-all.policy</option> (in addition to the <option>-Djava.security.manager</option> option)."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Most permissve OpenJDK policy file"
+msgstr ""
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"grant {\n"
+"      permission java.security.AllPermission;\n"
+"};\n"
+""
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "With this most permissive policy, the security manager is still active, and explicit requests to drop privileges will be honored."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Reducing trust in code"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "<xref linkend=\"ex-Defensive_Coding-Java-SecurityManager-Unprivileged\" /> shows how to run a piece code of with reduced privileges."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Using the security manager to run code with reduced privileges"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The example above does not add any additional permissions to the <literal>permissions</literal> object. If such permissions are necessary, code like the following (which grants read permission on all files in the current directory) can be used:"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Calls to the <function>java.security.AccessController.doPrivileged()</function> methods do not enforce any additional restriction if no security manager has been set. Except for a few special exceptions, the restrictions no longer apply if the <function>doPrivileged()</function> has returned, even to objects created by the code which ran with reduced privileges. (This applies to object finalization in particular.)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The example code above does not prevent the called code from calling the <function>java.security.AccessController.doPrivileged()</function> methods. This mechanism should be considered an additional safety net, but it still can be used to prevent unexpected behavior of trusted code. As long as the executed code is not dynamic and came with the original application or library, the sandbox is fairly effective."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The <literal>context</literal> argument in <xref linkend=\"ex-Defensive_Coding-Java-SecurityManager-Unprivileged\" /> is extremely important—otherwise, this code would increase privileges instead of reducing them."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "For activating the security manager, see <xref linkend=\"sect-Defensive_Coding-Java-SecurityManager-Activate\" />. Unfortunately, this affects the virtual machine as a whole, so it is not possible to do this from a library."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Re-gaining privileges"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Ordinarily, when trusted code is called from untrusted code, it loses its privileges (because of the untrusted stack frames visible to stack inspection). The <function>java.security.AccessController.doPrivileged()</function> family of methods provides a controlled backdoor from untrusted to trusted code."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "By design, this feature can undermine the Java security model and the sandbox. It has to be used very carefully. Most sandbox vulnerabilities can be traced back to its misuse."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "In essence, the <function>doPrivileged()</function> methods cause the stack inspection to end at their call site. Untrusted code further down the call stack becomes invisible to security checks."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "The following operations are common and safe to perform with elevated privileges."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Reading custom system properties with fixed names, especially if the value is not propagated to untrusted code. (File system paths including installation paths, host names and user names are sometimes considered private information and need to be protected.)"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Reading from the file system at fixed paths, either determined at compile time or by a system property. Again, leaking the file contents to the caller can be problematic."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Accessing network resources under a fixed address, name or URL, derived from a system property or configuration file, information leaks not withstanding."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "<xref linkend=\"ex-Defensive_Coding-Java-SecurityManager-Privileged\" /> shows how to request additional privileges."
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Using the security manager to run code with increased privileges"
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Obviously, this only works if the class containing the call to <function>doPrivileged()</function> is marked trusted (usually because it is loaded from a trusted class loader)."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "When writing code that runs with elevated privileges, make sure that you follow the rules below."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Make the privileged code as small as possible. Perform as many computations as possible before and after the privileged code section, even if it means that you have to define a new class to pass the data around."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Make sure that you either control the inputs to the privileged code, or that the inputs are harmless and cannot affect security properties of the privileged code."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "Data that is returned from or written by the privileged code must either be restricted (that is, it cannot be accessed by untrusted code), or must be harmless. Otherwise, privacy leaks or information disclosures which affect security properties can be the result."
+msgstr ""
+
+#. Tag: para
+#, no-c-format
+msgid "If the code calls back into untrusted code at a later stage (or performs other actions under control from the untrusted caller), you must obtain the original security context and restore it before performing the callback, as in <xref linkend=\"ex-Defensive_Coding-Java-SecurityManager-Callback\" />. (In this example, it would be much better to move the callback invocation out of the privileged code section, of course.)"
+msgstr ""
+
+#. Tag: title
+#, no-c-format
+msgid "Restoring privileges when invoking callbacks"
+msgstr ""
+

pot/Java/schemas.pot

@@ -0,0 +1,14 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+

pot/Java/snippets/Finally.pot

@@ -0,0 +1,26 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"InputStream in = new BufferedInputStream(new FileInputStream(path));\n"
+"try {\n"
+"    readFile(in);\n"
+"} finally {\n"
+"    in.close();\n"
+"}\n"
+""
+msgstr ""
+

pot/Java/snippets/JNI-Pointers.pot

@@ -0,0 +1,50 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"JNIEXPORT jint JNICALL Java_sum\n"
+"  (JNIEnv *jEnv, jclass clazz, jbyteArray buffer, jint offset, jint length)\n"
+"{\n"
+"  assert(sizeof(jint) == sizeof(unsigned));\n"
+"  if (offset &lt; 0 || length &lt; 0) {\n"
+"    (*jEnv)-&gt;ThrowNew(jEnv, arrayIndexOutOfBoundsExceptionClass,\n"
+"		      \"negative offset/length\");\n"
+"    return 0;\n"
+"  }\n"
+"  unsigned uoffset = offset;\n"
+"  unsigned ulength = length;\n"
+"  // This cannot overflow because of the check above.\n"
+"  unsigned totallength = uoffset + ulength;\n"
+"  unsigned actuallength = (*jEnv)-&gt;GetArrayLength(jEnv, buffer);\n"
+"  if (totallength &gt; actuallength) {\n"
+"    (*jEnv)-&gt;ThrowNew(jEnv, arrayIndexOutOfBoundsExceptionClass,\n"
+"		      \"offset + length too large\");\n"
+"    return 0;\n"
+"  }\n"
+"  unsigned char *ptr = (*jEnv)-&gt;GetPrimitiveArrayCritical(jEnv, buffer, 0);\n"
+"  if (ptr == NULL) {\n"
+"    return 0;\n"
+"  }\n"
+"  unsigned long long sum = 0;\n"
+"  for (unsigned char *p = ptr + uoffset, *end = p + ulength; p != end; ++p) {\n"
+"    sum += *p;\n"
+"  }\n"
+"  (*jEnv)-&gt;ReleasePrimitiveArrayCritical(jEnv, buffer, ptr, 0);\n"
+"  return sum;\n"
+"}\n"
+""
+msgstr ""
+

pot/Java/snippets/Language-ReadArray.pot

@@ -0,0 +1,53 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"static byte[] readBytes(InputStream in, int length) throws IOException {\n"
+"	final int startSize = 65536;\n"
+"    byte[] b = new byte[Math.min(length, startSize)];\n"
+"    int filled = 0;\n"
+"    while (true) {\n"
+"        int remaining = b.length - filled;\n"
+"	    readFully(in, b, filled, remaining);\n"
+"        if (b.length == length) {\n"
+"            break;\n"
+"        }\n"
+"        filled = b.length;\n"
+"        if (length - b.length &lt;= b.length) {\n"
+"            // Allocate final length.  Condition avoids overflow.\n"
+"            b = Arrays.copyOf(b, length);\n"
+"        } else {\n"
+"            b = Arrays.copyOf(b, b.length * 2);\n"
+"        }\n"
+"    }\n"
+"    return b;\n"
+"}\n"
+"\n"
+"static void readFully(InputStream in,byte[] b, int off, int len)\n"
+"	    throws IOException {\n"
+"	int startlen = len;\n"
+"    while (len &gt; 0) {\n"
+"        int count = in.read(b, off, len);\n"
+"        if (count &lt; 0) {\n"
+"            throw new EOFException();\n"
+"        }\n"
+"        off += count;\n"
+"        len -= count;\n"
+"    }\n"
+"}\n"
+""
+msgstr ""
+

pot/Java/snippets/SecurityManager-Callback.pot

@@ -0,0 +1,54 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"interface Callback&lt;T&gt; {\n"
+"	T call(boolean flag);\n"
+"}\n"
+"\n"
+"class CallbackInvoker&lt;T&gt; {\n"
+"	private final AccessControlContext context;\n"
+"	Callback&lt;T&gt; callback;\n"
+"\n"
+"	CallbackInvoker(Callback&lt;T&gt; callback) {\n"
+"	    context = AccessController.getContext();\n"
+"	    this.callback = callback;\n"
+"	}\n"
+"\n"
+"	public T invoke() {\n"
+"	    // Obtain increased privileges.\n"
+"	    return AccessController.doPrivileged(new PrivilegedAction&lt;T&gt;() {\n"
+"		    @Override\n"
+"		    public T run() {\n"
+"			// This operation would fail without\n"
+"			// additional privileges.\n"
+"			final boolean flag = Boolean.getBoolean(\"some.property\");\n"
+"\n"
+"			// Restore the original privileges.\n"
+"			return AccessController.doPrivileged(\n"
+"                        new PrivilegedAction&lt;T&gt;() {\n"
+"				@Override\n"
+"				public T run() {\n"
+"				    return callback.call(flag);\n"
+"				}\n"
+"			    }, context);\n"
+"		    }\n"
+"		});\n"
+"	}\n"
+"}\n"
+""
+msgstr ""
+

pot/Java/snippets/SecurityManager-CurrentDirectory.pot

@@ -0,0 +1,22 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"permissions.add(new FilePermission(\n"
+"            System.getProperty(\"user.dir\") + \"/-\", \"read\"));\n"
+""
+msgstr ""
+

pot/Java/snippets/SecurityManager-Privileged.pot

@@ -0,0 +1,33 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"// This is expected to fail.\n"
+"try {\n"
+"    System.out.println(System.getProperty(\"user.home\"));\n"
+"} catch (SecurityException e) {\n"
+"    e.printStackTrace(System.err);\n"
+"}\n"
+"AccessController.doPrivileged(new PrivilegedAction&lt;Void&gt;() {\n"
+"        public Void run() {\n"
+"            // This should work.\n"
+"            System.out.println(System.getProperty(\"user.home\"));\n"
+"            return null;\n"
+"        }\n"
+"    });\n"
+""
+msgstr ""
+

pot/Java/snippets/SecurityManager-Unprivileged.pot

@@ -0,0 +1,42 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"Permissions permissions = new Permissions();\n"
+"        ProtectionDomain protectionDomain =\n"
+"    new ProtectionDomain(null, permissions);\n"
+"        AccessControlContext context = new AccessControlContext(\n"
+"            new ProtectionDomain[] { protectionDomain });\n"
+"\n"
+"// This is expected to succeed.\n"
+"try (FileInputStream in = new FileInputStream(path)) {\n"
+"    System.out.format(\"FileInputStream: %s%n\", in);\n"
+"}\n"
+"\n"
+"AccessController.doPrivileged(new PrivilegedExceptionAction&lt;Void&gt;() {\n"
+"	@Override\n"
+"        public Void run() throws Exception {\n"
+"	    // This code runs with reduced privileges and is\n"
+"	    // expected to fail.\n"
+"	    try (FileInputStream in = new FileInputStream(path)) {\n"
+"		System.out.format(\"FileInputStream: %s%n\", in);\n"
+"	    }\n"
+"	    return null;\n"
+"	}\n"
+"    }, context);\n"
+""
+msgstr ""
+

pot/Java/snippets/TryWithResource.pot

@@ -0,0 +1,23 @@
+# 
+# AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: 0\n"
+"POT-Creation-Date: 2013-08-13T01:54:52\n"
+"PO-Revision-Date: 2013-08-13T01:54:52\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: None\n"
+"MIME-Version: 1.0\n"
+"Content-Type: application/x-publican; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. Tag: programlisting
+#, no-c-format
+msgid "\n"
+"try (InputStream in = new BufferedInputStream(new FileInputStream(path))) {\n"
+"    readFile(in);\n"
+"}\n"
+""
+msgstr ""
+