combinedwww.147qqq

WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page1of7612WebServicesSecurity:3SOAPMessageSecurity1.
14(WS-Security2004)5OASISStandardSpecification,1February20066OASISidentifier:7wss-v1.
1-spec-os-SOAPMessageSecurity8Location:9http://docs.
oasis-open.
org/wss/v1.
1/10TechnicalCommittee:11WebServiceSecurity(WSS)12Chairs:13KelvinLawrence,IBM14ChrisKaler,Microsoft15Editors:16AnthonyNadalin,IBM17ChrisKaler,Microsoft18RonaldMonzillo,Sun19PhillipHallam-Baker,Verisign20Abstract:21ThisspecificationdescribesenhancementstoSOAPmessagingtoprovidemessage22integrityandconfidentiality.
Thespecifiedmechanismscanbeusedtoaccommodatea23widevarietyofsecuritymodelsandencryptiontechnologies.
2425Thisspecificationalsoprovidesageneral-purposemechanismforassociatingsecurity26tokenswithmessagecontent.
Nospecifictypeofsecuritytokenisrequired,the27specificationisdesignedtobeextensible(i.
e.
.
supportmultiplesecuritytokenformats).
28Forexample,aclientmightprovideoneformatforproofofidentityandprovideanother29formatforproofthattheyhaveaparticularbusinesscertification.
30WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page2of7631Additionally,thisspecificationdescribeshowtoencodebinarysecuritytokens,a32frameworkforXML-basedtokens,andhowtoincludeopaqueencryptedkeys.
Italso33includesextensibilitymechanismsthatcanbeusedtofurtherdescribethecharacteristics34ofthetokensthatareincludedwithamessage.
35Status:36ThisisanOASISStandarddocumentproducedbytheWebServicesSecurityTechnical37Committee.
ItwasapprovedbytheOASISmembershipon1February2006.
Checkthe38currentlocationnotedaboveforpossibleerratatothisdocument.
39TechnicalCommitteemembersshouldsendcommentsonthisspecificationtothe40technicalCommittee'semaillist.
OthersshouldsendcommentstotheTechnical41Committeebyusingthe"SendAComment"buttonontheTechnicalCommittee'sweb42pageatwww.
oasisopen.
org/committees/wss.
4344Forpatentdisclosureinformationthatmaybeessentialtotheimplementationofthis45specification,andanyoffersoflicensingterms,refertotheIntellectualPropertyRights46sectionoftheOASISWebServicesSecurityTechnicalCommittee(WSSTC)webpage47athttp://www.
oasis-open.
org/committees/wss/ipr.
php.
GeneralOASISIPRinformation48canbefoundathttp://www.
oasis-open.
org/who/intellectualproperty.
shtml.
49WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page3of7650Notices51OASIStakesnopositionregardingthevalidityorscopeofanyintellectualpropertyorotherrights52thatmightbeclaimedtopertaintotheimplementationoruseofthetechnologydescribedinthis53documentortheextenttowhichanylicenseundersuchrightsmightormightnotbevailable;54neitherdoesitrepresentthatithasmadeanyefforttoidentifyanysuchrights.
Informationon55OASIS'sprocedureswithrespecttorightsinOASISspecificationscanbefoundattheOASIS56website.
Copiesofclaimsofrightsmadeavailableforpublicationandanyassurancesoflicenses57tobemadeavailable,ortheresultofanattemptmadetoobtainagenerallicenseorpermission58fortheuseofsuchproprietaryrightsbyimplementorsorusersofthisspecification,canbe59obtainedfromtheOASISExecutiveDirector.
OASISinvitesanyinterestedpartytobringtoits60attentionanycopyrights,patentsorpatentapplications,orotherproprietaryrightswhichmay61covertechnologythatmayberequiredtoimplementthisspecification.
Pleaseaddressthe62informationtotheOASISExecutiveDirector.
6364Copyright(C)OASISOpen2002-2006.
AllRightsReserved.
6566Thisdocumentandtranslationsofitmaybecopiedandfurnishedtoothers,andderivativeworks67thatcommentonorotherwiseexplainitorassistinitsimplementationmaybeprepared,copied,68publishedanddistributed,inwholeorinpart,withoutrestrictionofanykind,providedthatthe69abovecopyrightnoticeandthisparagraphareincludedonallsuchcopiesandderivativeworks.
70However,thisdocumentitselfmaynotbemodifiedinanyway,suchasbyremovingthecopyright71noticeorreferencestoOASIS,exceptasneededforthepurposeofdevelopingOASIS72specifications,inwhichcasetheproceduresforcopyrightsdefinedintheOASISIntellectual73PropertyRightsdocumentmustbefollowed,orasrequiredtotranslateitintolanguagesother74thanEnglish.
7576ThelimitedpermissionsgrantedaboveareperpetualandwillnotberevokedbyOASISorits77successorsorassigns.
7879Thisdocumentandtheinformationcontainedhereinisprovidedonan"ASIS"basisandOASIS80DISCLAIMSALLWARRANTIES,EXPRESSORIMPLIED,INCLUDINGBUTNOTLIMITEDTO81ANYWARRANTYTHATTHEUSEOFTHEINFORMATIONHEREINWILLNOTINFRINGE82ANYRIGHTSORANYIMPLIEDWARRANTIESOFMERCHANTABILITYORFITNESSFORA83PARTICULARPURPOSE.
8485OASIShasbeennotifiedofintellectualpropertyrightsclaimedinregardtosomeorallofthe86contentsofthisspecification.
Formoreinformationconsulttheonlinelistofclaimedrights.
8788Thissectionisnon-normative.
89WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page4of76TableofContents901Introduction7911.
1GoalsandRequirements7921.
1.
1Requirements.
8931.
1.
2Non-Goals.
8942NotationsandTerminology.
9952.
1NotationalConventions.
9962.
2Namespaces9972.
3AcronymsandAbbreviations10982.
4Terminology.
11992.
5NoteonExamples.
121003MessageProtectionMechanisms.
131013.
1MessageSecurityModel.
131023.
2MessageProtection.
131033.
3InvalidorMissingClaims141043.
4Example141054IDReferences.
171064.
1IdAttribute.
171074.
2IdSchema181085SecurityHeader201096SecurityTokens231106.
1AttachingSecurityTokens231116.
1.
1ProcessingRules.
231126.
1.
2SubjectConfirmation.
231136.
2UserNameToken231146.
2.
1Usernames.
231156.
3BinarySecurityTokens241166.
3.
1AttachingSecurityTokens.
241176.
3.
2EncodingBinarySecurityTokens.
241186.
4XMLTokens261196.
5EncryptedDataToken261206.
6IdentifyingandReferencingSecurityTokens261217TokenReferences.
271227.
1SecurityTokenReferenceElement271237.
2DirectReferences.
29124WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page5of767.
3KeyIdentifiers.
301257.
4EmbeddedReferences321267.
5ds:KeyInfo331277.
6KeyNames.
331287.
7EncryptedKeyreference.
341298Signatures.
351308.
1Algorithms351318.
2SigningMessages.
381328.
3SigningTokens.
381338.
4SignatureValidation411348.
5SignatureConfirmation421358.
5.
1ResponseGenerationRules.
431368.
5.
2ResponseProcessingRules.
431378.
6Example441389Encryption451399.
1xenc:ReferenceList451409.
2xenc:EncryptedKey461419.
3EncryptedHeader471429.
4ProcessingRules471439.
4.
1Encryption.
481449.
4.
2Decryption.
481459.
4.
3EncryptionwithEncryptedHeader491469.
4.
4ProcessinganEncryptedHeader.
491479.
4.
5ProcessingthemustUnderstandattributeonEncryptedHeader5014810SecurityTimestamps5114911ExtendedExample.
5415012ErrorHandling.
5715113SecurityConsiderations.
5915213.
1GeneralConsiderations5915313.
2AdditionalConsiderations5915413.
2.
1Replay.
5915513.
2.
2CombiningSecurityMechanisms6015613.
2.
3Challenges.
6015713.
2.
4ProtectingSecurityTokensandKeys.
6015813.
2.
5ProtectingTimestampsandIds6115913.
2.
6ProtectingagainstremovalandmodificationofXMLElements6116013.
2.
7DetectingDuplicateIdentifiers.
6216114InteroperabilityNotes.
63162WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page6of7615PrivacyConsiderations6416316References.
65164AppendixA:Acknowledgements.
67165AppendixB:RevisionHistory70166AppendixC:UtilityElementsandAttributes.
7116716.
1IdentificationAttribute.
7116816.
2TimestampElements7116916.
3GeneralSchemaTypes72170AppendixD:SecurityTokenReferenceModel73171172WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page7of761Introduction173ThisOASISspecificationistheresultofsignificantnewworkbytheWSSTechnicalCommittee174andsupersedestheinputsubmissions,WebServiceSecurity(WS-Security)Version1.
0April5,1752002andWebServicesSecurityAddendumVersion1.
0August18,2002.
176177ThisspecificationproposesastandardsetofSOAP[SOAP11,SOAP12]extensionsthatcanbe178usedwhenbuildingsecureWebservicestoimplementmessagecontentintegrityand179confidentiality.
Thisspecificationreferstothissetofextensionsandmodulesasthe"Web180ServicesSecurity:SOAPMessageSecurity"or"WSS:SOAPMessageSecurity".
181182ThisspecificationisflexibleandisdesignedtobeusedasthebasisforsecuringWebservices183withinawidevarietyofsecuritymodelsincludingPKI,Kerberos,andSSL.
Specifically,this184specificationprovidessupportformultiplesecuritytokenformats,multipletrustdomains,multiple185signatureformats,andmultipleencryptiontechnologies.
Thetokenformatsandsemanticsfor186usingthesearedefinedintheassociatedprofiledocuments.
187188Thisspecificationprovidesthreemainmechanisms:abilitytosendsecuritytokensaspartofa189message,messageintegrity,andmessageconfidentiality.
Thesemechanismsbythemselvesdo190notprovideacompletesecuritysolutionforWebservices.
Instead,thisspecificationisabuilding191blockthatcanbeusedinconjunctionwithotherWebserviceextensionsandhigher-level192application-specificprotocolstoaccommodateawidevarietyofsecuritymodelsandsecurity193technologies.
194195Thesemechanismscanbeusedindependently(e.
g.
,topassasecuritytoken)orinatightly196coupledmanner(e.
g.
,signingandencryptingamessageorpartofamessageandprovidinga197securitytokenortokenpathassociatedwiththekeysusedforsigningandencryption).
1981.
1GoalsandRequirements199ThegoalofthisspecificationistoenableapplicationstoconductsecureSOAPmessage200exchanges.
201202Thisspecificationisintendedtoprovideaflexiblesetofmechanismsthatcanbeusedto203constructarangeofsecurityprotocols;inotherwordsthisspecificationintentionallydoesnot204describeexplicitfixedsecurityprotocols.
205206Aswitheverysecurityprotocol,significanteffortsmustbeappliedtoensurethatsecurity207protocolsconstructedusingthisspecificationarenotvulnerabletoanyoneofawiderangeof208attacks.
Theexamplesinthisspecificationaremeanttoillustratethesyntaxofthesemechanisms209andarenotintendedasexamplesofcombiningthesemechanismsinsecureways.
210Thefocusofthisspecificationistodescribeasingle-messagesecuritylanguagethatprovidesfor211messagesecuritythatmayassumeanestablishedsession,securitycontextand/orpolicy212agreement.
213214WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page8of76Therequirementstosupportsecuremessageexchangearelistedbelow.
2151.
1.
1Requirements216TheWebservicessecuritylanguagemustsupportawidevarietyofsecuritymodels.
The217followinglistidentifiesthekeydrivingrequirementsforthisspecification:218Multiplesecuritytokenformats219Multipletrustdomains220Multiplesignatureformats221Multipleencryptiontechnologies222End-to-endmessagecontentsecurityandnotjusttransport-levelsecurity2231.
1.
2Non-Goals224Thefollowingtopicsareoutsidethescopeofthisdocument:225226Establishingasecuritycontextorauthenticationmechanisms.
227Keyderivation.
228Advertisementandexchangeofsecuritypolicy.
229Howtrustisestablishedordetermined.
230Non-repudiation.
231232WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page9of762NotationsandTerminology233Thissectionspecifiesthenotations,namespaces,andterminologyusedinthisspecification.
2342.
1NotationalConventions235Thekeywords"MUST","MUSTNOT","REQUIRED","SHALL","SHALLNOT","SHOULD",236"SHOULDNOT","RECOMMENDED","MAY",and"OPTIONAL"inthisdocumentaretobe237interpretedasdescribedinRFC2119.
238239Whendescribingabstractdatamodels,thisspecificationusesthenotationalconventionusedby240theXMLInfoset.
Specifically,abstractpropertynamesalwaysappearinsquarebrackets(e.
g.
,241[someproperty]).
242243WhendescribingconcreteXMLschemas,thisspecificationusesaconventionwhereeach244memberofanelement's[children]or[attributes]propertyisdescribedusinganXPath-like245notation(e.
g.
,/x:MyHeader/x:SomeProperty/@value1).
Theuseof{any}indicatesthepresence246ofanelementwildcard().
Theuseof@{any}indicatesthepresenceofanattribute247wildcard().
248249ReadersarepresumedtobefamiliarwiththetermsintheInternetSecurityGlossary[GLOS].
2502.
2Namespaces251NamespaceURIs(ofthegeneralform"some-URI")representssomeapplication-dependentor252context-dependentURIasdefinedinRFC2396[URI].
253254Thisspecificationisbackwardlycompatiblewithversion1.
0.
ThismeansthatURIsandschema255elementsdefinedin1.
0remainunchangedandnewschemaelementsandconstantsaredefined256using1.
1namespacesandURIs.
257258TheXMLnamespaceURIsthatMUSTbeusedbyimplementationsofthisspecificationareas259follows(notethatelementsusedinthisspecificationarefromvariousnamespaces):260261http://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-wssecurity-262secext-1.
0.
xsd263http://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-wssecurity-264utility-1.
0.
xsd265http://docs.
oasis-open.
org/wss/oasis-wss-wssecurity-secext-1.
1.
xsd266267ThisspecificationisdesignedtoworkwiththegeneralSOAP[SOAP11,SOAP12]message268structureandmessageprocessingmodel,andshouldbeapplicabletoanyversionofSOAP.
The269currentSOAP1.
1namespaceURIisusedhereintoprovidedetailedexamples,butthereisno270intentiontolimittheapplicabilityofthisspecificationtoasingleversionofSOAP.
271272WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page10of76Thenamespacesusedinthisdocumentareshowninthefollowingtable(notethatforbrevity,the273examplesusetheprefixeslistedbelowbutdonotincludetheURIs–thoselistedbeloware274assumed).
275276PrefixNamespacedshttp://www.
w3.
org/2000/09/xmldsig#S11http://schemas.
xmlsoap.
org/soap/envelope/S12http://www.
w3.
org/2003/05/soap-envelopewssehttp://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.
0.
xsdwsse11http://docs.
oasis-open.
org/wss/oasis-wss-wssecurity-secext-1.
1.
xsdwsuhttp://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.
0.
xsdxenchttp://www.
w3.
org/2001/04/xmlenc#277TheURLsprovidedforthewsseandwsunamespacescanbeusedtoobtaintheschemafiles.
278279URIfragmentsdefinedinthisdocumentarerelativetothefollowingbaseURIunlessotherwise280stated:281http://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-soap-message-security-1.
02822.
3AcronymsandAbbreviations283Thefollowing(non-normative)tabledefinesacronymsandabbreviationsforthisdocument.
284285TermDefinitionHMACKeyed-HashingforMessageAuthenticationSHA-1SecureHashAlgorithm1SOAPSimpleObjectAccessProtocolURIUniformResourceIdentifierXMLExtensibleMarkupLanguageWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page11of762.
4Terminology286Definedbelowarethebasicdefinitionsforthesecurityterminologyusedinthisspecification.
287288Claim–Aclaimisadeclarationmadebyanentity(e.
g.
name,identity,key,group,privilege,289capability,etc).
290291ClaimConfirmation–Aclaimconfirmationistheprocessofverifyingthataclaimappliesto292anentity.
293294Confidentiality–Confidentialityisthepropertythatdataisnotmadeavailableto295unauthorizedindividuals,entities,orprocesses.
296297Digest–Adigestisacryptographicchecksumofanoctetstream.
298299DigitalSignature–Adigitalsignatureisavaluecomputedwithacryptographicalgorithm300andboundtodatainsuchawaythatintendedrecipientsofthedatacanusethedigitalsignature301toverifythatthedatahasnotbeenalteredand/orhasoriginatedfromthesignerofthemessage,302providingmessageintegrityandauthentication.
Thedigitalsignaturecanbecomputedand303verifiedwithsymmetrickeyalgorithms,wherethesamekeyisusedforsigningandverifying,or304withasymmetrickeyalgorithms,wheredifferentkeysareusedforsigningandverifying(aprivate305andpublickeypairareused).
306307End-To-EndMessageLevelSecurity-End-to-endmessagelevelsecurityis308establishedwhenamessagethattraversesmultipleapplications(oneormoreSOAP309intermediaries)withinandbetweenbusinessentities,e.
g.
companies,divisionsandbusiness310units,issecureoveritsfullroutethroughandbetweenthosebusinessentities.
Thisincludesnot311onlymessagesthatareinitiatedwithintheentitybutalsothosemessagesthatoriginateoutside312theentity,whethertheyareWebServicesorthemoretraditionalmessages.
313314Integrity–Integrityisthepropertythatdatahasnotbeenmodified.
315316MessageConfidentiality-MessageConfidentialityisapropertyofthemessageand317encryptionisthemechanismbywhichthispropertyofthemessageisprovided.
318319MessageIntegrity-MessageIntegrityisapropertyofthemessageanddigitalsignatureisa320mechanismbywhichthispropertyofthemessageisprovided.
321322Signature-Inthisdocument,signatureanddigitalsignatureareusedinterchangeablyand323havethesamemeaning.
324325SecurityToken–Asecuritytokenrepresentsacollection(oneormore)ofclaims.
326327WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page12of76328329SignedSecurityToken–Asignedsecuritytokenisasecuritytokenthatisassertedand330cryptographicallysignedbyaspecificauthority(e.
g.
anX.
509certificateoraKerberosticket).
331332Trust-Trustisthecharacteristicthatoneentityiswillingtorelyuponasecondentitytoexecute333asetofactionsand/ortomakesetofassertionsaboutasetofsubjectsand/orscopes.
3342.
5NoteonExamples335Theexampleswhichappearinthisdocumentareonlyintendedtoillustratethecorrectsyntaxof336thefeaturesbeingspecified.
TheexamplesareNOTintendedtonecessarilyrepresentbest337practiceforimplementinganyparticularsecurityproperties.
338339Specifically,theexamplesareconstrainedtocontainonlymechanismsdefinedinthisdocument.
340Theonlyreasonforthisistoavoidrequiringthereadertoconsultotherdocumentsmerelyto341understandtheexamples.
ItisNOTintendedtosuggestthatthemechanismsillustrated342representbestpracticeorarethestrongestavailabletoimplementthesecuritypropertiesin343question.
Inparticular,mechanismsdefinedinotherTokenProfilesareknowntobestronger,344moreefficientand/orgenerallysuperiortosomeofthemechanismsshownintheexamplesinthis345document.
346347WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page13of763MessageProtectionMechanisms348WhensecuringSOAPmessages,varioustypesofthreatsshouldbeconsidered.
Thisincludes,349butisnotlimitedto:350351themessagecouldbemodifiedorreadbyattackeror352anantagonistcouldsendmessagestoaservicethat,whilewell-formed,lackappropriate353securityclaimstowarrantprocessing354anantagonistcouldalteramessagetotheservicewhichbeingwellformedcausesthe355servicetoprocessandrespondtotheclientforanincorrectrequest.
356357Tounderstandthesethreatsthisspecificationdefinesamessagesecuritymodel.
3583.
1MessageSecurityModel359Thisdocumentspecifiesanabstractmessagesecuritymodelintermsofsecuritytokens360combinedwithdigitalsignaturestoprotectandauthenticateSOAPmessages.
361362Securitytokensassertclaimsandcanbeusedtoassertthebindingbetweenauthentication363secretsorkeysandsecurityidentities.
Anauthoritycanvouchfororendorsetheclaimsina364securitytokenbyusingitskeytosignorencrypt(itisrecommendedtouseakeyedencryption)365thesecuritytokentherebyenablingtheauthenticationoftheclaimsinthetoken.
AnX.
509[X509]366certificate,claimingthebindingbetweenone'sidentityandpublickey,isanexampleofasigned367securitytokenendorsedbythecertificateauthority.
Intheabsenceofendorsementbyathird368party,therecipientofasecuritytokenmaychoosetoaccepttheclaimsmadeinthetokenbased369onitstrustoftheproducerofthecontainingmessage.
370371Signaturesareusedtoverifymessageoriginandintegrity.
Signaturesarealsousedbymessage372producerstodemonstrateknowledgeofthekey,typicallyfromathirdparty,usedtoconfirmthe373claimsinasecuritytokenandthustobindtheiridentity(andanyotherclaimsoccurringinthe374securitytoken)tothemessagestheycreate.
375376Itshouldbenotedthatthissecuritymodel,byitself,issubjecttomultiplesecurityattacks.
Refer377totheSecurityConsiderationssectionforadditionaldetails.
378379Wherethespecificationrequiresthatanelementbe"processed"itmeansthattheelementtype380MUSTberecognizedtotheextentthatanappropriateerrorisreturnediftheelementisnot381supported.
3823.
2MessageProtection383Protectingthemessagecontentfrombeingdisclosed(confidentiality)ormodifiedwithout384detection(integrity)areprimarysecurityconcerns.
Thisspecificationprovidesameanstoprotect385amessagebyencryptingand/ordigitallysigningabody,aheader,oranycombinationofthem(or386partsofthem).
387WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page14of76388MessageintegrityisprovidedbyXMLSignature[XMLSIG]inconjunctionwithsecuritytokensto389ensurethatmodificationstomessagesaredetected.
Theintegritymechanismsaredesignedto390supportmultiplesignatures,potentiallybymultipleSOAPactors/roles,andtobeextensibleto391supportadditionalsignatureformats.
392393MessageconfidentialityleveragesXMLEncryption[XMLENC]inconjunctionwithsecuritytokens394tokeepportionsofaSOAPmessageconfidential.
Theencryptionmechanismsaredesignedto395supportadditionalencryptionprocessesandoperationsbymultipleSOAPactors/roles.
396397Thisdocumentdefinessyntaxandsemanticsofsignatureswithinaelement.
398Thisdocumentdoesnotconstrainanysignatureappearingoutsideofa399element.
4003.
3InvalidorMissingClaims401AmessagerecipientSHOULDrejectmessagescontaininginvalidsignatures,messagesmissing402necessaryclaimsormessageswhoseclaimshaveunacceptablevalues.
Suchmessagesare403unauthorized(ormalformed).
Thisspecificationprovidesaflexiblewayforthemessageproducer404tomakeaclaimaboutthesecuritypropertiesbyassociatingzeroormoresecuritytokenswiththe405message.
Anexampleofasecurityclaimistheidentityoftheproducer;theproducercanclaim406thatheisBob,knownasanemployeeofsomecompany,andthereforehehastherighttosend407themessage.
4083.
4Example409Thefollowingexampleillustratestheuseofacustomsecuritytokenandassociatedsignature.
410Thetokencontainsbase64encodedbinarydataconveyingasymmetrickeywhich,weassume,411canbeproperlyauthenticatedbytherecipient.
Themessageproducerusesthesymmetrickey412withanHMACsigningalgorithmtosignthemessage.
Themessagereceiverusesitsknowledge413ofthesharedsecrettorepeattheHMACkeycalculationwhichitusestovalidatethesignature414andintheprocessconfirmthatthemessagewasauthoredbytheclaimeduseridentity.
415416(001)417(002)419(003)420(004)422(005)425(006)FHUIORv.
.
.
426(007)427(008)428(009)429(010)432(011)435(012)436(013)439(014)LyLsF0Pi4wPU.
.
.
440(015)441(016)442(017)DJbchm5gK.
.
.
443(018)444(019)445(020)446(021)447(022)448(023)449(024)450(025)451(026)452(027)453QQQ454455(028)456(029)457458ThefirsttwolinesstarttheSOAPenvelope.
Line(003)beginstheheadersthatareassociated459withthisSOAPmessage.
460461Line(004)startstheheaderdefinedinthisspecification.
Thisheader462containssecurityinformationforanintendedrecipient.
Thiselementcontinuesuntilline(024).
463464Lines(005)to(007)specifyacustomtokenthatisassociatedwiththemessage.
Inthiscase,it465usesanexternallydefinedcustomtokenformat.
466467Lines(008)to(023)specifyadigitalsignature.
Thissignatureensurestheintegrityofthesigned468elements.
ThesignatureusestheXMLSignaturespecificationidentifiedbythedsnamespace469declarationinLine(002).
470471Lines(009)to(016)describewhatisbeingsignedandthetypeofcanonicalizationbeingused.
472473Line(010)specifieshowtocanonicalize(normalize)thedatathatisbeingsigned.
Lines(012)to474(015)selecttheelementsthataresignedandhowtodigestthem.
Specifically,line(012)475indicatesthattheelementissigned.
Inthisexampleonlythemessagebodyis476signed;typicallyallcriticalelementsofthemessageareincludedinthesignature(seethe477ExtendedExamplebelow).
478479Line(017)specifiesthesignaturevalueofthecanonicalizedformofthedatathatisbeingsigned480asdefinedintheXMLSignaturespecification.
481482WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page16of76Lines(018)to(022)providesinformation,partialorcomplete,astowheretofindthesecurity483tokenassociatedwiththissignature.
Specifically,lines(019)to(021)indicatethatthesecurity484tokencanbefoundat(pulledfrom)thespecifiedURL.
485486Lines(026)to(028)containthebody(payload)oftheSOAPmessage.
487488WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page17of764IDReferences489Therearemanymotivationsforreferencingothermessageelementssuchassignature490referencesorcorrelatingsignaturestosecuritytokens.
Forthisreason,thisspecificationdefines491thewsu:Idattributesothatrecipientsneednotunderstandthefullschemaofthemessagefor492processingofthesecurityelements.
Thatis,theyneedonly"know"thatthewsu:Idattribute493representsaschematypeofIDwhichisusedtoreferenceelements.
However,becausesome494keyschemasusedbythisspecificationdon'tallowattributeextensibility(namelyXMLSignature495andXMLEncryption),thisspecificationalsoallowsuseoftheirlocalIDattributesinadditionto496thewsu:Idattributeandthexml:idattribute[XMLID].
Asaconsequence,whentryingtolocate497anelementreferencedinasignature,thefollowingattributesareconsidered(innoparticular498order):499500LocalIDattributesonXMLSignatureelements501LocalIDattributesonXMLEncryptionelements502Globalwsu:Idattributes(describedbelow)onelements503Profilespecificdefinedidentifiers504Globalxml:idattributesonelements505506Inaddition,whensigningapartofanenvelopesuchasthebody,itisRECOMMENDEDthatan507IDreferenceisusedinsteadofamoregeneraltransformation,especiallyXPath[XPATH].
Thisis508tosimplifyprocessing.
509510Tokensandelementsthataredefinedinthisspecificationandrelatedprofilestousewsu:Id511attributesSHOULDusewsu:Id.
ElementstobesignedMAYusexml:id[XMLID]orwsu:Id,512anduseofxml:idMAYbespecifiedinprofiles.
AllreceiversMUSTbeabletoidentifyXML513elementscarryingawsu:IdattributeasrepresentinganattributeofschematypeIDandprocess514itaccordingly.
515516AllreceiversMAYbeabletoidentifyXMLelementswithaxml:idattributeasrepresentinganID517attributeandprocessitaccordingly.
SendersSHOULDusewsu:IdandMAYusexml:id.
Note518thatuseofxml:idinconjunctionwithinclusivecanonicalizationmaybeinappropriate,asnoted519in[XMLID]andthusthiscombinationSHOULDbeavoided.
5205214.
1IdAttribute522TherearemanysituationswhereelementswithinSOAPmessagesneedtobereferenced.
For523example,whensigningaSOAPmessage,selectedelementsareincludedinthescopeofthe524signature.
XMLSchemaPart2[XMLSCHEMA]providesseveralbuilt-indatatypesthatmaybe525usedforidentifyingandreferencingelements,buttheiruserequiresthatconsumersoftheSOAP526messageeitherhaveormustbeabletoobtaintheschemaswheretheidentityorreference527mechanismsaredefined.
Insomecircumstances,forexample,intermediaries,thiscanbe528problematicandnotdesirable.
529WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page18of76530Consequentlyamechanismisrequiredforidentifyingandreferencingelements,basedonthe531SOAPfoundation,whichdoesnotrelyuponcompleteschemaknowledgeofthecontextinwhich532anelementisused.
ThisfunctionalitycanbeintegratedintoSOAPprocessorssothatelements533canbeidentifiedandreferredtowithoutdynamicschemadiscoveryandprocessing.
534535Thissectionspecifiesanamespace-qualifiedglobalattributeforidentifyinganelementwhichcan536beappliedtoanyelementthateitherallowsarbitraryattributesorspecificallyallowsaparticular537attribute.
538539Alternatively,thexml:idattributeMAYbeused.
ApplicationsMUSTNOTspecifybotha540wsu:Idandxml:idattributeonasingleelement.
ItisanXMLrequirementthatonlyoneid541attributebespecifiedonasingleelement.
5424.
2IdSchema543Tosimplifytheprocessingforintermediariesandrecipients,acommonattributeisdefinedfor544identifyinganelement.
ThisattributeutilizestheXMLSchemaIDtypeandspecifiesacommon545attributeforindicatingthisinformationforelements.
546Thesyntaxforthisattributeisasfollows:547548549550Thefollowingdescribestheattributeillustratedabove:551.
.
.
/@wsu:Id552Thisattribute,definedastypexsd:ID,providesawell-knownattributeforspecifyingthe553localIDofanelement.
554555Twowsu:IdattributeswithinanXMLdocumentMUSTNOThavethesamevalue.
556ImplementationsMAYrelyonXMLSchemavalidationtoproviderudimentaryenforcementfor557intra-documentuniqueness.
However,applicationsSHOULDNOTrelyonschemavalidation558alonetoenforceuniqueness.
559560Thisspecificationdoesnotspecifyhowthisattributewillbeusedanditisexpectedthatother561specificationsMAYaddadditionalsemantics(orrestrictions)fortheirusageofthisattribute.
562Thefollowingexampleillustratesuseofthisattributetoidentifyanelement:563564566567ConformantprocessorsthatdosupportXMLSchemaMUSTtreatthisattributeasifitwas568definedusingaglobalattributedeclaration.
569570ConformantprocessorsthatdonotsupportdynamicXMLSchemaorDTDsdiscoveryand571processingarestronglyencouragedtointegratethisattributedefinitionintotheirparsers.
Thatis,572totreatthisattributeinformationitemasifitsPSVIhasa[typedefinition]which{target573namespace}is"http://www.
w3.
org/2001/XMLSchema"andwhich{type}is"ID.
"Doingso574allowstheprocessortoinherentlyknowhowtoprocesstheattributewithouthavingtolocateand575WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page19of76processtheassociatedschema.
Specifically,implementationsMAYsupportthevalueofthe576wsu:IdasthevalididentifierforuseasanXPointer[XPointer]shorthandpointerfor577interoperabilitywithXMLSignaturereferences.
578WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page20of765SecurityHeader579Theheaderblockprovidesamechanismforattachingsecurity-related580informationtargetedataspecificrecipientintheformofaSOAPactor/role.
Thismaybeeither581theultimaterecipientofthemessageoranintermediary.
Consequently,elementsofthistype582maybepresentmultipletimesinaSOAPmessage.
Anactiveintermediaryonthemessagepath583MAYaddoneormorenewsub-elementstoanexistingheaderblockifthey584aretargetedforitsSOAPnodeoritMAYaddoneormorenewheadersforadditionaltargets.
585586Asstated,amessageMAYhavemultipleheaderblocksiftheyaretargeted587forseparaterecipients.
AmessageMUSTNOThavemultipleheaderblocks588targeted(whetherexplicitlyorimplicitly)atthesamerecipient.
However,onlyone589headerblockMAYomittheS11:actororS12:roleattributes.
Two590headerblocksMUSTNOThavethesamevalueforS11:actoror591S12:role.
MessagesecurityinformationtargetedfordifferentrecipientsMUSTappearin592differentheaderblocks.
Thisisduetopotentialprocessingorderissues593(e.
g.
duetopossibleheaderre-ordering).
Theheaderblockwithouta594specifiedS11:actororS12:roleMAYbeprocessedbyanyone,butMUSTNOTberemoved595priortothefinaldestinationorendpoint.
596597Aselementsareaddedtoaheaderblock,theySHOULDbeprependedto598theexistingelements.
Assuch,theheaderblockrepresentsthesigningand599encryptionstepsthemessageproducertooktocreatethemessage.
Thisprependingrule600ensuresthatthereceivingapplicationcanprocesssub-elementsintheordertheyappearinthe601headerblock,becausetherewillbenoforwarddependencyamongthesub-602elements.
Notethatthisspecificationdoesnotimposeanyspecificorderofprocessingthesub-603elements.
Thereceivingapplicationcanusewhateverorderisrequired.
604605Whenasub-elementreferstoakeycarriedinanothersub-element(forexample,asignature606sub-elementthatreferstoabinarysecuritytokensub-elementthatcontainstheX.
509certificate607usedforthesignature),thekey-bearingelementSHOULDbeorderedtoprecedethekey-using608Element:609610611612.
.
.
613614.
.
.
615616.
.
.
617618.
.
.
619620621Thefollowingdescribestheattributesandelementslistedintheexampleabove:622WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page21of76/wsse:Security623Thisistheheaderblockforpassingsecurity-relatedmessageinformationtoarecipient.
624625/wsse:Security/@S11:actor626ThisattributeallowsaspecificSOAP1.
1[SOAP11]actortobeidentified.
Thisattribute627isoptional;however,notwoinstancesoftheheaderblockmayomitanactororspecify628thesameactor.
629630/wsse:Security/@S12:role631ThisattributeallowsaspecificSOAP1.
2[SOAP12]roletobeidentified.
Thisattributeis632optional;however,notwoinstancesoftheheaderblockmayomitaroleorspecifythe633samerole.
634635/wsse:Security/@S11:mustUnderstand636ThisSOAP1.
1[SOAP11]attributeisusedtoindicatewhetheraheaderentryis637mandatoryoroptionalfortherecipienttoprocess.
ThevalueofthemustUnderstand638attributeiseither"1"or"0".
TheabsenceoftheSOAPmustUnderstandattributeis639semanticallyequivalenttoitspresencewiththevalue"0".
640641/wsse:Security/@S12:mustUnderstand642ThisSOAP1.
2[SPOAP12]attributeisusedtoindicatewhetheraheaderentryis643mandatoryoroptionalfortherecipienttoprocess.
ThevalueofthemustUnderstand644attributeiseither"true","1""false"or"0".
TheabsenceoftheSOAPmustUnderstand645attributeissemanticallyequivalenttoitspresencewiththevalue"false".
646647/wsse:Security/{any}648Thisisanextensibilitymechanismtoallowdifferent(extensible)typesofsecurity649information,basedonaschema,tobepassed.
UnrecognizedelementsSHOULDcause650afault.
651652/wsse:Security/@{any}653Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe654addedtotheheader.
UnrecognizedattributesSHOULDcauseafault.
655656AllcompliantimplementationsMUSTbeabletoprocessaelement.
657658AllcompliantimplementationsMUSTdeclarewhichprofilestheysupportandMUSTbeableto659processaelementincludinganysub-elementswhichmaybedefinedbythat660profile.
ItisRECOMMENDEDthatundefinedelementswithintheheader661notbeprocessed.
662663Thenextfewsectionsoutlineelementsthatareexpectedtobeusedwithina664header.
665666WhenaheaderincludesamustUnderstand="true"attribute:667ThereceiverMUSTgenerateaSOAPfaultifdoesnotimplementtheWSS:SOAP668MessageSecurityspecificationcorrespondingtothenamespace.
Implementationmeans669WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page22of76abilitytointerprettheschemaaswellasfollowtherequiredprocessingrulesspecifiedin670WSS:SOAPMessageSecurity.
671ThereceiverMUSTgenerateafaultifunabletointerpretorprocesssecuritytokens672containedintheheaderblockaccordingtothecorrespondingWSS:673SOAPMessageSecuritytokenprofiles.
674ReceiversMAYignoreelementsorextensionswithintheelement,675basedonlocalsecuritypolicy.
676WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page23of766SecurityTokens677Thischapterspecifiessomedifferenttypesofsecuritytokensandhowtheyareattachedto678messages.
6796.
1AttachingSecurityTokens680Thisspecificationdefinestheheaderasamechanismforconveying681securityinformationwithandaboutaSOAPmessage.
Thisheaderis,bydesign,extensibleto682supportmanytypesofsecurityinformation.
683684ForsecuritytokensbasedonXML,theextensibilityoftheheaderallowsfor685thesesecuritytokenstobedirectlyinsertedintotheheader.
6866.
1.
1ProcessingRules687ThisspecificationdescribestheprocessingrulesforusingandprocessingXMLSignatureand688XMLEncryption.
TheserulesMUSTbefollowedwhenusinganytypeofsecuritytoken.
Note689thatifsignatureorencryptionisusedinconjunctionwithsecuritytokens,theyMUSTbeusedina690waythatconformstotheprocessingrulesdefinedbythisspecification.
6916.
1.
2SubjectConfirmation692Thisspecificationdoesnotdictateifandhowclaimconfirmationmustbedone;however,itdoes693definehowsignaturesmaybeusedandassociatedwithsecuritytokens(byreferencingthe694securitytokensfromthesignature)asaformofclaimconfirmation.
6956.
2UserNameToken6966.
2.
1Usernames697Theelementisintroducedasawayofprovidingausername.
This698elementisoptionallyincludedintheheader.
699Thefollowingillustratesthesyntaxofthiselement:700701702.
.
.
703704705Thefollowingdescribestheattributesandelementslistedintheexampleabove:706707/wsse:UsernameToken708Thiselementisusedtorepresentaclaimedidentity.
709710/wsse:UsernameToken/@wsu:Id711WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page24of76Astringlabelforthissecuritytoken.
Thewsu:Idallowforanopenattributemodel.
712713/wsse:UsernameToken/wsse:Username714Thisrequiredelementspecifiestheclaimedidentity.
715716/wsse:UsernameToken/wsse:Username/@{any}717Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe718addedtotheelement.
719720/wsse:UsernameToken/{any}721Thisisanextensibilitymechanismtoallowdifferent(extensible)typesofsecurity722information,basedonaschema,tobepassed.
UnrecognizedelementsSHOULDcause723afault.
724725/wsse:UsernameToken/@{any}726Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe727addedtotheelement.
UnrecognizedattributesSHOULD728causeafault.
729730AllcompliantimplementationsMUSTbeabletoprocessa731element.
732Thefollowingillustratestheuseofthis:733734735736.
.
.
737738739Zoe740741742.
.
.
743744.
.
.
7457467476.
3BinarySecurityTokens7486.
3.
1AttachingSecurityTokens749Forbinary-formattedsecuritytokens,thisspecificationprovidesa750elementthatcanbeincludedinthe751headerblock.
7526.
3.
2EncodingBinarySecurityTokens753Binarysecuritytokens(e.
g.
,X.
509certificatesandKerberos[KERBEROS]tickets)orothernon-754XMLformatsrequireaspecialencodingformatforinclusion.
Thissectiondescribesabasic755WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page25of76frameworkforusingbinarysecuritytokens.
SubsequentspecificationsMUSTdescribetherules756forcreatingandprocessingspecificbinarysecuritytokenformats.
757758Theelementdefinestwoattributesthatareusedtointerpret759it.
TheValueTypeattributeindicateswhatthesecuritytokenis,forexample,aKerberosticket.
760TheEncodingTypetellshowthesecuritytokenisencoded,forexampleBase64Binary.
761Thefollowingisanoverviewofthesyntax:762763766767Thefollowingdescribestheattributesandelementslistedintheexampleabove:768/wsse:BinarySecurityToken769Thiselementisusedtoincludeabinary-encodedsecuritytoken.
770771/wsse:BinarySecurityToken/@wsu:Id772Anoptionalstringlabelforthissecuritytoken.
773774/wsse:BinarySecurityToken/@ValueType775TheValueTypeattributeisusedtoindicatethe"valuespace"oftheencodedbinary776data(e.
g.
anX.
509certificate).
TheValueTypeattributeallowsaURIthatdefinesthe777valuetypeandspaceoftheencodedbinarydata.
SubsequentspecificationsMUST778definetheValueTypevalueforthetokensthattheydefine.
TheusageofValueTypeis779RECOMMENDED.
780781/wsse:BinarySecurityToken/@EncodingType782TheEncodingTypeattributeisusedtoindicate,usingaURI,theencodingformatofthe783binarydata(e.
g.
,base64encoded).
Anewattributeisintroduced,asthereareissues784withthecurrentschemavalidationtoolsthatmakederivationsofmixedsimpleand785complextypesdifficultwithinXMLSchema.
TheEncodingTypeattributeisinterpreted786toindicatetheencodingformatoftheelement.
Thefollowingencodingformatsarepre-787defined:788789URIDescription#Base64Binary(default)XMLSchemabase64encoding790/wsse:BinarySecurityToken/@{any}791Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe792added.
793794AllcompliantimplementationsMUSTbeabletoprocessa795element.
796WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page26of766.
4XMLTokens797ThissectionpresentsaframeworkforusingXML-basedsecuritytokens.
Profilespecifications798describerulesandprocessesforspecificXML-basedsecuritytokenformats.
7996.
5EncryptedDataToken800Incertaincasesitisdesirablethatthetokenincludedintheheaderbe801encryptedfortherecipientprocessingrole.
Insuchacasethe802elementMAYbeusedtocontainasecuritytokenandincludedinthe803header.
Thatisthisspecificationdefinestheusageoftoencrypt804securitytokenscontainedinheader.
805806Itshouldbenotedthattokenreferencesarenotmadetotheelement,807butinsteadtothetokenrepresentedbytheclear-text,oncethe808elementhasbeenprocessed(decrypted).
Suchreferencesutilizethetokenprofileforthe809containedtoken.
i.
e.
,SHOULDNOTincludeanXMLIDfor810referencingthecontainedsecuritytoken.
811812AlltokensSHOULDeitherhaveanembeddedencryptionkeyor813shouldbereferencedbyaseparateencryptionkey.
814Whenatokenisprocessed,itisreplacedinthemessageinfosetwith815itsdecryptedform.
8166.
6IdentifyingandReferencingSecurityTokens817Thisspecificationalsodefinesmultiplemechanismsforidentifyingandreferencingsecurity818tokensusingthewsu:Idattributeandtheelement(as819wellassomeadditionalmechanisms).
Pleaserefertothespecificprofiledocumentsforthe820appropriatereferencemechanism.
However,specificextensionsMAYbemadetothe821element.
822WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page27of767TokenReferences823Thischapterdiscussesanddefinesmechanismsforreferencingsecuritytokensandotherkey824bearingelements.
.
8257.
1SecurityTokenReferenceElement826Digitalsignatureandencryptionoperationsrequirethatakeybespecified.
Forvariousreasons,827theelementcontainingthekeyinquestionmaybelocatedelsewhereinthemessageor828completelyoutsidethemessage.
Theelementprovides829anextensiblemechanismforreferencingsecuritytokensandotherkeybearingelements.
830831Theelementprovidesanopencontentmodelfor832referencingkeybearingelementsbecausenotallofthemsupportacommonreferencepattern.
833Similarly,somehaveclosedschemasanddefinetheirownreferencemechanisms.
Theopen834contentmodelallowsappropriatereferencemechanismstobeused.
835836Ifaisusedoutsideofthesecurityheaderprocessing837blockthemeaningoftheresponseand/orprocessingrulesoftheresultingreferencesMUSTbe838specifiedbythethespecificprofileandareoutofscopeofthisspecification.
839Thefollowingillustratesthesyntaxofthiselement:840841843844845Thefollowingdescribestheelementsdefinedabove:846847/wsse:SecurityTokenReference848Thiselementprovidesareferencetoasecuritytoken.
849850/wsse:SecurityTokenReference/@wsu:Id851Astringlabelforthissecuritytokenreferencewhichnamesthereference.
Thisattribute852doesnotindicatetheIDofwhatisbeingreferenced,thatSHOULDbedoneusinga853fragmentURIinaelementwithinthe854element.
855856/wsse:SecurityTokenReference/@wsse11:TokenType857Thisoptionalattributeisusedtoidentify,byURI,thetypeofthereferencedtoken.
858Thisspecificationrecommendsthattokenspecificprofilesdefineappropriatetokentype859identifyingURIvalues,andthatthesesameprofilesrequirethatthesevaluesbe860specifiedintheprofiledefinedreferenceforms.
861862WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page28of76Whenawsse11:TokenTypeattributeisspecifiedinconjunctionwitha863wsse:KeyIdentifier/@ValueTypeattributeorawsse:Reference/@ValueType864attributethatindicatesthetypeofthereferencedtoken,thesecuritytokentypeidentified865bythewsse11:TokenTypeattributeMUSTbeconsistentwiththesecuritytokentype866identifiedbythewsse:ValueTypeattribute.
867868URIDescriptionhttp://docs.
oasis-open.
org/wss/oasis-wss-soap-message-security-1.
1#EncryptedKeyAtokentypeofan869/wsse:SecurityTokenReference/@wsse:Usage870Thisoptionalattributeisusedtotypetheusageofthe871.
UsagesarespecifiedusingURIsandmultiple872usagesMAYbespecifiedusingXMLlistsemantics.
Nousagesaredefinedbythis873specification.
874875/wsse:SecurityTokenReference/{any}876Thisisanextensibilitymechanismtoallowdifferent(extensible)typesofsecurity877references,basedonaschema,tobepassed.
UnrecognizedelementsSHOULDcausea878fault.
879880/wsse:SecurityTokenReference/@{any}881Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe882addedtotheheader.
UnrecognizedattributesSHOULDcauseafault.
883884AllcompliantimplementationsMUSTbeabletoprocessa885element.
886887Thiselementcanalsobeusedasadirectchildelementoftoindicateahintto888retrievethekeyinformationfromasecuritytokenplacedsomewhereelse.
Inparticular,itis889RECOMMENDED,whenusingXMLSignatureandXMLEncryption,thata890elementbeplacedinsideatoreference891thesecuritytokenusedforthesignatureorencryption.
892893Thereareseveralchallengesthatimplementationsfacewhentryingtointeroperate.
Processing894theIDsandreferencesrequirestherecipienttounderstandtheschema.
Thismaybean895expensivetaskandinthegeneralcaseimpossibleasthereisnowaytoknowthe"schema896location"foraspecificnamespaceURI.
Aswell,theprimarygoalofareferenceistouniquely897identifythedesiredtoken.
IDreferencesare,bydefinition,uniquebyXML.
However,other898mechanismssuchas"principalname"arenotrequiredtobeuniqueandthereforesuch899referencesmaybenotunique.
900901WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page29of76Thisspecificationallowsfortheuseofmultiplereferencemechanismswithinasingle902.
Whenmultiplereferencesarepresentinagiven903,theyMUSTresolvetoasingletokenincommon.
904SpecifictokenprofilesSHOULDdefinethereferencemechanismstobeused.
905906ThefollowinglistprovidesalistofthespecificreferencemechanismsdefinedinWSS:SOAP907MessageSecurityinpreferredorder(i.
e.
,mostspecifictoleastspecific):908909DirectReferences–ThisallowsreferencestoincludedtokensusingURIfragmentsand910externaltokensusingfullURIs.
911KeyIdentifiers–Thisallowstokenstobereferencedusinganopaquevaluethat912representsthetoken(definedbytokentype/profile).
913KeyNames–Thisallowstokenstobereferencedusingastringthatmatchesanidentity914assertionwithinthesecuritytoken.
Thisisasubsetmatchandmayresultinmultiple915securitytokensthatmatchthespecifiedname.
916EmbeddedReferences-Thisallowstokenstobeembedded(asopposedtoapointer917toatokenthatresideselsewhere).
9187.
2DirectReferences919Theelementprovidesanextensiblemechanismfordirectlyreferencing920securitytokensusingURIs.
921922Thefollowingillustratesthesyntaxofthiselement:923924925926927928Thefollowingdescribestheelementsdefinedabove:929930/wsse:SecurityTokenReference/wsse:Reference931ThiselementisusedtoidentifyanabstractURIlocationforlocatingasecuritytoken.
932933/wsse:SecurityTokenReference/wsse:Reference/@URI934ThisoptionalattributespecifiesanabstractURIforasecuritytoken.
Ifafragmentis935specified,thenitindicatesthelocalIDofthesecuritytokenbeingreferenced.
TheURI936MUSTidentifyasecuritytoken.
TheURIMUSTNOTidentifya937wsse:SecurityTokenReferenceelement,awsse:Embeddedelement,a938wsse:Referenceelement,orawsse:KeyIdentifierelement.
939940/wsse:SecurityTokenReference/wsse:Reference/@ValueType941ThisoptionalattributespecifiesaURIthatisusedtoidentifythetypeoftokenbeing942referenced.
Thisspecificationdoesnotdefineanyprocessingrulesaroundtheusageof943thisattribute,however,specificationsforindividualtokentypesMAYdefinespecific944processingrulesandsemanticsaroundthevalueoftheURIanditsinterpretation.
Ifthis945attributeisnotpresent,theURIMUSTbeprocessedasanormalURI.
946947WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page30of76Inthisversionofthespecificationtheuseofthisattributetoidentifythetypeofthe948referencedsecuritytokenisdeprecated.
Profileswhichrequireorrecommendtheuseof949thisattributetoidentifythetypeofthereferencedsecuritytokenSHOULDevolveto950requireorrecommendtheuseofthe951wsse:SecurityTokenReference/@wsse11:TokenTypeattributetoidentifythetype952ofthereferencedtoken.
953954/wsse:SecurityTokenReference/wsse:Reference/{any}955Thisisanextensibilitymechanismtoallowdifferent(extensible)typesofsecurity956references,basedonaschema,tobepassed.
UnrecognizedelementsSHOULDcausea957fault.
958959/wsse:SecurityTokenReference/wsse:Reference/@{any}960Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe961addedtotheheader.
UnrecognizedattributesSHOULDcauseafault.
962963Thefollowingillustratestheuseofthiselement:9649659679699707.
3KeyIdentifiers971Alternatively,ifadirectreferenceisnotused,thenitisRECOMMENDEDthatakeyidentifierbe972usedtospecify/referenceasecuritytokeninsteadofa.
A973isavaluethatcanbeusedtouniquelyidentifyasecuritytoken(e.
g.
a974hashoftheimportantelementsofthesecuritytoken).
Theexactvaluetypeandgeneration975algorithmvariesbysecuritytokentype(andsometimesbythedatawithinthetoken),976Consequently,thevaluesandalgorithmsaredescribedinthetoken-specificprofilesratherthan977thisspecification.
978979TheelementSHALLisplacedinthe980elementtoreferenceatokenusinganidentifier.
This981elementSHOULDbeusedforallkeyidentifiers.
982983Theprocessingmodelassumesthatthekeyidentifierforasecuritytokenisconstant.
984Consequently,processingakeyidentifierinvolvessimplylookingforasecuritytokenwhosekey985identifiermatchesthespecifiedconstant.
Theelementisonlyallowed986insideaelement987Thefollowingisanoverviewofthesyntax:988989990993WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page31of76.
.
.
994995996997Thefollowingdescribestheattributesandelementslistedintheexampleabove:998999/wsse:SecurityTokenReference/wsse:KeyIdentifier1000Thiselementisusedtoincludeabinary-encodedkeyidentifier.
10011002/wsse:SecurityTokenReference/wsse:KeyIdentifier/@wsu:Id1003Anoptionalstringlabelforthisidentifier.
10041005/wsse:SecurityTokenReference/wsse:KeyIdentifier/@ValueType1006TheoptionalValueTypeattributeisusedtoindicatethetypeofKeyIdentifierbeingused.
1007ThisspecificationdefinesoneValueTypethatcanbeappliedtoalltokentypes.
Eachspecific1008tokenprofilespecifiestheKeyIdentifiertypesthatmaybeusedtorefertotokensofthat1009type.
Italsospecifiesthecriticalsemanticsoftheidentifier,suchaswhetherthe1010KeyIdentifierisuniquetothekeyorthetoken.
Ifnovalueisspecifiedthenthekeyidentifier1011willbeinterpretedinanapplication-specificmanner.
ThisURIfragmentisrelativetoabaseURI1012asndicatedinthetablebelow.
10131014URIDescriptionhttp://docs.
oasis-open.
org/wss/oasis-wss-soap-message-security-1.
1#ThumbPrintSHA1IfthesecuritytokentypethattheSecurityTokenReferencereferstoalreadycontainsarepresentationforthethumbprint,thevalueobtainedfromthetokenMAYbeused.
Ifthetokendoesnotcontainarepresentationofathumbprint,thenthevalueoftheKeyIdentifierMUSTbetheSHA1oftherawoctetswhichwouldbeencodedwithinthesecuritytokenelementwereittobeincluded.
AthumbprintreferenceMUSToccurincombinationwitharequiredtobesupported(bytheapplicableprofile)referenceformunlessathumbprintreferenceisamongthereferenceformsrequiredtobesupportedbytheapplicableprofile,orthepartiestothecommunicationhaveagreedtoacceptthumbprintonlyreferences.
http://docs.
oasis-open.
org/wss/oasis-wss-soap-message-security-1.
1#EncryptedKeySHA1IfthesecuritytokentypethattheSecurityTokenReferencereferstoalreadycontainsarepresentationfortheEncryptedKey,thevalueobtainedfromthetokenMAYbeused.
IfthetokendoesnotcontainarepresentationofaEncryptedKey,thenthevalueoftheKeyIdentifierMUSTbetheSHA1oftheWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page32of76rawoctetswhichwouldbeencodedwithinthesecuritytokenelementwereittobeincluded.
1015/wsse:SecurityTokenReference/wsse:KeyIdentifier/@EncodingType1016TheoptionalEncodingTypeattributeisusedtoindicate,usingaURI,theencoding1017formatoftheKeyIdentifier(#Base64Binary).
Thisspecificationdefinesthe1018EncodingTypeURIvaluesappearinginthefollowingtable.
AtokenspecificprofileMAY1019defineadditionaltokenspecificEncodingTypeURIvalues.
AKeyIdentifierMUST1020includeanEncodingTypeattributewhenitsValueTypeisnotsufficienttoidentifyits1021encodingtype.
Thebasevaluesdefinedinthisspecificationare:10221023URIDescription#Base64BinaryXMLSchemabase64encoding1024/wsse:SecurityTokenReference/wsse:KeyIdentifier/@{any}1025Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe1026added.
10277.
4EmbeddedReferences1028Insomecasesareferencemaybetoanembeddedtoken(asopposedtoapointertoatoken1029thatresideselsewhere).
Todothis,theelementisspecifiedwithina1030element.
Theelementisonly1031allowedinsideaelement.
1032Thefollowingisanoverviewofthesyntax:1033103410351036.
.
.
1037103810391040Thefollowingdescribestheattributesandelementslistedintheexampleabove:10411042/wsse:SecurityTokenReference/wsse:Embedded1043Thiselementisusedtoembedatokendirectlywithinareference(thatis,tocreatea1044localorliteralreference).
10451046/wsse:SecurityTokenReference/wsse:Embedded/@wsu:Id1047Anoptionalstringlabelforthiselement.
Thisallowsthisembeddedtokentobe1048referencedbyasignatureorencryption.
10491050/wsse:SecurityTokenReference/wsse:Embedded/{any}1051Thisisanextensibilitymechanismtoallowanysecuritytoken,basedonschemas,tobe1052embedded.
UnrecognizedelementsSHOULDcauseafault.
1053WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page33of761054/wsse:SecurityTokenReference/wsse:Embedded/@{any}1055Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe1056added.
UnrecognizedattributesSHOULDcauseafault.
10571058ThefollowingexampleillustratesembeddingaSAMLassertion:10591060106110621063.
.
.
1064106510661067.
.
.
1068106910701071.
.
.
107210731074.
.
.
107510767.
5ds:KeyInfo1077Theelement(fromXMLSignature)canbeusedforcarryingthekeyinformation1078andisallowedfordifferentkeytypesandforfutureextensibility.
However,inthisspecification,1079theuseofistheRECOMMENDEDmechanismtocarrykey1080materialifthekeytypecontainsbinarydata.
Pleaserefertothespecificprofiledocumentsforthe1081appropriatewaytocarrykeymaterial.
10821083Thefollowingexampleillustratesuseofthiselementtofetchanamedkey:108410851086CN=HiroshiMaruyama,C=JP108710887.
6KeyNames1089ItisstronglyRECOMMENDEDtouseelements.
However,ifkey1090namesareused,thenitisstronglyRECOMMENDEDthatelementsconformto1091theattributenamesinsection2.
3ofRFC2253(thisisrecommendedbyXMLSignaturefor1092)forinteroperability.
10931094Additionally,e-mailaddresses,SHOULDconformtoRFC822:1095EmailAddress=ckaler@microsoft.
com1096WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page34of767.
7EncryptedKeyreference1097Incertaincases,anelementMAYbeusedtocarrykeymaterial1098encryptedfortherecipient'skey.
ThiskeymaterialishenceforthreferredtoasEncryptedKey.
10991100TheEncryptedKeyMAYbeusedtoperformothercryptographicoperationswithinthesame1101message,suchassignatures.
TheEncryptedKeyMAYalsobeusedforperforming1102cryptographicoperationsinsubsequentmessagesexchangedbythetwoparties.
Two1103mechanismsaredefinedforreferencingtheEncryptedKey.
11041105WhenreferencingtheEncryptedKeywithinthesamemessagethatcontainsthe1106element,theelementofthereferencingconstruct1107MUSTcontaina.
The1108elementMUSTcontainaelement.
11091110TheURIattributevalueoftheelementMUSTbesettothevalueoftheID1111attributeofthereferencedelementthatcontainstheEncryptedKey.
1112WhenreferencingtheEncryptedKeyinamessagethatdoesnotcontainthe1113element,theelementofthereferencingconstruct1114MUSTcontaina.
The1115elementMUSTcontaina1116element.
TheEncodingTypeattributeSHOULDbesetto#Base64Binary.
Otherencoding1117typesMAYbespecifiedifagreedonbyallparties.
Thewsse11:TokenTypeattributeMUSTbe1118setto1119http://docs.
oasis-open.
org/wss/oasis-wss-soap-message-security-11201.
1#EncryptedKey.
TheidentifierforatokenisdefinedastheSHA11121oftheraw(pre-base64encoding)octetsspecifiedintheelementofthe1122referencedtoken.
Thisvalueisencodedasindicatedinthe1123reference.
Theattributeof1124MUSTbesettohttp://docs.
oasis-open.
org/wss/oasis-1125wss-soap-message-security-1.
1#EncryptedKeySHA1.
1126WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page35of768Signatures1127Messageproducersmaywanttoenablemessagerecipientstodeterminewhetheramessage1128wasalteredintransitandtoverifythattheclaimsinaparticularsecuritytokenapplytothe1129producerofthemessage.
11301131Demonstratingknowledgeofaconfirmationkeyassociatedwithatokenkey-claimconfirmsthe1132accompanyingtokenclaims.
Knowledgeofaconfirmationkeymaybedemonstratedbyusing1133thatkeytocreateanXMLSignature,forexample.
Therelyingparty'sacceptanceoftheclaims1134maydependonitsconfidenceinthetoken.
Multipletokensmaycontainakey-claimfora1135signatureandmaybereferencedfromthesignatureusinga1136.
Akey-claimmaybeanX.
509Certificatetoken,ora1137Kerberosservicetickettokentogivetwoexamples.
11381139BecauseofthemutabilityofsomeSOAPheaders,producersSHOULDNOTusetheEnveloped1140SignatureTransformdefinedinXMLSignature.
Instead,messagesSHOULDexplicitlyinclude1141theelementstobesigned.
Similarly,producersSHOULDNOTusetheEnvelopingSignature1142definedinXMLSignature[XMLSIG].
11431144Thisspecificationallowsformultiplesignaturesandsignatureformatstobeattachedtoa1145message,eachreferencingdifferent,evenoverlapping,partsofthemessage.
Thisisimportant1146formanydistributedapplicationswheremessagesflowthroughmultipleprocessingstages.
For1147example,aproducermaysubmitanorderthatcontainsanorderIDheader.
Theproducersigns1148theorderIDheaderandthebodyoftherequest(thecontentsoftheorder).
Whenthisisreceived1149bytheorderprocessingsub-system,itmayinsertashippingIDintotheheader.
Theordersub-1150systemwouldthensign,ataminimum,theorderIDandtheshippingID,andpossiblythebodyas1151well.
Thenwhenthisorderisprocessedandshippedbytheshippingdepartment,ashippedInfo1152headermightbeappended.
Theshippingdepartmentwouldsign,ataminimum,theshippedInfo1153andtheshippingIDandpossiblythebodyandforwardthemessagetothebillingdepartmentfor1154processing.
Thebillingdepartmentcanverifythesignaturesanddetermineavalidchainoftrust1155fortheorder,aswellaswhoauthorizedeachstepintheprocess.
11561157AllcompliantimplementationsMUSTbeabletosupporttheXMLSignaturestandard.
11588.
1Algorithms1159ThisspecificationbuildsonXMLSignatureandthereforehasthesamealgorithmrequirementsas1160thosespecifiedintheXMLSignaturespecification.
1161ThefollowingtableoutlinesadditionalalgorithmsthatarestronglyRECOMMENDEDbythis1162specification:11631164AlgorithmTypeAlgorithmAlgorithmURICanonicalizationExclusiveXMLhttp://www.
w3.
org/2001/10/xml-exc-c14n#WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page36of76Canonicalization1165Aswell,thefollowingtableoutlinesadditionalalgorithmsthatMAYbeused:11661167AlgorithmTypeAlgorithmAlgorithmURITransformSOAPMessageNormalizationhttp://www.
w3.
org/TR/soap12-n11n/1168TheExclusiveXMLCanonicalizationalgorithmaddressesthepitfallsofgeneralcanonicalization1169thatcanoccurfromleakynamespaceswithpre-existingsignatures.
11701171Finally,ifaproducerwishestosignamessagebeforeencryption,thenfollowingtheordering1172ruleslaidoutinsection5,"SecurityHeader",theySHOULDfirstprependthesignatureelementto1173theheader,andthenprependtheencryptionelement,resultingina1174headerthathastheencryptionelementfirst,followedbythesignature1175element:11761177header[encryptionelement][signatureelement].
.
1178Likewise,ifaproducerwishestosignamessageafterencryption,theySHOULDfirstprepend1179theencryptionelementtotheheader,andthenprependthesignature1180element.
Thiswillresultinaheaderthathasthesignatureelementfirst,1181followedbytheencryptionelement:11821183header[signatureelement][encryptionelement].
.
1184TheXMLDigitalSignatureWGhasdefinedtwocanonicalizationalgorithms:XML1185CanonicalizationandExclusiveXMLCanonicalization.
Topreventconfusion,thefirstisalso1186calledInclusiveCanonicalization.
Neitheronesolvesallpossibleproblemsthatcanarise.
The1187followinginformaldiscussionisintendedtoprovideguidanceonthechoiceofwhichonetouse1188inparticularcircumstances.
Foramoredetailedandtechnicallyprecisediscussionofthese1189issuessee:[XML-C14N]and[EXC-C14N].
11901191WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page37of76Therearetwoproblemstobeavoided.
Ontheonehand,XMLallowsdocumentstobechanged1192invariouswaysandstillbeconsideredequivalent.
Forexample,duplicatenamespace1193declarationscanberemovedorcreated.
Asaresult,XMLtoolsmakethesekindsofchanges1194freelywhenprocessingXML.
Therefore,itisvitalthattheseequivalentformsmatchthesame1195signature.
11961197Ontheotherhand,ifthesignaturesimplycoverssomethinglikexx:foo,itsmeaningmaychange1198ifxxisredefined.
Inthiscasethesignaturedoesnotpreventtampering.
Itmightbethoughtthat1199theproblemcouldbesolvedbyexpandingallthevaluesinline.
Unfortunately,thereare1200mechanismslikeXPATHwhichconsiderxx="http://example.
com/";tobedifferentfrom1201yy="http://example.
com/";eventhoughbothxxandyyareboundtothesamenamespace.
1202ThefundamentaldifferencebetweentheInclusiveandExclusiveCanonicalizationisthe1203namespacedeclarationswhichareplacedintheoutput.
InclusiveCanonicalizationcopiesallthe1204declarationsthatarecurrentlyinforce,eveniftheyaredefinedoutsideofthescopeofthe1205signature.
Italsocopiesanyxml:attributesthatareinforce,suchasxml:langorxml:base.
1206Thisguaranteesthatallthedeclarationsyoumightmakeuseofwillbeunambiguouslyspecified.
1207TheproblemwiththisisthatifthesignedXMLismovedintoanotherXMLdocumentwhichhas1208otherdeclarations,theInclusiveCanonicalizationwillcopythenandthesignaturewillbeinvalid.
1209Thiscanevenhappenifyousimplyaddanattributeinadifferentnamespacetothesurrounding1210context.
12111212ExclusiveCanonicalizationtriestofigureoutwhatnamespacesyouareactuallyusingandjust1213copiesthose.
Specifically,itcopiestheonesthatare"visiblyused",whichmeanstheonesthat1214areapartoftheXMLsyntax.
However,itdoesnotlookintoattributevaluesorelementcontent,1215sothenamespacedeclarationsrequiredtoprocessthesearenotcopied.
Forexample1216ifyouhadanattributelikexx:foo="yy:bar"itwouldcopythedeclarationforxx,butnotyy.
(This1217canevenhappenwithoutyourknowledgebecauseXMLprocessingtoolsmightaddxsi:typeif1218youuseaschemasubtype.
)Italsodoesnotcopythexml:attributesthataredeclaredoutsidethe1219scopeofthesignature.
12201221ExclusiveCanonicalizationallowsyoutocreatealistofthenamespacesthatmustbedeclared,1222sothatitwillpickupthedeclarationsfortheonesthatarenotvisiblyused.
Theonlyproblemis1223thatthesoftwaredoingthesigningmustknowwhattheyare.
InatypicalSOAPsoftware1224environment,thesecuritycodewilltypicallybeunawareofallthenamespacesbeingusedbythe1225applicationinthemessagebodythatitissigning.
12261227ExclusiveCanonicalizationisusefulwhenyouhaveasignedXMLdocumentthatyouwishto1228insertintootherXMLdocuments.
AgoodexampleisasignedSAMLassertionwhichmightbe1229insertedasaXMLTokeninthesecurityheaderofvariousSOAPmessages.
TheIssuerwho1230signstheassertionwillbeawareofthenamespacesbeingusedandabletoconstructthelist.
1231TheuseofExclusiveCanonicalizationwillinsurethesignatureverifiescorrectlyeverytime.
1232InclusiveCanonicalizationisusefulinthetypicalcaseofsigningpartoralloftheSOAPbodyin1233accordancewiththisspecification.
Thiswillinsureallthedeclarationsfallunderthesignature,1234eventhoughthecodeisunawareofwhatnamespacesarebeingused.
Atthesametime,itis1235lesslikelythatthesigneddata(andsignatureelement)willbeinsertedinsomeotherXML1236document.
Evenifthisisdesired,itstillmaynotbefeasibleforotherreasons,forexamplethere1237maybeId'swiththesamevaluedefinedinbothXMLdocuments.
12381239WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page38of76Inothersituationsitwillbenecessarytostudytherequirementsoftheapplicationandthe1240detailedoperationofthecanonicalizationmethodstodeterminewhichisappropriate.
1241Thissectionisnon-normative.
12428.
2SigningMessages1243TheheaderblockMAYbeusedtocarryasignaturecompliantwiththeXML1244SignaturespecificationwithinaSOAPEnvelopeforthepurposeofsigningoneormoreelements1245intheSOAPEnvelope.
MultiplesignatureentriesMAYbeaddedintoasingleSOAPEnvelope1246withinoneheaderblock.
ProducersSHOULDsignallimportantelementsof1247themessage,andcarefulthoughtmustbegiventocreatingasigningpolicythatrequiressigning1248ofpartsofthemessagethatmightlegitimatelybealteredintransit.
12491250SOAPapplicationsMUSTsatisfythefollowingconditions:12511252AcompliantimplementationMUSTbecapableofprocessingtherequiredelements1253definedintheXMLSignaturespecification.
1254Toaddasignaturetoaheaderblock,aelement1255conformingtotheXMLSignaturespecificationMUSTbeprependedtotheexisting1256contentoftheheaderblock,inordertoindicatetothereceiverthe1257correctorderofoperations.
Alltheelementscontainedinthe1258signatureSHOULDrefertoaresourcewithintheenclosingSOAPenvelopeasdescribed1259intheXMLSignaturespecification.
However,sincetheSOAPmessageexchangemodel1260allowsintermediateapplicationstomodifytheEnvelope(addordeleteaheaderblock;for1261example),XPathfilteringdoesnotalwaysresultinthesameobjectsaftermessage1262delivery.
CareshouldbetakeninusingXPathfilteringsothatthereisnounintentional1263validationfailureduetosuchmodifications.
1264Theproblemofmodificationbyintermediaries(especiallyactiveones)isapplicableto1265morethanjustXPathprocessing.
Digitalsignatures,becauseofcanonicalizationand1266digests,presentparticularlyfragileexamplesofsuchrelationships.
Ifoverallmessage1267processingistoremainrobust,intermediariesmustexercisecarethatthetransformation1268algorithmsuseddonotaffectthevalidityofadigitallysignedcomponent.
1269Duetosecurityconcernswithnamespaces,thisspecificationstronglyRECOMMENDS1270theuseofthe"ExclusiveXMLCanonicalization"algorithmoranothercanonicalization1271algorithmthatprovidesequivalentorgreaterprotection.
1272ForprocessingefficiencyitisRECOMMENDEDtohavethesignatureaddedandthen1273thesecuritytokenpre-pendedsothataprocessorcanreadandcachethetokenbeforeit1274isused.
12758.
3SigningTokens1276Itisoftendesirabletosignsecuritytokensthatareincludedinamessageorevenexternaltothe1277message.
TheXMLSignaturespecificationprovidesseveralcommonwaysforreferencing1278informationtobesignedsuchasURIs,IDs,andXPath,butsometokenformatsmaynotallow1279tokenstobereferencedusingURIsorIDsandXPathsmaybeundesirableinsomesituations.
1280Thisspecificationallowsdifferenttokenstohavetheirownuniquereferencemechanismswhich1281arespecifiedintheirprofileasextensionstotheelement.
1282WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page39of76Thiselementprovidesauniformreferencingmechanismthatisguaranteedtoworkwithalltoken1283formats.
Consequently,thisspecificationdefinesanewreferenceoptionforXMLSignature:the1284STRDereferenceTransform.
12851286ThistransformisspecifiedbytheURI#STR-Transformandwhenappliedtoa1287elementitmeansthattheoutputisthetokenreferenced1288bytheelementnottheelementitself.
12891290Asanoverviewtheprocessingmodelistoechotheinputtothetransformexceptwhena1291elementisencountered.
Whenoneisfound,theelement1292isnotechoed,butinstead,itisusedtolocatethetoken(s)matchingthecriteriaandrulesdefined1293bytheelementandechoit(them)totheoutput.
1294Consequently,theoutputofthetransformationistheresultantsequencerepresentingtheinput1295withanyelementsreplacedbythereferencedsecurity1296token(s)matched.
12971298Thefollowingillustratesanexampleofthistransformationwhichreferencesatokencontained1299withinthemessageenvelope:13001301.
.
.
13021303.
.
.
13041305.
.
.
130613071308.
.
.
130913101311131313141317131813191321.
.
.
13221323132413251326.
.
.
13271328Thefollowingdescribestheattributesandelementslistedintheexampleabove:13291330/wsse:TransformationParameters1331WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page40of76Thiselementisusedtowrapparametersforatransformationallowselementsevenfrom1332theXMLSignaturenamespace.
13331334/wsse:TransformationParameters/ds:Canonicalization1335Thisspecifiesthecanonicalizationalgorithmtoapplytotheselecteddata.
13361337/wsse:TransformationParameters/{any}1338Thisisanextensibilitymechanismtoallowdifferent(extensible)parameterstobe1339specifiedinthefuture.
UnrecognizedparametersSHOULDcauseafault.
13401341/wsse:TransformationParameters/@{any}1342Thisisanextensibilitymechanismtoallowadditionalattributes,basedonschemas,tobe1343addedtotheelementinthefuture.
UnrecognizedattributesSHOULDcauseafault.
13441345Thefollowingisadetailedspecificationofthetransformation.
Thealgorithmisidentifiedbythe1346URI:#STR-Transform.
13471348TransformInput:1349Theinputisanodeset.
Iftheinputisanoctetstream,thenitisautomaticallyparsed;cf.
1350XMLDigitalSignature[XMLSIG].
1351TransformOutput:1352Theoutputisanoctetsteam.
1353Syntax:1354Thetransformtakesasinglemandatoryparameter,a1355element,whichisusedtoserializetheoutputnode1356set.
Note,however,thattheoutputmaynotbestrictlyincanonicalform,perthe1357canonicalizationalgorithm;however,theoutputiscanonical,inthesensethatitis1358unambiguous.
However,becauseofsyntaxrequirementsintheXMLSignature1359definition,thisparameterMUSTbewrappedina1360element.
13611362ProcessingRules:1363LetNbetheinputnodeset.
1364LetRbethesetofallelementsinN.
1365ForeachRiinR,letDibetheresultofdereferencingRi.
1366IfDicannotbedetermined,thenthetransformMUSTsignalafailure.
1367IfDiisanXMLsecuritytoken(e.
g.
,aSAMLassertionora1368element),thenletRi'beDi.
Otherwise,Diisaraw1369binarysecuritytoken;i.
e.
,anoctetstream.
Inthiscase,letRi'beanodesetconsistingof1370aelement,utilizingthesamenamespaceprefixas1371theelementRi,withnoEncodingTypeattribute,1372aValueTypeattributeidentifyingthecontentofthesecuritytoken,andtextcontent1373consistingofthebinary-encodedsecuritytoken,withnowhitespace.
1374Finally,employthecanonicalizationmethodspecifiedasaparametertothetransformto1375serializeNtoproducetheoctetstreamoutputofthistransform;but,inplaceofany1376dereferencedelementRianditsdescendants,1377WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page41of76processthedereferencednodesetRi'instead.
Duringthisstep,canonicalizationofthe1378replacementnodesetMUSTbeaugmentedasfollows:1379oNote:Anamespacedeclarationxmlns=""MUSTbeemittedwitheveryapex1380elementthathasnonamespacenodedeclaringavalueforthedefault1381namespace;cf.
XMLDecryptionTransform.
1382Note:Pertheprocessingrulesabove,any1383elementiseffectivelyreplacedbythereferenced1384elementandthentheiscanonicalizedinthat1385context.
Eachneedstobecompleteinagiven1386context,soanynecessarynamespacedeclarationsthatarenotpresentonanancestor1387elementwillneedtobeaddedtotheelementpriorto1388canonicalization.
13891390Signinga(STR)elementprovidesauthentication1391andintegrityprotectionofonlytheSTRandnotthereferencedsecuritytoken(ST).
If1392signingtheSTistheintendedbehavior,theSTRDereferenceTransform(STRDT)may1393beusedwhichreplacestheSTRwiththeSTfordigestcomputation,effectivelyprotecting1394theSTandnottheSTR.
IfprotectingboththeSTandtheSTRisdesired,youmaysign1395theSTRtwice,onceusingtheSTRDTandoncenotusingtheSTRDT.
13961397ThefollowingtableliststhefullURIforeachURIfragmentreferredtointhespecification.
13981399URIFragmentFullURI#Base64Binaryhttp://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-soap-message-security-1.
0#Base64Binary#STR-Transformhttp://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-soap-message-security-1.
0#STRTransform#X509v3http://docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-soap-message-security-1.
0#X509v38.
4SignatureValidation1400Thevalidationofaelementinsideanheaderblock1401MUSTfailif:1402thesyntaxofthecontentoftheelementdoesnotconformtothisspecification,or1403thevalidationofthesignaturecontainedintheelementfailsaccordingtothecore1404validationoftheXMLSignaturespecification[XMLSIG],or1405theapplicationapplyingitsownvalidationpolicyrejectsthemessageforsomereason1406(e.
g.
,thesignatureiscreatedbyanuntrustedkey–verifyingtheprevioustwostepsonly1407performscryptographicvalidationofthesignature).
14081409Ifthevalidationofthesignatureelementfails,applicationsMAYreportthefailuretotheproducer1410usingthefaultcodesdefinedinSection12ErrorHandling.
14111412Thesignaturevalidationshalladditionallyadheretotherulesdefinesinsignatureconfirmation1413sectionbelow,iftheinitiatordesiressignatureconfirmation:1414WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page42of768.
5SignatureConfirmation1415Inthegeneralmodel,theinitiatorusesXMLSignatureconstructstorepresentmessagepartsof1416therequestthatweresigned.
ThemanifestofsignedSOAPelementsiscontainedinthe1417elementwhichinturnisplacedinsidetheheader.
The1418elementoftherequestcontainsa.
Thiselement1419containsabase64encodedvaluerepresentingtheactualdigitalsignature.
Incertainsituationsit1420isdesirablethatinitiatorconfirmsthatthemessagereceivedwasgeneratedinresponsetoa1421messageitinitiatedinitsunalteredform.
Thishelpspreventcertainformsofattack.
This1422specificationintroducesaelementtoaddressthis1423necessity.
14241425Compliantresponderimplementationsthatsupportsignatureconfirmation,MUSTincludea1426elementinsidetheheaderofthe1427associatedresponsemessageforeveryelementthatisadirectchildofthe1428headerblockintheoriginatingmessage.
TheresponderMUSTincludethe1429contentsoftheelementoftherequestsignatureasthevalueofthe1430@Valueattributeoftheelement.
The1431elementMUSTbeincludedinthemessagesignatureof1432theassociatedresponsemessage.
14331434Iftheassociatedoriginatingsignatureisreceivedinencryptedformthenthecorresponding1435elementSHOULDbeencryptedtoprotecttheoriginal1436signatureandkeys.
14371438Theschemaoutlineforthiselementisasfollows:14391440reference1449listofthesignatureoftheassociatedresponsemessage.
ThisattributeMUSTbepresent1450sothatun-ambiguousreferencescanbemadetothis1451element.
14521453/wsse11:SignatureConfirmation/@Value1454Thisoptionalattributecontainsthecontentsofacopiedfrom1455theassociatedrequest.
Iftherequestwasnotsigned,thenthisattributeMUSTNOTbe1456present.
Ifthisattributeisspecifiedwithanemptyvalue,theinitiatorSHOULDinterpret1457thisasincorrectbehaviorandprocessaccordingly.
Whenthisattributeisnotpresent,the1458initiatorSHOULDinterpretthistomeanthattheresponseisbasedonarequestthatwas1459notsigned.
1460WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page43of768.
5.
1ResponseGenerationRules1461ConformantrespondersMUSTincludeatleastone.
1462elementintheheaderinanyresponse(s)associatedwithrequests.
Thatis,1463thenormalmessagingpatternsarenotaltered.
1464Foreveryresponsemessagegenerated,theresponderMUSTincludea1465elementforeveryelementit1466processedfromtheoriginalrequestmessage.
TheValueattributeMUSTbesettotheexact1467valueoftheelementofthecorrespondingelement.
1468Ifnoelementsarepresentintheoriginalrequestmessage,theresponder1469MUSTincludeexactlyoneelement.
TheValueattribute1470oftheelementMUSTNOTbepresent.
Theresponder1471MUSTincludeallelementsinthemessagesignatureof1472theresponsemessage(s).
Iftheelementcorrespondingtoa1473elementwasencryptedintheoriginalrequestmessage,1474theelementSHOULDbeencryptedfortherecipientof1475theresponsemessage(s).
147614778.
5.
2ResponseProcessingRules1478Thesignaturevalidationshalladditionallyadheretothefollowingprocessingguidelines,ifthe1479initiatordesiressignatureconfirmation:1480Ifaresponsemessagedoesnotcontaina1481elementinsidetheheader,theinitiatorSHOULDrejecttheresponse1482message.
1483Ifaresponsemessagedoescontainaelement1484insidetheheaderbut@Valueattributeisnotpresenton1485element,andtheassociatedrequestmessage1486didincludeaelement,theinitiatorSHOULDrejecttheresponse1487message.
1488Ifaresponsemessagedoescontainaelement1489insidetheheaderandthe@Valueattributeispresentonthe1490element,buttheassociatedrequestdidnot1491includeaelement,theinitiatorSHOULDrejecttheresponse1492message.
1493Ifaresponsemessagedoescontainaelement1494insidetheheader,andtheassociatedrequestmessagedidinclude1495aelementandthe@Valueattributeispresentbutdoesnotmatchthe1496storedsignaturevalueoftheassociatedrequestmessage,theinitiatorSHOULDreject1497theresponsemessage.
1498Ifaresponsemessagedoesnotcontaina1499elementinsidetheheadercorrespondingtoeach1500elementorifthe@Valueattributepresentdoesnotmatchthestored1501signaturevaluesoftheassociatedrequestmessage,theinitiatorSHOULDrejectthe1502responsemessage.
1503WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page44of768.
6Example1504Thefollowingsamplemessageillustratestheuseofintegrityandsecuritytokens.
Forthis1505example,onlythemessagebodyissigned.
1506150715081510151115121516MIIEZzCCA9CgAwIBAgIQEmtJZc0rqrKh5i.
.
.
15171518151915201522152415251526152815291531EULddytSo1.
.
.
1532153315341535BL8jdfToEb1l/vXcMZNNjPOV.
.
.
153615371538153915401541154215431544154515461547QQQ1548154915501551WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page45of769Encryption1552Thisspecificationallowsencryptionofanycombinationofbodyblocks,headerblocks,andanyof1553thesesub-structuresbyeitheracommonsymmetrickeysharedbytheproducerandtherecipient1554orasymmetrickeycarriedinthemessageinanencryptedform.
15551556Inordertoallowthisflexibility,thisspecificationleveragestheXMLEncryptionstandard.
This1557specificationdescribeshowthetwoelementsand1558listedbelowanddefinedinXMLEncryptioncanbeusedwithinthe1559headerblock.
Whenaproduceroranactiveintermediaryencrypts1560portion(s)ofaSOAPmessageusingXMLEncryptionitMUSTprependasub-elementtothe1561headerblock.
Furthermore,theencryptingpartyMUSTeitherprependthe1562sub-elementtoanexistingheaderblockfortheintendedrecipientsorcreate1563anewheaderblockandinsertthesub-element.
Thecombinedprocessof1564encryptingportion(s)ofamessageandaddingoneofthesesub-elementsiscalledanencryption1565stephereafter.
Thesub-elementMUSTcontaintheinformationnecessaryfortherecipientto1566identifytheportionsofthemessagethatitisabletodecrypt.
15671568Thisspecificationadditionallydefinesanelementforcontaining1569encryptedSOAPheaderblocks.
ThisspecificationRECOMMENDSanadditionalmechanismthat1570usesthiselementforencryptingSOAPheaderblocksthatcomplieswithSOAPprocessing1571guidelineswhilepreservingtheconfidentialityofattributesontheSOAPheaderblocks.
1572AllcompliantimplementationsMUSTbeabletosupporttheXMLEncryptionstandard[XMLENC].
15739.
1xenc:ReferenceList1574TheelementfromXMLEncryption[XMLENC]MAYbeusedto1575createamanifestofencryptedportion(s),whichareexpressedas1576elementswithintheenvelope.
Anelementorelementcontenttobeencryptedbythisencryption1577stepMUSTbereplacedbyacorrespondingaccordingtoXML1578Encryption.
Alltheelementscreatedbythisencryptionstep1579SHOULDbelistedinelementsinsideoneormore1580element.
15811582AlthoughinXMLEncryption[XMLENC],wasoriginallydesignedto1583beusedwithinanelement(whichimpliesthatallthereferenced1584elementsareencryptedbythesamekey),thisspecificationallows1585thatelementsreferencedbythesame1586MAYbeencryptedbydifferentkeys.
Eachencryptionkeycanbespecifiedin1587withinindividual.
15881589Atypicalsituationwherethesub-elementisusefulisthatthe1590producerandtherecipientuseasharedsecretkey.
Thefollowingillustratestheuseofthissub-1591element:1592WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page46of76159315951596159715981599160016011602160316041605CN=HiroshiMaruyama,C=JP160616071608.
.
.
160916101611161216139.
2xenc:EncryptedKey1614WhentheencryptionstepinvolvesencryptingelementsorelementcontentswithinaSOAP1615envelopewithasymmetrickey,whichisinturntobeencryptedbytherecipient'skeyand1616embeddedinthemessage,MAYbeusedforcarryingsuchan1617encryptedkey.
Thissub-elementMAYcontainamanifest,thatis,an1618element,thatliststheportionstobedecryptedwiththiskey.
ThemanifestMAYappearoutside1619theprovidedthatthecorrespondingxenc:EncryptedData1620elementscontainelementsthatreferencethe1621element.
.
AnelementorelementcontenttobeencryptedbythisencryptionstepMUSTbe1622replacedbyacorrespondingaccordingtoXMLEncryption.
Allthe1623elementscreatedbythisencryptionstepSHOULDbelistedinthe1624elementinsidethissub-element.
16251626Thisconstructisusefulwhenencryptionisdonebyarandomlygeneratedsymmetrickeythatis1627inturnencryptedbytherecipient'spublickey.
Thefollowingillustratestheuseofthiselement:162816291631163216331634.
.
.
16351636163716381639DC=ACMECorp,DC=com1640WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page47of761641123456781642164316441645.
.
.
16461647.
.
.
164816491650165116521653.
.
.
165416551656165716581659WhileXMLEncryptionspecifiesthatelementsMAYbespecifiedin1660elements,thisspecificationstronglyRECOMMENDSthat1661elementsbeplacedintheheader.
16629.
3EncryptedHeader1663InordertobecompliantwithSOAPmustUnderstandprocessingguidelinesandtoprevent1664disclosureofinformationcontainedinattributesonaSOAPheaderblock,thisspecification1665introducesanelement.
Thiselementcontainsexactlyone1666element.
ThisspecificationRECOMMENDStheuseof1667elementforencryptingSOAPheaderblocks.
16689.
4ProcessingRules1669Encryptedpartsorusingoneofthesub-elementsdefinedaboveMUSTbeincompliancewiththe1670XMLEncryptionspecification.
AnencryptedSOAPenvelopeMUSTstillbeavalidSOAP1671envelope.
ThemessagecreatorMUSTNOTencryptthe,,1672,,or,elementsbutMAY1673encryptchildelementsofeitherthe,andor1674elements.
MultiplestepsofencryptionMAYbeaddedintoasingle1675headerblockiftheyaretargetedforthesamerecipient.
16761677WhenanelementorelementcontentinsideaSOAPenvelope(e.
g.
thecontentsofthe1678orelements)aretobeencrypted,itMUSTbereplacedbyan1679,accordingtoXMLEncryptionanditSHOULDbereferencedfromthe1680elementcreatedbythisencryptionstep.
Ifthetargetofreferenceis1681anEncryptedHeaderasdefinedinsection9.
3above,seeprocessingrulesdefinedinsection16829.
5.
3EncryptionusingEncryptedHeaderandsection9.
5.
4DecryptionofEncryptedHeader1683below.
1684WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page48of769.
4.
1Encryption1685Thegeneralsteps(non-normative)forcreatinganencryptedSOAPmessageincompliancewith1686thisspecificationarelistedbelow(notethatuseofis1687RECOMMENDED.
Additionally,ifthetargetofencryptionisaSOAPheader,processingrules1688definedinsection9.
5.
3SHOULDbeused).
1689CreateanewSOAPenvelope.
1690Createaheader1691Whenanisused,createasub-1692elementoftheelement.
Thissub-1693elementSHOULDcontainansub-element,containinga1694toeachelementthatwas1695encryptedusingthatkey.
1696Locatedataitemstobeencrypted,i.
e.
,XMLelements,elementcontentswithinthetarget1697SOAPenvelope.
1698Encryptthedataitemsasfollows:ForeachXMLelementorelementcontentwithinthe1699targetSOAPenvelope,encryptitaccordingtotheprocessingrulesoftheXML1700Encryptionspecification[XMLENC].
Eachselectedoriginalelementorelementcontent1701MUSTberemovedandreplacedbytheresultingelement.
1702TheoptionalelementintheelementMAY1703referenceanotherelement.
Notethatiftheencryptionisbasedonan1704attachedsecuritytoken,thenaelementSHOULD1705beaddedtotheelementtofacilitatelocatingit.
1706Createanelementreferencingthegenerated1707elements.
Addthecreated1708elementtothe.
1709Copyallnon-encrypteddata.
17109.
4.
2Decryption1711OnreceivingaSOAPenvelopecontainingencryptionheaderelements,foreachencryption1712headerelementthefollowinggeneralstepsshouldbeprocessed(thissectionisnon-normative.
1713Additionally,ifthetargetofreferenceisanEncryptedHeader,processingrulesasdefinedin1714section9.
5.
4belowSHOULDbeused):171517161.
Identifyanydecryptionkeysthatareintherecipient'spossession,thenidentifyingany1717messageelementsthatitisabletodecrypt.
17182.
Locatetheitemstobedecrypted(possiblyusingthe1719).
17203.
Decryptthemasfollows:1721a.
ForeachelementinthetargetSOAPenvelope,decryptitaccordingtothe1722processingrulesoftheXMLEncryptionspecificationandtheprocessingrules1723listedabove.
1724b.
Ifthedecryptionfailsforsomereason,applicationsMAYreportthefailuretothe1725producerusingthefaultcodedefinedinSection12ErrorHandlingofthis1726specification.
1727WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page49of76c.
ItispossibleforoverlappingportionsoftheSOAPmessagetobeencryptedin1728suchawaythattheyareintendedtobedecryptedbySOAPnodesactingin1729differentRoles.
Inthiscase,theor1730elementsidentifyingtheseencryptionoperationswill1731necessarilyappearindifferentheaders.
SinceSOAPdoes1732notprovideanymeansofspecifyingtheorderinwhichdifferentRoleswill1733processtheirrespectiveheaders,thisorderisnotspecifiedbythisspecification1734andcanonlybedeterminedbyaprioragreement.
17359.
4.
3EncryptionwithEncryptedHeader1736WhenitisrequiredthatanentireSOAPheaderblockincludingthetop-levelelementandits1737attributesbeencrypted,theoriginalheaderblockSHOULDbereplacedwitha1738element.
TheelementMUST1739containtheproducedbyencryptingtheheaderblock.
Awsu:Idattribute1740MAYbeaddedtotheelementforreferencing.
Ifthereferencing1741headerblockdefinesavaluefortheor1742attribute,thatattributeandassociatedvalueMUSTbecopiedtothe1743element.
Ifthereferencingheaderblock1744definesavaluefortheS12:roleorS11:actorattribute,thatattributeandassociatedvalue1745MUSTbecopiedtotheelement.
Ifthereferencing1746headerblockdefinesavaluefortheS12:relayattribute,thatattributeand1747associatedvalueMUSTbecopiedtotheelement.
17481749Anyheaderblockcanbereplacedwithacorrespondingheader1750block.
Thisincludesheaderblocks.
(Inthiscase,obviouslyiftheencryption1751operationisspecifiedinthesamesecurityheaderorinasecurityheadertargetedatanode1752whichisreachedafterthenodetargetedbytheelement,the1753decryptionwillnotoccur.
)17541755Inaddition,headerblockscanbesuper-encryptedandreplaced1756byotherheaderblocks(forwrapping/tunnelingscenarios).
Any1757headerthatencryptsaheaderblocktargetedtoaparticularactorSHOULD1758betargetedtothatsameactor,unlessitisasecurityheader.
17599.
4.
4ProcessinganEncryptedHeader1760Theprocessingmodelforheaderblocksisasfollows:17611.
Resolvereferencestoencrypteddataspecifiedintheheaderblock1762targetedatthisnode.
Foreachreference,performthefollowingsteps.
17632.
Ifthereferencedelementdoesnothaveaqualifiednameof1764thenprocessaspersection9.
5.
2Decryptionandstop1765theprocessingstepshere.
17663.
Otherwise,extracttheelementfromthe1767element.
1768WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page50of764.
Decryptthecontentsoftheelementaspersection9.
5.
21769Decryptionandreplacetheelementwiththedecrypted1770contents.
17715.
ProcessthedecryptedheaderblockasperSOAPprocessingguidelines.
17721773Alternatively,aprocessormayperformapre-passovertheencryptionreferencesinthe1774header:17751.
Resolvereferencestoencrypteddataspecifiedintheheaderblock1776targetedatthisnode.
Foreachreference,performthefollowingsteps.
17772.
Ifareferencedelementhasaqualifiednameofthen1778replacetheelementwiththecontained1779elementandifpresentcopythevalueofthewsu:Idattribute1780fromtheelementtothe1781element.
17823.
Processtheheaderblockasnormal.
17831784Itshouldbenotedthattheresultsofdecryptingaheaderblock1785couldbeanotherheaderblock.
Inaddition,theresultMAYbe1786targetedatadifferentrolethantheroleprocessingtheheader1787block.
17889.
4.
5ProcessingthemustUnderstandattributeonEncryptedHeader1789IftheS11:mustUnderstandorS12:mustUnderstandattributeisspecifiedonthe1790headerblock,andistrue,thenthefollowingstepsdefinewhatit1791meansto"understand"theheaderblock:17921.
TheprocessorMUSTbeawareofthiselementandknowhowtodecryptandconvertinto1793theoriginalheaderblock.
ThisDOESNOTREQUIREthattheprocessknowthatithas1794thecorrectkeysorsupporttheindicatedalgorithms.
17952.
TheprocessorMUST,afterdecryptingtheencryptedheaderblock,processthe1796decryptedheaderblockaccordingtotheSOAPprocessingguidelines.
Thereceiver1797MUSTraiseafaultifanycontentrequiredtoadequatelyprocesstheheaderblock1798remainsencryptedorifthedecryptedSOAPheaderisnotunderstoodandthevalueof1799theS12:mustUnderstandorS11:mustUnderstandattributeonthedecrypted1800headerblockistrue.
NotethatinordertocomplywithSOAPprocessingrulesinthis1801case,theprocessormustrollbackanypersistenteffectsofprocessingthesecurity1802header,suchasstoringareceivedtoken.
18031804WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page51of7610SecurityTimestamps1805Itisoftenimportantfortherecipienttobeabletodeterminethefreshnessofsecuritysemantics.
1806Insomecases,securitysemanticsmaybesostalethattherecipientmaydecidetoignoreit.
1807Thisspecificationdoesnotprovideamechanismforsynchronizingtime.
Theassumptionisthat1808timeistrustedoradditionalmechanisms,notdescribedhere,areemployedtopreventreplay.
1809Thisspecificationdefinesandillustratestimereferencesintermsofthexsd:dateTimetype1810definedinXMLSchema.
ItisRECOMMENDEDthatalltimereferencesusethistype.
All1811referencesMUSTbeinUTCtime.
ImplementationsMUSTNOTgeneratetimeinstantsthat1812specifyleapseconds.
If,however,othertimetypesareused,thentheValueTypeattribute1813(describedbelow)MUSTbespecifiedtoindicatethedatatypeofthetimeformat.
Requestorsand1814receiversSHOULDNOTrelyonotherapplicationssupportingtimeresolutionfinerthan1815milliseconds.
18161817Theelementprovidesamechanismforexpressingthecreationand1818expirationtimesofthesecuritysemanticsinamessage.
18191820AlltimesMUSTbeinUTCformatasspecifiedbytheXMLSchematype(dateTime).
Itshouldbe1821notedthattimessupporttimeprecisionasdefinedintheXMLSchemaspecification.
1822Theelementisspecifiedasachildoftheheaderand1823mayonlybepresentatmostonceperheader(thatis,perSOAPactor/role).
18241825Theorderingwithintheelementisasillustratedbelow.
Theorderingofelementsinthe1826elementisfixedandMUSTbepreservedbyintermediaries.
1827Theschemaoutlinefortheelementisasfollows:18281829183018311832.
.
.
183318341835Thefollowingdescribestheattributesandelementslistedintheschemaabove:18361837/wsu:Timestamp1838Thisistheelementforindicatingsecuritysemanticstimestamps.
18391840/wsu:Timestamp/wsu:Created1841Thisrepresentsthecreationtimeofthesecuritysemantics.
Thiselementisoptional,but1842canonlybespecifiedonceinaelement.
WithintheSOAP1843processingmodel,creationistheinstantthattheinfosetisserializedfortransmission.
1844ThecreationtimeofthemessageSHOULDNOTdiffersubstantiallyfromitstransmission1845time.
Thedifferenceintimeshouldbeminimized.
18461847WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page52of76/wsu:Timestamp/wsu:Expires1848Thiselementrepresentstheexpirationofthesecuritysemantics.
Thisisoptional,but1849canappearatmostonceinaelement.
Uponexpiration,the1850requestorassertsthatitssecuritysemanticsarenolongervalid.
Itisstrongly1851RECOMMENDEDthatrecipients(anyonewhoprocessesthismessage)discard(ignore)1852anymessagewhosesecuritysemanticshavepassedtheirexpiration.
AFaultcode1853(wsu:MessageExpired)isprovidediftherecipientwantstoinformtherequestorthatits1854securitysemanticswereexpired.
AserviceMAYissueaFaultindicatingthesecurity1855semanticshaveexpired.
18561857/wsu:Timestamp/{any}1858Thisisanextensibilitymechanismtoallowadditionalelementstobeaddedtothe1859element.
UnrecognizedelementsSHOULDcauseafault.
18601861/wsu:Timestamp/@wsu:Id1862ThisoptionalattributespecifiesanXMLSchemaIDthatcanbeusedtoreferencethis1863element(thetimestamp).
Thisisused,forexample,toreferencethetimestampinaXML1864Signature.
18651866/wsu:Timestamp/@{any}1867Thisisanextensibilitymechanismtoallowadditionalattributestobeaddedtothe1868element.
UnrecognizedattributesSHOULDcauseafault.
18691870Theexpirationisrelativetotherequestor'sclock.
Inordertoevaluatetheexpirationtime,1871recipientsneedtorecognizethattherequestor'sclockmaynotbesynchronizedtotherecipient's1872clock.
Therecipient,therefore,MUSTmakeanassessmentoftheleveloftrusttobeplacedin1873therequestor'sclock,sincetherecipientiscalledupontoevaluatewhethertheexpirationtimeis1874inthepastrelativetotherequestor's,nottherecipient's,clock.
Therecipientmaymakea1875judgmentoftherequestor'slikelycurrentclocktimebymeansnotdescribedinthisspecification,1876forexampleanout-of-bandclocksynchronizationprotocol.
Therecipientmayalsousethe1877creationtimeandthedelaysintroducedbyintermediateSOAProlestoestimatethedegreeof1878clockskew.
18791880Thefollowingexampleillustratestheuseoftheelementanditscontent.
1881188218831884188518862001-09-13T08:42:00Z18872001-10-13T09:00:00Z18881889.
.
.
18901891.
.
.
189218931894.
.
.
18951896WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page53of761897WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page54of7611ExtendedExample1898Thefollowingsamplemessageillustratestheuseofsecuritytokens,signatures,andencryption.
1899Forthisexample,thetimestampandthemessagebodyaresignedpriortoencryption.
The1900decryptiontransformationisnotneededasthesigning/encryptionorderisspecifiedwithinthe1901header.
19021903(001)1904(002)1906(003)1907(004)1908(005)1909(006)1910(007)2001-09-13T08:42:00Z1911(008)1912(009)1913(010)1917(011)MIIEZzCCA9CgAwIBAgIQEmtJZc0rqrKh5i.
.
.
1918(012)1919(013)1920(014)1922(015)19231924(016)MIGfMa0GCSq.
.
.
1927(017)19281929(018)1930(019)1931(020)d2FpbmdvbGRfE0lm4byV0.
.
.
1932(021)1933(022)1934(023)1935(024)1936(025)1937(026)1938(027)1939(028)1940(029)1942(030)1944(031)1945(032)1946WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page55of76(033)1948(034)1949(035)1951(036)LyLsF094hPi4wPU.
.
.
1952(037)1953(038)1954(039)1955(040)1956(041)1958(042)1959(043)1961(044)LyLsF094hPi4wPU.
.
.
1962(045)1963(046)1964(047)1965(048)1966(049)Hp1ZkmFZ/2kQLXDJbchm5gK.
.
.
1967(050)1968(051)1969(052)1970(053)1971(054)1972(055)1973(056)1974(057)1975(058)1976(059)1977(060)1980(061)1983(062)1984(063)d2FpbmdvbGRfE0lm4byV0.
.
.
1985(064)1986(065)1987(066)1988(067)1989(068)19901991Let'sreviewsomeofthekeysectionsofthisexample:1992Lines(003)-(058)containtheSOAPmessageheaders.
19931994Lines(004)-(057)representtheheaderblock.
Thiscontainsthesecurity-1995relatedinformationforthemessage.
19961997Lines(005)-(008)specifythetimestampinformation.
Inthiscaseitindicatesthecreationtimeof1998thesecuritysemantics.
1999WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page56of762000Lines(010)-(012)specifyasecuritytokenthatisassociatedwiththemessage.
Inthiscase,it2001specifiesanX.
509certificatethatisencodedasBase64.
Line(011)specifiestheactualBase642002encodingofthecertificate.
20032004Lines(013)-(026)specifythekeythatisusedtoencryptthebodyofthemessage.
Sincethisisa2005symmetrickey,itispassedinanencryptedform.
Line(014)definesthealgorithmusedto2006encryptthekey.
Lines(015)-(018)specifytheidentifierofthekeythatwasusedtoencryptthe2007symmetrickey.
Lines(019)-(022)specifytheactualencryptedformofthesymmetrickey.
Lines2008(023)-(025)identifytheencryptionblockinthemessagethatusesthissymmetrickey.
Inthis2009caseitisonlyusedtoencryptthebody(Id="enc1").
20102011Lines(027)-(056)specifythedigitalsignature.
Inthisexample,thesignatureisbasedonthe2012X.
509certificate.
Lines(028)-(047)indicatewhatisbeingsigned.
Specifically,line(039)2013referencesthemessagebody.
20142015Lines(048)-(050)indicatetheactualsignaturevalue–specifiedinLine(043).
20162017Lines(052)-(054)indicatethekeythatwasusedforthesignature.
Inthiscase,itistheX.
5092018certificateincludedinthemessage.
Line(053)providesaURIlinktotheLines(010)-(012).
2019ThebodyofthemessageisrepresentedbyLines(059)-(067).
20202021Lines(060)-(066)representtheencryptedmetadataandformofthebodyusingXMLEncryption.
2022Line(060)indicatesthatthe"elementvalue"isbeingreplacedandidentifiesthisencryption.
Line2023(061)specifiestheencryptionalgorithm–Triple-DESinthiscase.
Lines(063)-(064)containthe2024actualciphertext(i.
e.
,theresultoftheencryption).
Notethatwedon'tincludeareferencetothe2025keyasthekeyreferencesthisencryption–Line(024).
20262027WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page57of7612ErrorHandling2028Therearemanycircumstanceswhereanerrorcanoccurwhileprocessingsecurityinformation.
2029Forexample:2030Invalidorunsupportedtypeofsecuritytoken,signing,orencryption2031Invalidorunauthenticatedorunauthenticatablesecuritytoken2032Invalidsignature2033Decryptionfailure2034Referencedsecuritytokenisunavailable2035Unsupportednamespace20362037IfaservicedoesnotperformitsnormaloperationbecauseofthecontentsoftheSecurityheader,2038thenthatMAYbereportedusingSOAP'sFaultMechanism.
Thisspecificationdoesnotmandate2039thatfaultsbereturnedasthiscouldbeusedaspartofadenialofserviceorcryptographic2040attack.
Wecombinesignatureandencryptionfailurestomitigatecertaintypesofattacks.
20412042IfafailureisreturnedtoaproducerthenthefailureMUSTbereportedusingtheSOAPFault2043mechanism.
Thefollowingtablesoutlinethepredefinedsecurityfaultcodes.
The"unsupported"2044classesoferrorsareasfollows.
NotethatthereasontextprovidedbelowisRECOMMENDED,2045butalternativetextMAYbeprovidedifmoredescriptiveorpreferredbytheimplementation.
The2046tablesbelowaredefinedintermsofSOAP1.
1.
ForSOAP1.
2,theFault/Code/Valueis2047env:Sender(asdefinedinSOAP1.
2)andtheFault/Code/Subcode/Valueisthefaultcodebelow2048andtheFault/Reason/Textisthefaultstringbelow.
20492050Errorthatoccurred(faultstring)faultcodeAnunsupportedtokenwasprovidedwsse:UnsupportedSecurityTokenAnunsupportedsignatureorencryptionalgorithmwasusedwsse:UnsupportedAlgorithm2051The"failure"classoferrorsare:20522053Errorthatoccurred(faultstring)faultcodeAnerrorwasdiscoveredprocessingtheheader.
wsse:InvalidSecurityAninvalidsecuritytokenwasprovidedwsse:InvalidSecurityTokenThesecuritytokencouldnotbeauthenticatedorauthorizedwsse:FailedAuthenticationWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page58of76Thesignatureordecryptionwasinvalidwsse:FailedCheckReferencedsecuritytokencouldnotberetrievedwsse:SecurityTokenUnavailableThemessagehasexpiredwsse:MessageExpiredWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page59of7613SecurityConsiderations20542055AsstatedintheGoalsandRequirementssectionofthisdocument,thisspecificationismeantto2056provideextensibleframeworkandflexiblesyntax,withwhichonecouldimplementvarious2057securitymechanisms.
Thisframeworkandsyntaxbyitselfdoesnotprovideanyguaranteeof2058security.
Whenimplementingandusingthisframeworkandsyntax,onemustmakeeveryeffortto2059ensurethattheresultisnotvulnerabletoanyoneofawiderangeofattacks.
2060206113.
1GeneralConsiderations20622063Itisnotfeasibletoprovideacomprehensivelistofsecurityconsiderationsforsuchanextensible2064setofmechanisms.
AcompletesecurityanalysisMUSTbeconductedonspecificsolutionsbased2065onthisspecification.
Belowweillustratesomeofthesecurityconcernsthatoftencomeupwith2066protocolsofthistype,butwestressthatthisisnotanexhaustivelistofconcerns.
2067freshnessguarantee(e.
g.
,thedangerofreplay,delayedmessagesandthedangerof2068relyingontimestampsassumingsecureclocksynchronization)2069properuseofdigitalsignatureandencryption(signing/encryptingcriticalpartsofthe2070message,interactionsbetweensignaturesandencryption),i.
e.
,signatureson(content2071of)encryptedmessagesleakinformationwheninplain-text)2072protectionofsecuritytokens(integrity)2073certificateverification(includingrevocationissues)2074thedangerofusingpasswordswithoutoutmostprotection(i.
e.
dictionaryattacksagainst2075passwords,replay,insecurityofpasswordderivedkeys,.
.
.
)2076theuseofrandomness(orstrongpseudo-randomness)2077interactionbetweenthesecuritymechanismsimplementingthisstandardandother2078systemcomponent2079man-in-the-middleattacks2080PKIattacks(i.
e.
identitymix-ups)20812082Thereareothersecurityconcernsthatonemayneedtoconsiderinsecurityprotocols.
Thelist2083aboveshouldnotbeusedasa"checklist"insteadofacomprehensivesecurityanalysis.
The2084nextsectionwillgiveafewdetailsonsomeoftheconsiderationsinthislist.
208513.
2AdditionalConsiderations208613.
2.
1Replay2087Digitalsignaturesalonedonotprovidemessageauthentication.
Onecanrecordasigned2088messageandresendit(areplayattack).
ItisstronglyRECOMMENDEDthatmessagesinclude2089digitallysignedelementstoallowmessagerecipientstodetectreplaysofthemessagewhenthe2090WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page60of76messagesareexchangedviaanopennetwork.
Thesecanbepartofthemessageorofthe2091headersdefinedfromotherSOAPextensions.
Fourtypicalapproachesare:Timestamp,2092SequenceNumber,ExpirationsandMessageCorrelation.
SignedtimestampsMAYbeusedto2093keeptrackofmessages(possiblybycachingthemostrecenttimestampfromaspecificservice)2094anddetectreplaysofpreviousmessages.
ItisRECOMMENDEDthattimestampsbecachedfor2095agivenperiodoftime,asaguideline,avalueoffiveminutescanbeusedasaminimumtodetect2096replays,andthattimestampsolderthanthatgivenperiodoftimesetberejectedininteractive2097scenarios.
209813.
2.
2CombiningSecurityMechanisms2099ThisspecificationdefinestheuseofXMLSignatureandXMLEncryptioninSOAPheaders.
As2100oneofthebuildingblocksforsecuringSOAPmessages,itisintendedtobeusedinconjunction2101withothersecuritytechniques.
Digitalsignaturesneedtobeunderstoodinthecontextofother2102securitymechanismsandpossiblethreatstoanentity.
21032104Implementersshouldalsobeawareofallthesecurityimplicationsresultingfromtheuseofdigital2105signaturesingeneralandXMLSignatureinparticular.
Whenbuildingtrustintoanapplication2106basedonadigitalsignaturethereareothertechnologies,suchascertificateevaluation,thatmust2107beincorporated,buttheseareoutsidethescopeofthisdocument.
21082109AsdescribedinXMLEncryption,thecombinationofsigningandencryptionoveracommondata2110itemmayintroducesomecryptographicvulnerability.
Forexample,encryptingdigitallysigned2111data,whileleavingthedigitalsignatureintheclear,mayallowplaintextguessingattacks.
211213.
2.
3Challenges2113Whendigitalsignaturesareusedforverifyingtheclaimspertainingtothesendingentity,the2114producermustdemonstrateknowledgeoftheconfirmationkey.
Onewaytoachievethisistouse2115achallenge-responsetypeofprotocol.
Suchaprotocolisoutsidethescopeofthisdocument.
2116Tothisend,thedeveloperscanattachtimestamps,expirations,andsequencestomessages.
211713.
2.
4ProtectingSecurityTokensandKeys2118Implementersshouldbeawareofthepossibilityofatokensubstitutionattack.
Inanysituation2119whereadigitalsignatureisverifiedbyreferencetoatokenprovidedinthemessage,which2120specifiesthekey,itmaybepossibleforanunscrupulousproducertolaterclaimthatadifferent2121token,containingthesamekey,butdifferentinformationwasintended.
2122AnexampleofthiswouldbeauserwhohadmultipleX.
509certificatesissuedrelatingtothe2123samekeypairbutwithdifferentattributes,constraintsorreliancelimits.
Notethatthesignatureof2124thetokenbyitsissuingauthoritydoesnotpreventthisattack.
Norcananauthorityeffectively2125preventadifferentauthorityfromissuingatokenoverthesamekeyiftheusercanprove2126possessionofthesecret.
21272128Themoststraightforwardcountertothisattackistoinsistthatthetoken(oritsuniqueidentifying2129data)beincludedunderthesignatureoftheproducer.
Ifthenatureoftheapplicationissuchthat2130thecontentsofthetokenareirrelevant,assumingithasbeenissuedbyatrustedauthority,this2131WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page61of76attackmaybeignored.
Howeverbecauseapplicationsemanticsmaychangeovertime,best2132practiceistopreventthisattack.
21332134Requestorsshouldusedigitalsignaturestosignsecuritytokensthatdonotincludesignatures(or2135otherprotectionmechanisms)toensurethattheyhavenotbeenalteredintransit.
Itisstrongly2136RECOMMENDEDthatallrelevantandimmutablemessagecontentbesignedbytheproducer.
2137ReceiversSHOULDonlyconsiderthoseportionsofthedocumentthatarecoveredbythe2138producer'ssignatureasbeingsubjecttothesecuritytokensinthemessage.
Securitytokens2139appearinginheaderelementsSHOULDbesignedbytheirissuingauthority2140sothatmessagereceiverscanhaveconfidencethatthesecuritytokenshavenotbeenforgedor2141alteredsincetheirissuance.
ItisstronglyRECOMMENDEDthatamessageproducersignany2142elementsthatitisconfirmingandthatarenotsignedbytheirissuing2143authority.
2144Whenarequesterprovides,withintherequest,aPublicKeytobeusedtoencrypttheresponse,2145itispossiblethatanattackerinthemiddlemaysubstituteadifferentPublicKey,thusallowingthe2146attackertoreadtheresponse.
Thebestwaytopreventthisattackistobindtheencryptionkeyin2147somewaytotherequest.
Onesimplewayofdoingthisistousethesamekeypairtosignthe2148requestastoencrypttheresponse.
However,ifpolicyrequirestheuseofdistinctkeypairsfor2149signingandencryption,thenthePublicKeyprovidedintherequestshouldbeincludedunderthe2150signatureoftherequest.
215113.
2.
5ProtectingTimestampsandIds2152Inordertotrustwsu:Idattributesandelements,theySHOULDbesigned2153usingthemechanismsoutlinedinthisspecification.
ThisallowsreadersoftheIDsand2154timestampsinformationtobecertainthattheIDsandtimestampshaven'tbeenforgedoraltered2155inanyway.
ItisstronglyRECOMMENDEDthatIDsandtimestampelementsbesigned.
2156215713.
2.
6ProtectingagainstremovalandmodificationofXMLElements2158XMLSignaturesusingShorthandXPointerReferences(AKAIDREF)protectagainsttheremoval2159andmodificationofXMLelements;butdonotprotectthelocationoftheelementwithintheXML2160Document.
21612162Whetherornotthisisasecurityvulnerabilitydependsonwhetherthelocationofthesigneddata2163withinitssurroundingcontexthasanysemanticimport.
Thisconsiderationappliestodatacarried2164intheSOAPBodyortheHeader.
21652166OfparticularconcernistheabilitytorelocatesigneddataintoaSOAPHeaderblockwhichis2167unknowntothereceiverandmarkedmustUnderstand="false".
Thiscouldhavetheeffectof2168causingthereceivertoignoresigneddatawhichthesenderexpectedwouldeitherbeprocessed2169orresultinthegenerationofaMustUnderstandfault.
21702171AsimilarexploitwouldinvolverelocatingsigneddataintoaSOAPHeaderblocktargetedtoa2172S11:actororS12:roleotherthanthatwhichthesenderintended,andwhichthereceiverwillnot2173process.
21742175WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page62of76Whiletheseattackscouldapplytoanyportionofthemessage,theireffectsaremostpernicious2176withSOAPheaderelementswhichmaynotalwaysbepresent,butmustbeprocessedwhenever2177theyappear.
21782179InthegeneralcaseofXMLDocumentsandSignatures,thisissuemayberesolvedbysigningthe2180entireXMLDocumentand/orstrictXMLSchemaspecificationandenforcement.
However,2181becauseelementsoftheSOAPmessage,particularlyheaderelements,maybelegitimately2182modifiedbySOAPintermediaries,thisapproachisusuallynotappropriate.
ItisRECOMMENDED2183thatapplicationssigninganypartoftheSOAPbodysigntheentirebody.
21842185Alternativescountermeasuresinclude(butarenotlimitedto):2186ReferencesusingXPathtransformswithAbsolutePathexpressionswithchecks2187performedbythereceiverthattheURIandAbsolutePathXPathexpressionevaluateto2188thedigestednodeset.
2189AReferenceusinganXPathtransformtoincludeanysignificantlocation-dependent2190elementsandexcludeanyelementsthatmightlegitimatelyberemoved,added,oraltered2191byintermediaries,2192UsingonlyReferencestoelementswithlocation-independentsemantics,2193Strictpolicyspecificationandenforcementregardingwhichmessagepartsaretobe2194signed.
Forexample:2195oRequiringthattheentireSOAPBodyandallchildrenofSOAPHeaderbesigned,2196oRequiringthatSOAPheaderelementswhicharemarked2197MustUnderstand="false"andhavesigneddescendantsMUSTincludethe2198MustUnderstandattributeunderthesignature.
2199220013.
2.
7DetectingDuplicateIdentifiers2201TheprocessingSHOULDcheckforduplicatevaluesfromamongthesetof2202IDattributesthatitisawareof.
Thewsse:SecurityprocessingMUSTgenerateafaultifa2203duplicateIDvalueisdetected.
22042205Thissectionisnon-normative.
2206WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page63of7614InteroperabilityNotes2207Basedoninteroperabilityexperienceswiththisandsimilarspecifications,thefollowinglist2208highlightsseveralcommonareaswhereinteroperabilityissueshavebeendiscovered.
Care2209shouldbetakenwhenimplementingtoavoidtheseissues.
Itshouldbenotedthatsomeofthese2210mayseem"obvious",buthavebeenproblematicduringtesting.
22112212KeyIdentifiers:Makesureyouunderstandthealgorithmandhowitisappliedtosecurity2213tokens.
2214EncryptedKey:TheelementfromXMLEncryptionrequiresa2215Typeattributewhosevalueisoneofapre-definedlistofvalues.
Ensurethatacorrect2216valueisused.
2217EncryptionPadding:TheXMLEncryptionrandomblockcipherpaddinghascaused2218issueswithcertaindecryptionimplementations;becarefultofollowthespecifications2219exactly.
2220IDs:ThespecificationrecognizesthreespecificIDelements:theglobalwsu:Idattribute2221andthelocalIDattributesonXMLSignatureandXMLEncryptionelements(because2222thelattertwodonotallowglobalattributes).
Ifanyotherelementdoesnotallowglobal2223attributes,itcannotbedirectlysignedusinganIDreference.
Notethattheglobal2224attributewsu:IdMUSTcarrythenamespacespecification.
2225TimeFormats:ThisspecificationusesarestrictedversionoftheXMLSchema2226xsd:dateTimeelement.
Takecaretoensurecompliancewiththespecifiedrestrictions.
2227ByteOrderMarker(BOM):SomeimplementationshaveproblemsprocessingtheBOM2228marker.
Itissuggestedthatusageofthisbeoptional.
2229SOAP,WSDL,HTTP:Variousinteroperabilityissueshavebeenseenwithincorrect2230SOAP,WSDL,andHTTPsemanticsbeingapplied.
Careshouldbetakentocarefully2231adheretothesespecificationsandanyinteroperabilityguidelinesthatareavailable.
22322233Thissectionisnon-normative.
2234WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page64of7615PrivacyConsiderations2235Inthecontextofthisspecification,weareonlyconcernedwithpotentialprivacyviolationbythe2236securityelementsdefinedhere.
Privacyofthecontentofthepayloadmessageisoutofscope.
2237Producersorsendingapplicationsshouldbeawarethatclaims,ascollectedinsecuritytokens,2238aretypicallypersonalinformation,andshouldthusonlybesentaccordingtotheproducer's2239privacypolicies.
Futurestandardsmayallowprivacyobligationsorrestrictionstobeaddedtothis2240data.
Unlesssuchstandardsareused,theproducermustensurebyout-of-bandmeansthatthe2241recipientisboundtoadheringtoallrestrictionsassociatedwiththedata,andtherecipientmust2242similarlyensurebyout-of-bandmeansthatithasthenecessaryconsentforitsintended2243processingofthedata.
22442245Ifclaimdataarevisibletointermediaries,thenthepoliciesmustalsoallowthereleasetothese2246intermediaries.
Asmostpersonalinformationcannotbereleasedtoarbitraryparties,thiswill2247typicallyrequirethattheactorsarereferencedinanidentifiableway;suchidentifiablereferences2248arealsotypicallyneededtoobtainappropriateencryptionkeysfortheintermediaries.
2249Ifintermediariesaddclaims,theyshouldbeguidedbytheirprivacypoliciesjustliketheoriginal2250producers.
22512252IntermediariesmayalsogaintrafficinformationfromaSOAPmessageexchange,e.
g.
,who2253communicateswithwhomatwhattime.
Producersthatuseintermediariesshouldverifythat2254releasingthistrafficinformationtothechosenintermediariesconformstotheirprivacypolicies.
22552256Thissectionisnon-normative.
2257WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page65of7616References2258[GLOSS]InformationalRFC2828,"InternetSecurityGlossary,"May2000.
2259[KERBEROS]J.
KohlandC.
Neuman,"TheKerberosNetworkAuthenticationService2260(V5),"RFC1510,September1993,http://www.
ietf.
org/rfc/rfc1510.
txt.
2261[KEYWORDS]S.
Bradner,"KeywordsforuseinRFCstoIndicateRequirementLevels,"2262RFC2119,HarvardUniversity,March1997.
2263[SHA-1]FIPSPUB180-1.
SecureHashStandard.
U.
S.
Departmentof2264Commerce/NationalInstituteofStandardsandTechnology.
2265http://csrc.
nist.
gov/publications/fips/fips180-1/fip180-1.
txt2266[SOAP11]W3CNote,"SOAP:SimpleObjectAccessProtocol1.
1,"08May2000.
2267[SOAP12]W3CRecommendation,"SOAPVersion1.
2Part1:Messaging2268Framework",23June2003.
2269[SOAPSEC]W3CNote,"SOAPSecurityExtensions:DigitalSignature,"06February22702001.
2271[URI]T.
Berners-Lee,R.
Fielding,L.
Masinter,"UniformResourceIdentifiers2272(URI):GenericSyntax,"RFC3986,MIT/LCS,DaySoftware,Adobe2273Systems,January2005.
2274[XPATH]W3CRecommendation,"XMLPathLanguage",16November199922752276Thefollowingarenon-normativereferencesincludedforbackgroundandrelatedmaterial:2277[WS-SECURITY]"WebServicesSecurityLanguage",IBM,Microsoft,VeriSign,April2002.
2278"WS-SecurityAddendum",IBM,Microsoft,VeriSign,August2002.
2279"WS-SecurityXMLTokens",IBM,Microsoft,VeriSign,August2002.
2280[XMLC14N]W3CRecommendation,"CanonicalXMLVersion1.
0,"15March2001.
2281[EXCC14N]W3CRecommendation,"ExclusiveXMLCanonicalizationVersion1.
0,"82282July2002.
2283[XMLENC]W3CWorkingDraft,"XMLEncryptionSyntaxandProcessing,"04March22842002.
2285W3CRecommendation,"DecryptionTransformforXMLSignature",10December2002.
2286[XML-ns]W3CRecommendation,"NamespacesinXML,"14January1999.
2287[XMLSCHEMA]W3CRecommendation,"XMLSchemaPart1:Structures,"2May2001.
2288W3CRecommendation,"XMLSchemaPart2:Datatypes,"2May2001.
2289[XMLSIG]D.
Eastlake,J.
R.
,D.
Solo,M.
Bartel,J.
Boyer,B.
Fox,E.
Simon.
XML-2290SignatureSyntaxandProcessing,W3CRecommendation,12February22912002.
2292WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page66of76[X509]S.
Santesson,etal,"InternetX.
509PublicKeyInfrastructureQualified2293CertificatesProfile,"2294http://www.
itu.
int/rec/recommendation.
asptype=items&lang=e&parent=2295T-REC-X.
509-200003-I2296[WSS-SAML]OASISWorkingDraft06,"WebServicesSecuritySAMLTokenProfile",229721February20032298[WSS-XrML]OASISWorkingDraft03,"WebServicesSecurityXrMLTokenProfile",229930January20032300[WSS-X509]OASIS,"WebServicesSecurityX.
509CertificateTokenProfile",192301January2004,http://www.
docs.
oasis-open.
org/wss/2004/01/oasis-2302200401-wss-x509-token-profile-1.
02303[WSSKERBEROS]OASISWorkingDraft03,"WebServicesSecurityKerberosProfile",302304January20032305[WSSUSERNAME]OASIS,"WebServicesSecurityUsernameTokenProfile"19January23062004,http://www.
docs.
oasis-open.
org/wss/2004/01/oasis-200401-wss-2307username-token-profile-1.
02308[WSS-XCBF]OASISWorkingDraft1.
1,"WebServicesSecurityXCBFTokenProfile",230930March20032310[XMLID]W3CRecommmendation,"xml:idVersion1.
0",9September2005.
2311[XPOINTER]"XMLPointerLanguage(XPointer)Version1.
0,Candidate2312Recommendation",DeRose,Maler,Daniel,11September2001.
2313WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page67of76AppendixA:Acknowledgements2314CurrentContributors:2315MichaelHuActionalManeeshSahuActionalDuaneNickullAdobeSystemsGeneThurstonAmberPointFrankSiebenlistArgonneNationalLaboratoryHalLockhartBEASystemsDenisPilipchukBEASystemsCorinnaWittBEASystemsSteveAndersonBMCSoftwareRichLevinsonComputerAssociatesThomasDeMartiniContentGuardMerlinHughesCybertrustDaleMobergCycloneCommerceRichSalzDatapowerSamWeiEMCDanaS.
KaufmanForumSystemsToshihiroNishimuraFujitsuKefengChenGeoTrustIrvingReidHewlett-PackardKojiroNakayamaHitachiPaulaAustelIBMDerekFuIBMMaryannHondoIBMKelvinLawrenceIBMMichaelMcIntoshIBMAnthonyNadalinIBMNatarajNagaratnamIBMBruceRichIBMRonWilliamsIBMDonFlinnIndividualKateCherryLockheedMartinPaulCottonMicrosoftVijayGajjalaMicrosoftMartinGudginMicrosoftChrisKalerMicrosoftFrederickHirschNokiaAbbieBarbirNortelPrateekMishraOracleVamsiMotukuruOracleRamanaTurlapiOracleBenHammondRSASecurityWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page68of76RobPhilpottRSASecurityBlakeDournaeeSarvegaSundeepPeechuSarvegaCoumaraRadjaSarvegaPeteWenzelSeeBeyondManveenKaurSunMicrosystemsRonaldMonzilloSunMicrosystemsJanAlexanderSystinetSymonChangTIBCOSoftwareJohnWeilandUSNavyHansGranqvistVeriSignPhillipHallam-BakerVeriSignHemmaPrafullchandraVeriSignPreviousContributors:2316PeteDapkusBEAGuillermoLaoContentGuardTJPannuContentGuardXinWangContentGuardShawnSharpCycloneCommerceGaneshVaideeswaranDocumentumTimMosesEntrustCarolinaCanales-ValenzuelaEricssonTomRuttFujitsuYutakaKudoHitachiJasonRouaultHPBobBlakleyIBMJoelFarrellIBMSatoshiHadaIBMHiroshiMaruyamaIBMDavidMelgarIBMKentTamuraIBMWayneVicknairIBMPhilGriffinIndividualMarkHayesIndividualJohnHughesIndividualPeterRostinIndividualDavanumSrinivasIndividualBobMorganIndividual/InternetBobAtkinsonMicrosofKeithBallingerMicrosoftAllenBrownMicrosoftGiovanniDella-LiberaMicrosoftAlanGellerMicrosoftJohannesKleinMicrosoftWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page69of76ScottKonersmannMicrosoftChrisKurtMicrosoftBrianLaMacchiaMicrosoftPaulLeachMicrosoftJohnManferdelliMicrosoftJohnShewchukMicrosoftDanSimonMicrosoftHerveyWilsonMicrosoftJeffHodgesNeustarSenthilSengodanNokiaLloydBurchNovellEdReedNovellCharlesKnouseOblixVipinSamarOracleJerrySchwarzOracleEricGravengaardReactivityAndrewNashReactivityStuartKingReedElsevierMartijndeBoerSAPJonathanTourzanSonyYassirElleySunMichaelNguyenTheIDAofSingaporeDonAdamsTIBCOMortenJorgensenVordel2317WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page70of76AppendixB:RevisionHistory2318RevDateByWhomWhat2319Thissectionisnon-normative.
2320WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page71of76AppendixC:UtilityElementsandAttributes2321Thesespecificationsdefineseveralelements,attributes,andattributegroupswhichcanbere-2322usedbyotherspecifications.
Thisappendixprovidesanoverviewoftheseutilitycomponents.
It2323shouldbenotedthatthedetaileddescriptionsareprovidedinthespecificationandthisappendix2324willreferencethesesectionsaswellascallingoutotheraspectsnotdocumentedinthe2325specification.
232616.
1IdentificationAttribute2327TherearemanysituationswhereelementswithinSOAPmessagesneedtobereferenced.
For2328example,whensigningaSOAPmessage,selectedelementsareincludedinthesignature.
XML2329SchemaPart2providesseveralbuilt-indatatypesthatmaybeusedforidentifyingand2330referencingelements,buttheiruserequiresthatconsumersoftheSOAPmessageeitherhaveor2331areabletoobtaintheschemaswheretheidentityorreferencemechanismsaredefined.
Insome2332circumstances,forexample,intermediaries,thiscanbeproblematicandnotdesirable.
23332334Consequentlyamechanismisrequiredforidentifyingandreferencingelements,basedonthe2335SOAPfoundation,whichdoesnotrelyuponcompleteschemaknowledgeofthecontextinwhich2336anelementisused.
ThisfunctionalitycanbeintegratedintoSOAPprocessorssothatelements2337canbeidentifiedandreferredtowithoutdynamicschemadiscoveryandprocessing.
23382339Thisspecificationspecifiesanamespace-qualifiedglobalattributeforidentifyinganelement2340whichcanbeappliedtoanyelementthateitherallowsarbitraryattributesorspecificallyallows2341thisattribute.
Thisisageneralpurposemechanismwhichcanbere-usedasneeded.
2342AdetaileddescriptioncanbefoundinSection4.
0IDReferences.
23432344Thissectionisnon-normative.
234516.
2TimestampElements2346ThespecificationdefinesXMLelementswhichmaybeusedtoexpresstimestampinformation2347suchascreationandexpiration.
Whiledefinedinthecontextofmessagesecurity,these2348elementscanbere-usedwhereverthesesortsoftimestatementsneedtobemade.
23492350Theelementsinthisspecificationaredefinedandillustratedusingtimereferencesintermsofthe2351dateTimetypedefinedinXMLSchema.
ItisRECOMMENDEDthatalltimereferencesusethis2352typeforinteroperability.
ItisfurtherRECOMMENDEDthatallreferencesbeinUTCtimefor2353increasedinteroperability.
If,however,othertimetypesareused,thentheValueTypeattribute2354MUSTbespecifiedtoindicatethedatatypeofthetimeformat.
2355Thefollowingtableprovidesanoverviewoftheseelements:23562357ElementDescriptionThiselementisusedtoindicatethecreationtimeassociatedwiththeenclosingcontext.
WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page72of76Thiselementisusedtoindicatetheexpirationtimeassociatedwiththeenclosingcontext.
2358AdetaileddescriptioncanbefoundinSection10.
23592360Thissectionisnon-normative.
2361236216.
3GeneralSchemaTypes2363Theschemafortheutilityaspectsofthisspecificationalsodefinessomegeneralpurpose2364schemaelements.
Whiletheseelementsaredefinedinthisschemaforusewiththis2365specification,theyaregeneralpurposedefinitionsthatmaybeusedbyotherspecificationsas2366well.
23672368Specifically,thefollowingschemaelementsaredefinedandcanbere-used:23692370SchemaElementDescriptionwsu:commonAttsattributegroupThisattributegroupdefinesthecommonattributesrecommendedforelements.
Thisincludesthewsu:Idattributeaswellasextensibilityforothernamespacequalifiedattributes.
wsu:AttributedDateTimetypeThistypeextendstheXMLSchemadateTimetypetoincludethecommonattributes.
wsu:AttributedURItypeThistypeextendstheXMLSchemaanyURItypetoincludethecommonattributes.
2371Thissectionisnon-normative.
23722373WSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page73of76AppendixD:SecurityTokenReferenceModel2374Thisappendixprovidesanon-normativeoverviewoftheusageandprocessingmodelsforthe2375element.
23762377Thereareseveralmotivationsforintroducingthe2378element:2379TheXMLSignaturereferencemechanismsarefocusedon"key"referencesratherthan2380generaltokenreferences.
2381TheXMLSignaturereferencemechanismsutilizeafairlyclosedschemawhichlimitsthe2382extensibilitythatcanbeapplied.
2383Thereareadditionaltypesofgeneralreferencemechanismsthatareneeded,butarenot2384coveredbyXMLSignature.
2385TherearescenarioswhereareferencemayoccuroutsideofanXMLSignatureandthe2386XMLSignatureschemaisnotappropriateordesired.
2387TheXMLSignaturereferencesmayincludeaspects(e.
g.
transforms)thatmaynotapply2388toallreferences.
23892390Thefollowingusecasesdrivetheabovemotivations:23912392LocalReference–Asecuritytoken,thatisincludedinthemessageinthe2393header,isassociatedwithanXMLSignature.
Thefigurebelowillustratesthis:23942395SecurityTokenSignatureReferenceWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page74of762396RemoteReference–Asecuritytoken,thatisnotincludedinthemessagebutmaybeavailable2397ataspecificURI,isassociatedwithanXMLSignature.
Thefigurebelowillustratesthis:239823992400KeyIdentifier–Asecuritytoken,whichisassociatedwithanXMLSignatureandidentifiedusing2401aknownvaluethatistheresultofawell-knownfunctionofthesecuritytoken(definedbythe2402tokenformatorprofile).
Thefigurebelowillustratesthiswherethetokenislocatedexternally:24032404KeyName–AsecuritytokenisassociatedwithanXMLSignatureandidentifiedusingaknown2405valuethatrepresentsa"name"assertionwithinthesecuritytoken(definedbythetokenformator2406profile).
Thefigurebelowillustratesthiswherethetokenislocatedexternally:24072408Format-SpecificReferences–AsecuritytokenisassociatedwithanXMLSignatureand2409identifiedusingamechanismspecifictothetoken(ratherthanthegeneralmechanisms2410SecurityTokenK-I(ST)SignatureKeyIdentifierSecurityTokenSignatureReferenceSecurityTokenName:XXXSignatureKeyNameWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page75of76describedabove).
Thefigurebelowillustratesthis:24112412Non-SignatureReferences–AmessagemaycontainXMLthatdoesnotrepresentanXML2413signature,butmayreferenceasecuritytoken(whichmayormaynotbeincludedinthe2414message).
Thefigurebelowillustratesthis:241524162417Allconformantimplementationsmustbeabletoprocessthe2418element.
However,theyarenotrequiredtosupportallof2419thedifferenttypesofreferences.
24202421Thereferencemayincludeawsse11:TokenTypeattributewhichprovidesa"hint"forthetypeof2422desiredtoken.
24232424Ifmultiplesub-elementsarespecified,togethertheydescribethereferenceforthetoken.
2425Thereareseveralchallengesthatimplementationsfacewhentryingtointeroperate:2426IDReferences–TheunderlyingXMLreferencingmechanismusingtheXMLbasetypeofID2427providesasimplestraightforwardXMLelementreference.
However,becausethisisanXML2428type,itcanbeboundtoanyattribute.
ConsequentlyinordertoprocesstheIDsandreferences2429requirestherecipienttounderstandtheschema.
Thismaybeanexpensivetaskandinthe2430generalcaseimpossibleasthereisnowaytoknowthe"schemalocation"foraspecific2431namespaceURI.
24322433SecurityTokenMyStuffReferenceMyTokenSecurityTokenSignatureMyRefWSS:SOAPMessageSecurity(WS-Security2004)1February2006CopyrightOASISOpen2002-2006.
AllRightsReserved.
Page76of76Ambiguity–Theprimarygoalofareferenceistouniquelyidentifythedesiredtoken.
ID2434referencesare,bydefinition,uniquebyXML.
However,othermechanismssuchas"principal2435name"arenotrequiredtobeuniqueandthereforesuchreferencesmaybeunique.
2436TheXMLSignaturespecificationdefinesaelementwhichisusedtoprovide2437informationaboutthe"key"usedinthesignature.
Fortokenreferenceswithinsignatures,itis2438recommendedthatthebeplacedwithinthe2439.
TheXMLSignaturespecificationalsodefinesmechanismsforreferencingkeys2440byidentifierorpassingspecifickeys.
Asarule,thespecificmechanismsdefinedinWSS:SOAP2441MessageSecurityoritsprofilesarepreferredoverthemechanismsinXMLSignature.
2442ThefollowingprovidesadditionaldetailsonthespecificreferencemechanismsdefinedinWSS:2443SOAPMessageSecurity:24442445DirectReferences–TheelementisusedtoprovideaURIreferenceto2446thesecuritytoken.
Ifonlythefragmentisspecified,thenitreferencesthesecuritytokenwithin2447thedocumentwhosewsu:Idmatchesthefragment.
Fornon-fragmentURIs,thereferenceisto2448a[potentiallyexternal]securitytokenidentifiedusingaURI.
Therearenoimpliedsemantics2449aroundtheprocessingoftheURI.
24502451KeyIdentifiers–Theelementisusedtoreferenceasecuritytoken2452byspecifyingaknownvalue(identifier)forthetoken,whichisdeterminedbyapplyingaspecial2453functiontothesecuritytoken(e.
g.
ahashofkeyfields).
Thisapproachistypicallyuniqueforthe2454specificsecuritytokenbutrequiresaprofileortoken-specificfunctiontobespecified.
The2455ValueTypeattributedefinesthetypeofkeyidentifierand,consequently,identifiesthetypeof2456tokenreferenced.
TheEncodingTypeattributespecifieshowtheuniquevalue(identifier)is2457encoded.
Forexample,ahashvaluemaybeencodedusingbase64encoding.
24582459KeyNames–Theelementisusedtoreferenceasecuritytokenbyspecifyinga2460specificvaluethatisusedtomatchanidentityassertionwithinthesecuritytoken.
Thisisa2461subsetmatchandmayresultinmultiplesecuritytokensthatmatchthespecifiedname.
While2462XMLSignaturedoesn'timplyformattingsemantics,WSS:SOAPMessageSecurityrecommends2463thatX.
509namesbespecified.
24642465Itisexpectedthat,whereappropriate,profilesdefineifandhowthereferencemechanismsmap2466tothespecifictokenprofile.
Specifically,theprofileshouldanswerthefollowingquestions:24672468Whattypesofreferencescanbeused2469How"KeyName"referencesmap(ifatall)2470How"KeyIdentifier"referencesmap(ifatall)2471Arethereanyadditionalprofileorformat-specificreferences24722473Thissectionisnon-normative.
2474