SOA Securityopensource.corisecio.com/.../ReferenceGuide_SOASecurity.pdf · 2013. 4. 18. · The...

SOA Security

CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.de - Copyright 2009 - All Rights Reserved

SOA Security

© CORISECIO

1. Adapter requirements ............................................................................................................................. 11. securityRunTime (secRT) & managementRunTime .............................................................................. 1

1.1. securityRunTime (secRT) ..................................................................................................... 12. Functional overview ............................................................................................................................... 2

1. Data types ................................................................................................................................... 21.1. crs:multiLineString ............................................................................................................... 21.2. crs:xpath ........................................................................................................................... 21.3. crs:certificate ...................................................................................................................... 21.4. crs:privateKey .................................................................................................................... 21.5. crs:role ............................................................................................................................. 2

2. Functions ..................................................................................................................................... 22.1. SAMLAddUserAuth (SAML 1.X) ............................................................................................. 22.2. SAMLAddUserAuth (SAML 2.0) ............................................................................................. 22.3. SAMLCheckUserAuth (SAML 1.1) .......................................................................................... 32.4. SAMLCheckUserAuth (SAML 2.0) .......................................................................................... 32.5. decryptXPath ..................................................................................................................... 42.6. encryptXPath ..................................................................................................................... 42.7. encryptXPathForCertificate .................................................................................................... 42.8. RemoveSignatureHeader ...................................................................................................... 42.9. SignSOAPEnvelope ............................................................................................................. 52.10. SignSOAPEnvelopeWithXPath ............................................................................................. 52.11. VerifySOAPEnvelope ......................................................................................................... 52.12. AddSOAPMessage ............................................................................................................ 62.13. VerifySOAPEnvelopeWithXKMS ........................................................................................... 62.14. WSSecurityAddTimestamp .................................................................................................. 62.15. WSSecurityAddSAMLToken (SAML 1.1) ................................................................................ 72.16. WSSecurityCheckSAMLToken (SAML 1.1) ............................................................................. 72.17. WSSecurityCheckTimestamp ............................................................................................... 82.18. WSSecurityDecrypt ............................................................................................................ 82.19. WSSecurityEncryptXPathWithXKMS ..................................................................................... 82.20. WSSecurityEncryptForCertificate .......................................................................................... 92.21. WSSecurityRemoveHeader ................................................................................................. 92.22. WSSecuritySignXPath ........................................................................................................ 92.23. WSSecurityVerify ............................................................................................................. 10

Index .................................................................................................................................................... 11

© CORISECIO 1

Chapter 1. Adapter requirements

1. securityRunTime (secRT) & managementRunTime

1.1. securityRunTime (secRT)The SOA Security adapter requires secRT-SSF 1.1

© CORISECIO 2

Chapter 2. Functional overview

1. Data types

1.1. crs:multiLineStringA crs:multiLineString represents a multi-line string.

1.2. crs:xpathA crs:xpath represents an XPath expression. Supported is XPath Version 1.0 (based on Xalan 2.7.0).Please note, that XPath is namespace-aware and use //*[local-name()='CityName' and names-pace-uri()='www.webserviceX.NET'] expression to operate on nodes wtih namespace specified.

1.3. crs:certificateA crs:certificate represents an Base-64 encoded X.509 (.CER) certificate.

1.4. crs:privateKeyA crs:privateKey represents an private key container (supported are .p12 and .jks) with RSA (max. key length 1024) key.

1.5. crs:roleA crs:role represents a created role, which may be assigned to none, one or many users.

2. Functions

2.1. SAMLAddUserAuth (SAML 1.X)The function SAMLAddUserAuth (SAML 1.X) adds a SAML 1.1 Assertion to the SOAP message header. The Assertionmay contain a signature.

The function SAMLAddUserAuth (SAML 1.X) contains the following configuration parameter:

Parameter Type Required Description

User name xsd:string no The subject's user name. If this parameter is not given, the content ofthe execution variable username is used.

Authenti-cationmethod

xsd:string no The authentication method used to authenticate the subject. Ifthis parameter is not given, the content of the execution variablesaml.AuthnContextClassRef is used.

Issuer xsd:string yes The issuer's name.

Privatekey

crs:privateKey no The private key for signing the assertion.

Certifi-cate

crs:certificate no The certificate for signing the assertion.

For SOAPMessage the function contains the following signature:

Result name Result Typ Type Description

message ok SOAPMessage The Assertion was successfully added to the SOAP Header.

error error SOAPMessage An Error occurred during the process.

2.2. SAMLAddUserAuth (SAML 2.0)The function SAMLAddUserAuth (SAML 2.0) adds a SAML 2.0 Assertion to the SOAP Header. The Assertion maycontain a signature.

The function SAMLAddUserAuth (SAML 2.0) contains the following configuration parameter:


User name xsd:string no The subject's username. If this parameter is not given, the content ofexecution variable username is used.

© CORISECIO 3





Privatekey

crs:privateKey no The private key for signing the assertion.

Certifi-cate

crs:certificate no The certificate for signing the assertion.

The function contains the following signature

Result Name Result Type Type Description

message ok SOAPMessage The Assertion was successfully added to the SOAP Header.


2.3. SAMLCheckUserAuth (SAML 1.1)The function SAMLCheckUserAuth (SAML 1.1)verifies a SAML 1.1 Assertion in the Header of a SOAP Message. AnAssertion is valid, if the specified validity period has not expired and if the subject is a known entity. If the assertion containsa signature, it must be signed by a known entity.

The function sets the Subject in the execution variable username and the authentication method of the SAML Assertion inthe execution variable saml.AuthnContextClassRef .

The fuction SAMLCheckUserAuth (SAML 1.1) contains no configuration parameter.

The function contains for SOAPMessage the following signature:

Result name Result Type Type Description

verified ok SOAPMessage The assertion was successfully verified.

invalid error SOAPMessage The specified validity period expired or the subject is un-known.

noAssertion error SOAPMessage The SOAP Header does not contain a SAML Assertion.

error error SOAPMessage An error occurred during the process.

2.4. SAMLCheckUserAuth (SAML 2.0)The function SAMLCheckUserAuth (SAML 2.0) verifies a SAML 2.0 Assertion in the Header of a SOAP Message. AnAssertion is valid, if the specified validity period has not expired and if the subject is a known entity. If the assertion containsa signature, it must be signed by a known entity.

The function sets the Subject in the execution variable username and the authentication method of the SAML Assertion inthe execution variable saml.AuthnContextClassRef.

The function SAMLCheckUserAuth (SAML 2.0) contains no configuration parameter.



verified ok SOAPMessage The assertion was successfully verified.

invalid error SOAPMessage The specified validity period expired or the subject is un-known.

noAssertion error SOAPMessage The SOAP Header does not contain a SAML Assertion.


© CORISECIO 4

2.5. decryptXPathThe function decryptXPath decrypts an encrypted XML-Element on the specified X-Path location. It uses the private keyof the securityRunTime.

The function decryptXPath contains the following parameter:


XPath crs:xpath yes The specified X-Path location.

The functions contains for SOAPMessage the following signature:

Result name Type Description

decrypted SOAPMessage The decryption was successful.

error SOAPMessage An error occurred during the process.

2.6. encryptXPathThe function encryptXPath encrypts a SOAPMessage on a specified X-Path location with the public key defined in theexecution variable username. The value of the execution variable may be set using e.g. SetExecVariable

The function encryptXPath contains the following configuration parameter:


xpath crs:xpath yes The specified X-Path location.



encrypted SOAPMessage The encrytion was successful.


2.7. encryptXPathForCertificateThe function encryptXPathForCertificate encrypts a SOAPMessage on a specified X-Path location using the specifiedcertificate (which must be a Base-64 encoded X.509 (.CER)).

The function encryptXPathForCertificate contains the following configuration parameter:


xpath crs:xpath yes The specified X-Path location.

Encryptioncertifi-cate

crs:certificate yes The certificate which will be used for the encryption.



encrypted SOAPMessage The encryption was successful.


2.8. RemoveSignatureHeaderThe function RemoveSignatureHeader removes a signature header that was created with SignSOAPEnvelope or Sign-SOAPEnvelopeWithXPath.

The function RemoveSignatureHeader contains the following configuration parameter.


Actor/Role xsd:string no SOAP 1.2 role or SOAP 1.1 actor

© CORISECIO 5



ok ok SOAPMessage The header was removed.


2.9. SignSOAPEnvelopeThe function SignSOAPEnvelope signs the body of a SOAP Message with the key of the server entity. The XML-Signatureis created in the header of the SOAP Message.

The function SignSOAPEnvelope contains the following configuration parameter.



NotePlease note that the function ignores SOAP Attachments.



signed ok SOAPMessage The message was signed.


2.10. SignSOAPEnvelopeWithXPathThe function SignSOAPEnvelopeWithXPath signs of a SOAP Message with the key of the server entity. The XML-Sig-nature is created in the header of the SOAP Message.

The function SignSOAPEnvelopeWithXPath contains the following configuration parameters.



XPath crs:xpath yes this parameter references the elements which should be signed; to workproperly the given XPath should reference one ore more elements of theSOAP Message body

BaseRefURI xsd:string no URI for referencing the signed parts. This is only used if the elements do notcontain an id attribute

NotePlease note that the function ignores SOAP Attachments.

The functions contains for SOAPMessage the following signature:


signed ok SOAPMessage The message was signed.


2.11. VerifySOAPEnvelopeThe function VerifySOAPEnvelope verifies the signature of a SOAP Message. The signature must be in XML Signatureformat in the header of the SOAP Message. For the verification of the Signature a certificate is retrieved from the certificatestore which is named after the value of the execution variable username. If the username variable ist not set, the KeyInfoelement of the signature is used to verify the message. The found key information must belong to a known entity.

The function VerifySOAPEnvelope contains the following parrameter.

© CORISECIO 6





valid ok SOAPMessage The verification of the signature was successful. The Mes-sage was not modified and it was signed with a private keywhich associated with an available certificate in the store.

invalid error SOAPMessage The verification of the signature failed. Possible causes are amissing signature element, a missing certificate or the mes-sage was modified.


2.12. AddSOAPMessageThe function AddSOAPMessage creates a SOAPMessage (SOAP 1.1 or 1.2) from given string. The content of the SOAPMessage must be configured without Body-Element.

The function AddSOAPMessage contains the following configuration parameter:


MessageType

xsd:string yes XML string (SOAP 1.1 or SOAP 1.2)

Page con-tent

crs:multiLineString yes XML string, payload of SOAPMessage



message ok SOAPMessage SOAPMessage created from provided XML string.

2.13. VerifySOAPEnvelopeWithXKMSThe function VerifySOAPEnvelopeWithXKMS verifies a SOAPMessage for a given certificate using the specified XKMSservice.

The function VerifySOAPEnvelopeWithXKMS contains the following configuration parameters:



xkms xsd:string yes URL of XKMS service.



valid ok SOAPMessage Signature was found valid.

invalid error SOAPMessage Signature was found invalid.

invalidCer-tificate

error SOAPMessage XKMS service could not validate the certificate provided inSOAPMessage.


2.14. WSSecurityAddTimestampThe function WSSecurityAddTimestamp adds an timestamp element to the WS Security header. The timestamp is notsigned.

© CORISECIO 7

The function WSSecurityAddTimestamp contains the following configuration parameter:


Actor/Role xsd:string yes Defines the actor for the security header.

Time to live inseconds

xsd:int yes The time the token is valid.



ok ok SOAPMessage The timestamp token was created successfully.


2.15. WSSecurityAddSAMLToken (SAML 1.1)The function WSSecurityAddSAMLToken (SAML 1.1) adds a signed SAML 1.1 Assertion to the WS Security header.

The subject confirmation method is holder-of-key. The assertion must be signed.

The function WSSecurityAddSAMLToken (SAML 1.1) contains the following configuration parameter:



User name xsd:string no The subject's user name. If this parameter is not given, the content ofthe execution variable username is used.




Key crs:privateKey no The private key for signing the assertion. The corresponding certificateis added to the message.



ok ok SOAPMessage The Assertion was successfully added to the SOAP Header.


2.16. WSSecurityCheckSAMLToken (SAML 1.1)The function WSSecurityCheckSAMLToken (SAML 1.1)verifies a SAML 1.1 Assertion in the WS Security Header ofa SOAP Message.

The function sets the Subject in the execution variable username and the authentication method of the SAML Assertion inthe execution variable saml.AuthnContextClassRef .

The function WSSecurityCheckSAMLToken (SAML 1.1) contains the following configuration parameter:


Actor/Role xsd:string yes Defines the recipient actor for the security header.



verified ok SOAPMessage The assertion was verified successfully.

invalid error SOAPMessage The assertion can not be verified.

© CORISECIO 8


noAssertion error SOAPMessage No assertion was found for the given actor.


2.17. WSSecurityCheckTimestampThe function WSSecurityCheckTimestamp checks if the timestamp of the WS Security header is valid.

The function WSSecurityCheckTimestamp contains the following configuration parameter:





valid ok SOAPMessage The timestamp is valid.

invalid error SOAPMessage The timestamp is invalid.

error error SOAPMessage An error occurred during the process. For example a times-tamp was missing for the given actor.

2.18. WSSecurityDecryptThe function WSSecurityDecrypt decrypts XML-Element(s) on the location(s), which are referenced via a Refer-enceList-Element (namespace "http://www.w3.org/2001/04/xmlenc#").

The function WSSecurityDecrypt contains the following parameter:





decrypted ok SOAPMessage The message was decrypted successfully.


2.19. WSSecurityEncryptXPathWithXKMSThe function WSSecurityEncryptXPathWithXKMS encrypts a SOAPMessage for a given certificate on a specified X-Pathlocation. The certificate is retrieved by the configured XKMS Service.

NoteIf the X-Path location references multiple element, only the first found element is encrypted.

The function WSSecurityEncryptXPathForHostname contains the following configuration parameter:



User xsd:string yes The User whose certificate should be used to encrypt the message

XKMS URL xsd:string yes URL of XKMS service.

XPath crs:xpath yes The specified XPath location (default value references the SOAP body).

Requesttype

requestType yes Validate/Locate to trigger the validation of certificate.


© CORISECIO 9


encrypted ok SOAPMessage The encryption was successful.

noCertificate error SOAPMessage Requested certificate was not provided by XKMS service.

xkmsError error SOAPMessage An error occurred while contacting the XKMS service.


2.20. WSSecurityEncryptForCertificateThe function WSSecurityEncryptForCertificate encrypts a SOAPMessage on a specified X-Path location with thepublic key defined in the given certificate.

NoteIf the X-Path location references multiple element, only the first found element is encrypted.

The function WSSecurityEncryptForCertificate contains the following configuration parameter:



Encryptioncertificate

crs:certificate yes The certificate with the public key for the receiver.

xpath crs:xpath yes The specified X-Path location (default value references the SOAP body).



encrypted ok SOAPMessage The encryption was successful.


2.21. WSSecurityRemoveHeaderThe function WSSecurityRemoveHeader (SAML 1.1) removes the WS Security header with the configured actor fromthe message.

The function WSSecurityRemoveHeader (SAML 1.1) contains the following configuration parameter:





message ok SOAPMessage The Header was successfully removed.


2.22. WSSecuritySignXPathThe function WSSecuritySignXPath signs aSOAP Message with the key of the server entity. The XML-Signature iscreated in the header of the SOAP Message.

NoteIf the X-Path location references multiple element, only the first found element is signed.

The function WSSecuritySignXPath contains the following configuration parameter:



© CORISECIO 10


xpath crs:xpath yes The specified X-Path location (default value references the SOAP body).



signed ok SOAPMessage The signature was successfully applied.


2.23. WSSecurityVerifyThe function WSSecurityVerify verifies the signature of a SOAP Message. The signature must be WS Security compat-ible in the header of the SOAP Message. For the verification of the Signature a certificate is retrieved from the certificatestore which is named after the value of the execution variable username. If the username variable ist not set, the KeyInfoelement of the signature is used to verify the message. The found key information must belong to a known entity.

The function WSSecurityVerify contains the following configuration parameter:





valid ok SOAPMessage The verification of the signature was successful. The Mes-sage was not modified and it was signed with a private keywhich associated with an available certificate in the store.

invalid error SOAPMessage The verification of the signature failed. Possible causes are amissing signature element, a missing certificate or the mes-sage was modified.


© CORISECIO

Indexsaml.AuthnContextClassRef, 3

AAddSOAPMessage, 6Assertion, 2, 2, 3, 3, 7, 7

Ccrs:certificate, 2crs:multiLineString, 2crs:privateKey, 2crs:role, 2crs:xpath, 2

DdecryptXPath, 4

EencryptXPath, 4encryptXPathForCertificate, 4execution variable

saml.AuthnContextClassRef, 3, 7username, 3, 3, 5, 7, 10

RRemoveSignatureHeader, 4

SSAML, 2, 2, 3, 3, 7, 7SAMLAddUserAuth (SAML 1.X), 2SAMLAddUserAuth (SAML 2.0), 2SAMLCheckUserAuth (SAML 1.1), 3SAMLCheckUserAuth (SAML 2.0), 3signature, 2, 2Signature, 5, 10SignSOAPEnvelope, 5SignSOAPEnvelopeWithXPath, 5

VVerifySOAPEnvelope, 5VerifySOAPEnvelopeWithXKMS, 6

WWSSecurityAddSAMLToken (SAML 1.1), 7WSSecurityAddTimestamp, 6WSSecurityCheckSAMLToken (SAML 1.1), 7WSSecurityCheckTimestamp, 8WSSecurityDecrypt, 8WSSecurityEncryptForCertificate, 9WSSecurityEncryptXPathWithXKMS, 8WSSecurityRemoveHeader, 9WSSecuritySignXPath, 9

WSSecurityVerify, 10

XXML-Signature, 5, 5, 5, 9

SOA Securityopensource.corisecio.com/.../ReferenceGuide_SOASecurity.pdf · 2013. 4. 18. · The...

Documents

Transcript of SOA Securityopensource.corisecio.com/.../ReferenceGuide_SOASecurity.pdf · 2013. 4. 18. · The...