Download the latest releases of ESAPI http://www.owasp.org/index.

php/ESAPI

DesignPatterns

Thispageisintentionallyblank

iiESAPIDesignPatterns

OWASPESAPIDesignPatterns ThisdocumentexploresthreecommonOWASPEnterpriseSecurityAPI(ESAPI)designpatterns. Itisintendedtobelanguageindependent,i.e.,thepatternsdescribedinthisdocumentare applicabletoalllanguageversionsofESAPI.OWASPESAPIToolkitsaredesignedtoensurethat strongsimplesecuritycontrolsareavailabletoeverydeveloperineveryenvironment. WedLiketoHearfromYou FurtherdevelopmentofESAPIoccursthroughmailinglistdiscussionsandoccasionalworkshops, andsuggestionsforimprovementarewelcome.Pleaseaddresscommentsandquestions concerningtheAPIandthisdocumenttotheESAPImaillist,owaspesapi@lists.owasp.org CopyrightandLicense Copyright2009TheOWASPFoundation. ThisdocumentisreleasedundertheCreativeCommonsAttribution ShareAlike3.0license.Foranyreuseordistribution,youmustmakeclearto othersthelicensetermsofthiswork.

ESAPIDesignPatterns

iii

Thispageisintentionallyblank

ivESAPIDesignPatterns

 TableofContents AboutESAPI............................................................................................................................. 1 TheBuiltInSingletonPattern .................................................................................................. 2 TheExtendedSingletonPattern............................................................................................... 3 TheExtendedFactoryPattern.................................................................................................. 4 WheretoGoFromHere........................................................................................................... 7 Figures Figure1:HowESAPIworksoutofthebox ...................................................................................... 1 Figure2:BuiltInSingletonPatternExample .................................................................................. 2 Figure3:ExtendedSingletonPatternExample ............................................................................... 4 Figure4:ExtendedFactoryPatternExample .................................................................................. 6

ESAPIDesignPatterns

Thispageisintentionallyblank

viESAPIDesignPatterns

About ESAPI
OWASPESAPIToolkitsaredesignedtoensurethatstrongsimple securitycontrolsareavailabletoeverydeveloperineveryenvironment. AllOWASPESAPIversionsarecalledinthesamebasicway,asdepicted inthefigurebelow.

Figure1:HowESAPIworksoutofthebox Allowingforlanguagespecificdifferences,allOWASPESAPIversions havethesamebasicdesign: Thereisasetofsecuritycontrolinterfaces.Thereisno applicationlogiccontainedintheseinterfaces.Theydefinefor exampletypesofparametersthatarepassedtotypesof securitycontrols.Thereisnoproprietaryinformationorlogic containedintheseinterfaces. Thereisareferenceimplementationforeachsecuritycontrol. Thereisapplicationlogiccontainedintheseclasses,i.e. containedintheseinterfaceimplementations.However,the logicisnotorganizationspecificandthelogicisnotapplication specific.Thereisnoproprietaryinformationorlogiccontained inthesereferenceimplementationclasses.Anexample:string basedinputvalidation. Thereareoptionallyyourownimplementationsforeach securitycontrol.Theremaybeapplicationlogiccontainedin theseclasseswhichmaybedevelopedbyorforyour organization.Thelogicmaybeorganizationspecificand/or applicationspecific.Theremaybeproprietaryinformationor logiccontainedintheseclasseswhichmaybedevelopedbyor foryourorganization.Anexample:enterpriseauthentication.

Therearethreecommonwaystowriteyourownimplementationsfor eachsecuritycontrol:usingabuiltinsingletonpattern,usingan extendedsingletonpattern,orusinganextendedfactorypattern. Theremainderofthisdocumentexploresthesethreedesignpatterns, includingsituationswheretakingmorethanoneapproachmaybe appropriate. ESAPIDesignPatterns 1

The Built-In Singleton Pattern

TheESAPIsecuritycontrolinterfacesincludeanESAPIclassthatis commonlyreferredtoasalocatorclass.TheESAPIlocatorclassis calledinordertoretrievesingletoninstancesofindividualsecurity controls,whicharethencalledinordertoperformsecuritychecks(such asperforminganaccesscontrolcheck)orthatresultinsecurityeffects (suchasgeneratinganauditrecord). Thebuiltinsingletonpatternreferstothereplacementofsecurity controlreferenceimplementationswithyourownimplementations. ESAPIinterfacesareotherwiseleftintact. Forexample:
... require_once dirname(__FILE__) . '/../Authenticator.php'; ... //your implementation class MyAuthenticator implements Authenticator { ...

DeveloperswouldcallESAPIinthisexampleasfollows:
... $ESAPI = new ESAPI(); $myauthenticator = new MyAuthenticator(); //register with locator class ESAPI::setAuthenticator($myauthenticator); $authenticator = ESAPI::getAuthenticator(); $authenticator->login(...); //use your implementation ...

TheUMLfortheaboveexampleisinthefigurebelow.

Figure2:BuiltInSingletonPatternExample 2ESAPIDesignPatterns

ProsoftakingthisapproachincludeloosecouplingbetweenESAPIand yourownimplementations. ConsincludetheneedfordeveloperstounderstandhowtocallESAPI functionswiththeparametersrequiredbyyourorganizationand/or application.

The Extended Singleton Pattern

WhileESAPIsecuritycontrolreferenceimplementationsmayperform thesecuritychecksandresultinthesecurityeffectsrequiredbyyour organizationand/orapplication,theremaybeaneedtominimizethe needfordeveloperstounderstandhowtocallESAPIfunctionswiththe parametersrequiredbyyourorganizationand/orapplication. Availabilityoftrainingmaybeanissue,forexample.Anotherexample wouldbetofacilitateenforcingacodingstandard. Theextendedsingletonpatternreferstothereplacementofsecurity controlreferenceimplementationswithyourownimplementationsand theaddition/modification/subtractionofcorrespondingsecuritycontrol interfaces. Forexample:
... require_once dirname(__FILE__) . '/../Validator.php'; ... //reference implementation class DefaultValidator implements Validator { ... //not defined in Validator interface function isValidEmployeeID($eid) { ...

DeveloperswouldcallESAPIinthisexampleasfollows:
... $ESAPI = new ESAPI(); $validator = ESAPI::getValidator(); $validator->isValidEmployeeID(1234); ...

TheUMLfortheaboveexampleisinthefigurebelow.

ESAPIDesignPatterns

MyValidator +isValidInput() +...() +isValidEmployeeID() interface Validator +isValidInput() +...()

Your implementation (has additional and/or perhaps changed functions compared to reference implementation)

ESAPI interface

May also be modified

DefaultValidator +isValidInput() +...()

ESAPI reference implementation (does not include a isValidEmployeeID function)

Figure3:ExtendedSingletonPatternExample

Prosoftakingthisapproacharethelesseningoftheneedfor developerstounderstandhowtocallESAPIfunctionswiththespecific parametersrequiredbyyourorganizationand/orapplication.Prosalso includeminimizingoreliminatingtheabilityfordeveloperstocallESAPI functionsthatdeviatefromyourorganizationsand/orapplications policies. ConsresultfromthetightcouplingbetweenESAPIandyourown implementations:youwillneedtomaintainboththemodifiedsecurity controlreferenceimplementationsandthemodifiedsecuritycontrol interfaces(asnewversionsofESAPIarereleasedovertime).

The Extended Factory Pattern

WhileESAPIsecuritycontrolreferenceimplementationsmayperform thesecuritychecksandresultinthesecurityeffectsrequiredbyyour organizationand/orapplication,theremaybeaneedtoeliminatethe abilityofdeveloperstodeviatefromyourorganizationsand/or applicationspolicies.Highdeveloperturnovermaybeanissue,for example.Anotherexamplewouldbetostronglyenforceacoding standard. Theextendedfactorypatternsreferstotheadditionofanewsecurity controlinterfaceandcorrespondingimplementation,whichinturncalls ESAPIsecuritycontrolreferenceimplementationsand/orsecurity controlreferenceimplementationsthatwerereplacedwithyourown implementations.TheESAPIlocatorclasswouldbecalledinorderto retrieveasingletoninstanceofyournewsecuritycontrol,whichinturn 4ESAPIDesignPatterns

wouldcallESAPIsecuritycontrolreferenceimplementationsand/or securitycontrolreferenceimplementationsthatwerereplacedwith yourownimplementations. Forexample: IntheESAPIlocatorclass:

... class ESAPI { ... //not defined in ESAPI locator class private static $adapter = null; ... //new function public static function getAdapter() { if ( is_null(self::$adapter) ) { require_once dirname(__FILE__).'/adapters/MyAdapter.php'; self::$adapter = new MyAdapter(); } return self::$adapter; } //new function public static function setAdapter($adapter) { self::$adapter = $adapter; }

Inthenewsecuritycontrolclassinterface:
... //new interface interface Adapter { function getValidEmployeeID($eid); function isValidEmployeeID($eid); }

Inthenewsecuritycontrolclass:
... require_once dirname ( __FILE__ ) . '/../Adapter.php'; //new class with your implementation class MyAdapter implements Adapter { //for your new interface function getValidEmployeeID($eid) { //calls reference implementation $val = ESAPI::getValidator(); //calls using hardcoded parameters $val->getValidInput( "My Organization's Employee ID", $eid, "EmployeeID", //regex defined in ESAPI config 4, false ); }

ESAPIDesignPatterns

//for your new interface function isValidEmployeeID($eid) { try { $this->getValidEmployeeID($eid); return true; } catch ( Exception $e ) { return false; } }

DeveloperswouldcallESAPIinthisexampleasfollows:
... $ESAPI = new ESAPI(); $adapter = ESAPI::getAdapter(); $adapter->isValidEmployeeID(1234); ... //no other ESAPI controls called directly

TheUMLfortheaboveexampleisinthefigurebelow.

Figure4:ExtendedFactoryPatternExample Prosoftakingthisapproacharethesameasfortheextendedsingleton pattern,andadditionallyincludeloosecouplingbetweenESAPIand yourownimplementations,comparedtotheextendedsingleton pattern. ConsincludetheneedtomaintainthemodifiedESAPIlocatorclass(as newversionsofESAPIarereleasedovertime).

6ESAPIDesignPatterns

Where to Go From Here

OWASPisthepremiersiteforWebapplicationsecurity.TheOWASPsite hostsmanyprojects,forums,blogs,presentations,tools,andpapers. Additionally,OWASPhoststwomajorWebapplicationsecurity conferencesperyear,andhasover80localchapters.TheOWASPESAPI projectpagecanbefoundhere http://www.owasp.org/index.php/ESAPI ThefollowingOWASPprojectsaremostlikelytobeusefulto users/adoptersofESAPI: OWASPApplicationSecurityVerificationStandard(ASVS) Projecthttp://www.owasp.org/index.php/ASVS OWASPTopTenProject http://www.owasp.org/index.php/Top_10 OWASPCodeReviewGuide http://www.owasp.org/index.php/Category:OWASP_Code_Revi ew_Project OWASPTestingGuide http://www.owasp.org/index.php/Testing_Guide OWASPLegalProject http://www.owasp.org/index.php/Category:OWASP_Legal_Proj ect

Similarly,thefollowingWebsitesaremostlikelytobeusefulto users/adoptersofESAPI: OWASPhttp://www.owasp.org MITRECommonWeaknessEnumerationVulnerability Trends,http://cwe.mitre.org/documents/vulntrends.html PCISecurityStandardsCouncilpublishersofthePCIstandards, relevanttoallorganizationsprocessingorholdingcreditcard data,https://www.pcisecuritystandards.org PCIDataSecurityStandard(DSS)v1.1 https://www.pcisecuritystandards.org/pdfs/pci_dss_v11.pdf

ESAPIDesignPatterns

Thispageisintentionallyblank

8ESAPIDesignPatterns

Thispageisintentionallyblank

ESAPIDesignPatterns

10ESAPIDesignPatterns