|
43 | 43 | import org.owasp.esapi.errors.ConfigurationException; |
44 | 44 |
|
45 | 45 | /** |
46 | | - * The reference {@code SecurityConfiguration} manages all the settings used by the ESAPI in a single place. In this reference |
47 | | - * implementation, resources can be put in several locations, which are searched in the following order: |
| 46 | + * Thse reference implementation class for {@code SecurityConfiguration} manages all the settings used by the ESAPI |
| 47 | + * in a single place. In this reference implementation, resources can be put in several locations, which are |
| 48 | + * searched in the following order: |
48 | 49 | * <p> |
49 | | - * 1) Inside a directory set with a call to SecurityConfiguration.setResourceDirectory( "C:\temp\resources" ). |
50 | | - * <p> |
51 | | - * 2) Inside the System.getProperty( "org.owasp.esapi.resources" ) directory. |
| 50 | + * <ol> |
| 51 | + * <li> |
| 52 | + * Inside a directory set with a call to SecurityConfiguration.setResourceDirectory( "C:\temp\resources" ). |
| 53 | + * </p><p> |
| 54 | + * <b>CAUTION:</b> Generally this technique should be avoided if you are |
| 55 | + * using ESAPI in a resusable library, as it makes it very difficult for an |
| 56 | + * application using your library to use its own version of |
| 57 | + * <b>ESAPI.properties</b>. |
| 58 | + * </p><p> |
| 59 | + * The only exception might be if you are writing a wrapper library for ESAPI |
| 60 | + * and wish to provide a set of ESAPI properties that the application cannot <i>accidentally</i> |
| 61 | + * change. However, selecting this option won't intentionally prevent changing <b>ESAPI.properties</b> |
| 62 | + * unless you are signing the jar * and somehow forcing the verifiction of its digital signature at |
| 63 | + * runtime. That's because it's easy enough to unjar your library, edit the <b>ESAPI.properties</b> |
| 64 | + * file and then re-jar the library. |
| 65 | + * </p><p> |
| 66 | + * This option was probably more intended for use by web applications by embedding |
| 67 | + * them as resources in .war or .ear files, possibly with the intent of |
| 68 | + * dissauding operations staff from making "improvements", a practice which |
| 69 | + * makes much less--if any--sense in the era of DevOps and DevSecOps. |
| 70 | + * </p> |
| 71 | + * </li> |
| 72 | + * <li> |
| 73 | + * Inside the {@code System.getProperty( "org.owasp.esapi.resources" )} directory. |
52 | 74 | * You can set this on the java command line as follows (for example): |
53 | 75 | * <pre> |
54 | | - * java -Dorg.owasp.esapi.resources="C:\temp\resources" |
| 76 | + * |
| 77 | + * java -Dorg.owasp.esapi.resources="C:\apps\myApp\resources" |
55 | 78 | * </pre> |
56 | 79 | * You may have to add this to the start-up script that starts your web server. For example, for Tomcat, |
57 | 80 | * in the "catalina" script that starts Tomcat, you can set the JAVA_OPTS variable to the {@code -D} string above. |
58 | | - * <p> |
59 | | - * 3) Inside the {@code System.getProperty( "user.home" ) + "/.esapi"} directory (supported for backward compatibility) or |
| 81 | + * </li> |
| 82 | + * <li> |
| 83 | + * Inside the {@code System.getProperty( "user.home" ) + "/.esapi"} directory (supported for backward compatibility) or |
60 | 84 | * inside the {@code System.getProperty( "user.home" ) + "/esapi"} directory. |
61 | | - * <p> |
62 | | - * 4) The first ".esapi" or "esapi" directory on the classpath. (The former for backward compatibility.) |
63 | | - * <p> |
64 | | - * Once the Configuration is initialized with a resource directory, you can edit it to set things like master |
65 | | - * keys and passwords, logging locations, error thresholds, and allowed file extensions. |
66 | | - * <p> |
67 | | - * WARNING: Do not forget to update ESAPI.properties to change the master key and other security critical settings. |
68 | | - * <p> |
| 85 | + * </li> |
| 86 | + * <li> |
| 87 | + * The first ".esapi" or "esapi" directory on the classpath. (The former for backward compatibility.) |
| 88 | + * </li> |
| 89 | + * </ol> |
| 90 | + * </p><p> |
| 91 | + * Once the ESAPI configuration is initialized with a resource directory, you can edit it to set things like master |
| 92 | + * keys and passwords, logging locations, error thresholds, and allowed file extensions. (But see the above cautionary |
| 93 | + * note if you are using ESAPI in a reusable library.) |
| 94 | + * </p><p> |
| 95 | + * <b>WARNING:</b> Do not forget to update ESAPI.properties to change the master key and other security critical settings |
| 96 | + * as well as reviewing changes in the <code>esapi-<<i>vers</i>-configuration.jar</code> for differences |
| 97 | + * with your current version to see if any important properties were added or removed. |
| 98 | + * </p><p> |
69 | 99 | * <b>DEPRECATION WARNING</b>: All of the variables of the type '{@code public static final String}' |
70 | 100 | * are now declared and defined in the {@code org.owasp.esapi.PropNames}. These public fields |
71 | 101 | * representing property names and values in <i>this</i> class <i>will</i> be eventually deleted and |
|
0 commit comments