|
|
| (40 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | ==Eclipse Setup==
| + | ESAPI is easy to build yourself using [https://git-scm.com/ Git] and [http://maven.apache.org/ Maven]. Ensure that you are using UTF-8 for all source code. |
| | | | |
| − | * Get the [http://www.eclipse.org/downloads/ Ganymede release of Eclipse] - We recommend the version for Java EE developers
| + | $ git clone https://github.com/ESAPI/esapi-java-legacy.git # This will clone the 'develop' branch. |
| − | * Install [http://java.sun.com/javase/downloads/index_jdk5.jsp Java JDK 5.0 or greater] if you don't have it yet. Note: a ''JDK'' (not JRE) is required
| + | $ cd esapi-java-legacy |
| − | * Within Eclipse, download and install the [http://subclipse.tigris.org/install.html Eclipse Subversion (SVN) plugin] called Subclipse.
| + | $ mvn -Dmaven.test.skip=true package # Build ESAPI |
| − | ** Don't forget to do Step 12: to enable the Subversion perspective within Eclipse
| |
| − | * Within Eclipse, download and install the [http://m2eclipse.codehaus.org/ Eclipse Maven plugin]. At this time, we recommend using the latest stable development build (the second link on the page)
| |
| − | * Connect to the SVN and download the ESAPI source. Directions can be found [http://addlink here]
| |
| − | * Download [http://addlink this script] and edit it to match your directory structure. Then run the script to add ESAPI and Antisamy jar files to your Maven repository (enables building of ESAPI and Swingset)
| |
| − | ** If the script loads and quickly closes or there are build errors, it is likely that at least one of the references to files/folders is not correct
| |
| − | * If you do not launch Eclipse from a shortcut, create a shortcut for Eclipse
| |
| − | # Navigate to the directory where you installed Eclipse
| |
| − | # Right-Click Eclipse.exe
| |
| − | # Select ''Create Shortcut''
| |
| − | * Right-Click your Eclipse shortcut
| |
| − | * Select ''Properties''
| |
| − | * At the end of the line that says ''Target'', add ''-vm "x"'' where ''x'' is the location of a JDK. This step is necessary for the Maven plugin to work
| |
| − | * Restart Eclipse using the edited shortcut.
| |
| | | | |
| − | ==Importing the ESAPI Source==
| + | Maven will generate a "target" directory that contains the ESAPI jar file. |
| − | To import the ESAPI source code into your workspace, you can either download the source files in a zip file from [https://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API#Download_Now here] or download the latest trunk from the ESAPI SVN.
| |
| | | | |
| − | '''The zip files containing the ESAPI source''' are official releases of the ESAPI. They will be updated whenever major changes are made to the ESAPI, whether features are added/removed, or if ESAPI undergoes a major organizational change. If you are planning on using the ESAPI's reference implementations and want to see ESAPI's source, but do not want to build your own JAR, you might download the ESAPI source zip file (available [https://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API#Download_Now here]).
| + | To generate project reports use: |
| | | | |
| − | '''The ESAPI trunk SVN''' contains the most up-to-date development version of ESAPI. The trunk may contain different code from the pre-zipped source. It may contain new features or be organized differently. The trunk is a development version of the ESAPI, meaning that contributors to the ESAPI project are actively editing this code, so while all contributors are encouraged to run all test cases on the code before committing it, developers using this code should run their own tests to be sure the code is fully functional. In addition, because the trunk code is in development, documentation regarding the ESAPI, especially Javadocs, may not be entirely accurate.
| + | $ mvn site |
| | | | |
| − | ===Source Code From a .zip===
| + | To generate documentation use: |
| | | | |
| − | While there are a few ways to import the ESAPI project using a zip file of its source code, I recommend following these instructions. For the moment, I'll assume you are using Eclipse as your IDE. More tutorials may come in the future for other IDEs.
| + | $ mvn javadoc:jar |
| | | | |
| − | * Unzip file ESAPI source files to a directory of your choice.
| |
| − | * From the Eclipse toolbar, select ''File'' -> ''New'' -> ''Project'' -> ''Other''.
| |
| − | * In the ''Java'' folder, select ''Java Project from Existing Ant Buildfile'' and click Next.
| |
| − | * Name your project.
| |
| − | * Click ''Browse'' and navigate to the unzipped ESAPI source files.
| |
| − | * From the root directory (probably ESAPI_version) select ''build.xml''.
| |
| − | * Click ''Finish'' and you should be ready to edit ESAPI.
| |
| − |
| |
| − | ===Subversion Setup===
| |
| − |
| |
| − | If you choose to use the ESAPI SVN code, follow the instructions [http://code.google.com/p/owasp-esapi-java/source/checkout here]. Unless you have been added to the ESAPI project as a contributor, please use the bottom SVN checkout link on the Google Code page (non-SSL).
| |
| − |
| |
| − | If you are using subclipse, as recommended, open Eclipse and:
| |
| − | * Click ''File'' -> ''New'' -> ''Other....''.
| |
| − | * From the ''SVN Folder'' select '"Checkout Projects from SVN'' (this option will only be available if you have a SVN plugin installed) and hit ''Next >''.
| |
| − | * Click the ''Create a new repository location'' radio button.
| |
| − | * If you are not listed as a project contributor, insert ''http://owasp-esapi-java.googlecode.com/svn/trunk/'' as the URL. If you are listed as a project contributor, check the Google Code page for the URL to use. (Note: if you are a contributor, when prompted for your SVN password, use your Google generated password, available from the Google Code Source page.)
| |
| − | * Once the directory structure appears in the window, click the URL at the top to download everything. Then hit ''Next >''
| |
| − | * Select your desired project options. For most people, the default options should be fine. When finished, click ''Next >''.
| |
| − | * Select your desired workspace options, then click ''Finish''. The latest ESAPI source files will then be downloaded to your workspace. This may take a few minutes.
| |
| − |
| |
| − | ==Project Setup==
| |
| − |
| |
| − | Some configuration may be necessary for ESAPI to compile and build on your system.
| |
| − |
| |
| − | ESAPI requires the Java SDK 1.4. Java 1.4.2 is used by ESAPI to keep it backward compatible with environments that are still using older versions of Java. Please be sure this is [http://java.sun.com/j2se/1.4.2/download.html downloaded] and installed.
| |
| − |
| |
| − | * Once Java 1.4 is installed, open the ''Navigator view'' in Eclipse. If this is currently hidden, from the toolbar click ''Window'' -> ''Show View'' -> ''Navigator''.
| |
| − | * ''Right-click on the ESAPI project root folder'' in the Navigator view and select ''Properties''.
| |
| − | * From the left column, select ''Java Build Path''. Under the ''Libraries'' tab, be sure the ''JRE'' listed is version ''1.4''. If it is not, remove the current JRE and click ''Add Library'' and select an alternate JRE. If you are having trouble figuring out what version the current JRE is, select ''Installed JREs'' and look at the location to which each version is mapped.
| |
| − | * From the left column, select ''Java Compiler''. Be sure ''Compiler compliance level'', ''Generated .class files compatibility'', and ''Source compatibility'' are all set to ''1.4''.
| |
| − | * Close the properties window.
| |
| − | * ''Right-click the ESAPI project root folder'' and select ''Refresh''.
| |
| − | * From the toolbar, select ''Project'' -> ''Clean..'' and select the ESAPI project. Click ''OK''.
| |
| − | * ESAPI should now be compiled.
| |
| − |
| |
| − | ==Building==
| |
| − |
| |
| − | Building ESAPI should be easy with the included Ant build scripts.
| |
| − |
| |
| − | There are two build scripts included in the ESAPI trunk repository.
| |
| − | * Full build of ESAPI with all available reference implementations.
| |
| − | * Basic build of ESAPI without reference implementations.
| |
| − |
| |
| − | While the reference implementations are generally good for independent developers, most businesses will want to create their own security implementations based around the companies standard practices and infrastructure. This is why the Basic version is provided.
| |
| − |
| |
| − | To build either version, simple ''right-click the build script'' for the desired build, select ''Run As'' -> ''Ant Build''. The script should run, with output directed to the Console. When complete, the dist directory should contain a new JAR, the build directory will contain all class files (even the reference implementation class files in the Basic build), and javadoc/api will contain the newly generated Javadocs.
| |
| − |
| |
| − | ===Problems Building?===
| |
| − | If you have any problems while performing the steps above, be sure you have Apache Ant installed.
| |
| − | ''For help setting up Eclipse or integrating Ant within Eclipse, please read [http://www.onjava.com/pub/a/onjava/excerpt/anttdg2_ch11/index.html?page=1 this article]''.
| |
| − |
| |
| − | Compile problems after the build are usually caused by dependency issues. Please check your Java Build Path to be sure all the necessary files are included.
| |
| − |
| |
| − | As of ESAPI v1.3.0, the necessary Libraries are:
| |
| − |
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/antisamy-bin.1.2.jar antisamy-bin.1.2.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/batik-css.jar batik-css.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/batik-util.jar batik-util.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-codec-1.3.jar commons-codec-1.3.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-fileupload-1.2.jar commons-fileupload-1.2.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-fileupload-1.2-sources.jar commons-fileupload-1.2-sources.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-httpclient-3.1.jar commons-httpclient-3.1.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-io-1.3.2.jar commons-io-1.3.2.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-io-1.3.2-sources.jar commons-io-1.3.2-sources.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/commons-logging-1.1.1.jar commons-logging-1.1.1.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/jsp-api.jar jsp-api.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/junit-4.4.jar junit-4.4.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/nekohtml.jar nekohtml.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/proguard.jar proguard.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/servlet-api.jar servlet-api.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/xercesImpl.jar xercesImpl.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/xml-apis.jar xml-apis.jar]
| |
| − | * [http://owasp-esapi-java.googlecode.com/svn/trunk/lib/xml-apis-ext.jar xml-apis-ext.jar]
| |
| − | * [http://java.sun.com/j2se/1.4.2/download.html JRE System Library (1.4.2)]
| |
| − |
| |
| − | ''Note: not all of these libraries may be required if you do not plan on using the ESAPI reference implementations!''
| |
| − |
| |
| − |
| |
| − | Please remember, ESAPI requires J2SE 1.4.2.
| |
| − |
| |
| − | ====If any of these files are missing====
| |
| − | To check if the above files are on your Java Build Path in Eclipse, Right-Click the ESAPI project folder and select properties, then select ''Java Build Path'' from the left column, and choose ''Libraries'' from the tabs on the right.
| |
| − |
| |
| − | All of the files listed above, aside from the JRE, should have been downloaded in the source zip file. They should be located in /lib.
| |
| − |
| |
| − | ==Running Test Cases==
| |
| − |
| |
| − | * From the ''Navigator'' view, select test/org/owasp/esapi/AllTests.java
| |
| − | * ''Right-click'' -> ''Run As'' -> ''Run Configurations...''
| |
| − | * Choose the JUnit configuration
| |
| − | * Select the ''Arguments'' tab and enter a VM argument
| |
| − | ** -Dorg.owasp.esapi.resources="<path to your esapi project>/test/testresources"
| |
| − | * run tests and verify that they all pass
| |
| − |
| |
| − | ==Running Demo App==
| |
| − |
| |
| − | The ESAPI Demo application has been named ''The ESAPI Swingset''. More information about Swingset is available [http://www.owasp.org/index.php/ESAPI_Swingset here].
| |
| | | | |
| | __NOTOC__ | | __NOTOC__ |
| | | | |
| | [[Category:OWASP Enterprise Security API]] | | [[Category:OWASP Enterprise Security API]] |
