Description of Transport Layer
Introduction
In sign-up procedure Issuer or Merchant specifies the types of operations he is going to perform, accepts service public certificate, posts the prepared server certificate request on a web-page and accepts server certificate, issued by the service in the same way, as server certificate of any other CA.
Both parties of interaction (Service and Issuer/Merchant) keep two certificates of other party (one for encryption another one - for signing) and two certificates of it's own. Asymmetric RSA keys are used to accomplish immutable logging on each side, hence it is strongly recommended to keep complete logs of all transport activities on the consumer side of interaction.
You may skip the rest of this chapter if the client on your side of the interaction will be implemented with the help of MS WSE 2.0 - all transport details are embedded into the library.
Cryptorgaphy
Here is a brief description how both systems exchange ID's of keys to let other system know which key to use in particular interaction.
On each side there are two public keys of other side and two private keys of it's own enveloped into certificates with additional information (key owner, key designation, etc.) that can be used to reference the certificate.
Notation:
PUB.EK – public encryption key (of opposite party), RSA
PUB.SK – public signature key (of opposite party) , RSA
PVT.EK – private encryption key (own key), RSA
PVT.SK – private signature key (own key), RSA
SES – session key, AES
Transformation processes (requests and responses):
On a client side:
1. build an outgoing message;
2. sign (1) with PVT.SK , the signature will contain a reference to the signature certificate;
3. generate ramdom symmetric key SES;
4. encrypt (1) and (2) by SES;
5. encrypt SES by PUB.EK , the result will contain reference to encryption certificate in a plain text;
6. send (4), (5) to the server.On a server side:
7. get certificate info, transferred in a plain text, find own keys in a key store;
8. decrypt SES using PVT.EK;
9. decrypt message, signature;
10. retrieve cert info from signature, find client’s keys in a key store;
11. check the signature;
12. process the message;Note 1 : PUB.*K on the server side is a public part of PVT.*K on a client side!
Note 2: certificate properties are transferred in plain text, hence, the recipient of the message is publicised.
Errors:
If the server finds an error before he has been assured that the sender is a pre-registered consumer (before the step (12)), error response will not be encrypted but a generic “Not Available” error will be provided in plain-text as a response.
RSA-OAEP or RSA-PKCS1 can be used to encrypt SES, AES128 is used for symmetric encryption, RSA-PKCS1 (SHA-1 for digesting) is used for signing.
XML specifications by example
This is a simple example of SOAP-enabled protocol of interaction, used for web-services, enhanced by ‘XML Signature’ and ‘XML Encryption’ specifications with a concrete encryption mechanism, used by ON-LINE CARD (sm) Service.
Suppose, you would like to call CheckAuthenticateToken SOAP method by sending the following request:
URL: http://webservice.on-linecard.com/Merchant/Primary.asmx
Message header:
<MerchantNamespaceHeader xmlns="http://on-linecard.com/Ns/1.0">
<MerchantNamespaceId>1234-444...</MerchantNamespaceId>
</MerchantNamespaceHeader>
Message body:
<CheckAuthenticateToken xmlns="http://on-linecard.com/Ns/1.0">
<AuthenticateToken>XfGb4gSol...</AuthenticateToken>
</CheckAuthenticateToken>
…and get back the response:
<CheckAuthenticateTokenResponse xmlns="http://on-linecard.com/Ns/1.0">
<Account>1111 1111 1111 1111</Account>
<UserProfilePerson>
<FirstName>John</FirstName>
<MiddleName></MiddleName>
<LastName>Doe</LastName>
</UserProfilePerson>
</CheckAuthenticateTokenResponse>
Unencrypted and unsigned request, according to SOAP, WS-Addressing and WS-Security specs, passed via HTTP will have the following form:
HTTP headers:
POST /Merchant/Primary.asmx HTTP/1.1
Host: webservice.on-linecard.com
Content-Type: text/xml; charset=utf-8
Content-Length: some value
SOAPAction: "http://on-linecard.com/Ns/1.0/CheckAuthenticateToken"<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<MerchantNamespaceHeader xmlns="http://on-linecard.com/Ns/1.0">
<MerchantNamespaceId>1234-444...</MerchantNamespaceId>
</MerchantNamespaceHeader>
<wsa:Action>http://on-linecard.com/Ns/1.0/CheckAuthenticateToken</wsa:Action>
<wsa:MessageID>uuid:290cc063-cffb-42e9-a474-2b4dda92faf3</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://webservice.on-linecard.com/Merchant/Primary.asmx</wsa:To>
<wsse:Security soap:mustUnderstand="1">
<wsu:Timestamp wsu:Id="Timestamp-37e0a060-1779-409e-80fd-a04710ecefc5">
<wsu:Created>2005-04-12T10:58:57Z</wsu:Created>
<wsu:Expires>2005-04-12T11:03:57Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<CheckAuthenticateToken xmlns="http://on-linecard.com/Ns/1.0">
<AuthenticateToken>XfGb4gSol...</AuthenticateToken>
</CheckAuthenticateToken>
</soap:Body>
</soap:Envelope>
and the response will look as follows:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<wsa:Action>http://on-linecard.com/Ns/1.0/CheckAuthenticateTokenResponse</wsa:Action>
<wsa:MessageID>uuid:8c2003e3-2cfe-4046-93fc-e27e88646808</wsa:MessageID>
<wsa:RelatesTo>uuid:290cc063-cffb-42e9-a474-2b4dda92faf3</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-4d977850-cde1-406f-858f-a6fc93046db7">
<wsu:Created>2005-04-12T10:59:01Z</wsu:Created>
<wsu:Expires>2005-04-12T11:04:01Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<CheckAuthenticateTokenResponse xmlns="http://on-linecard.com/Ns/1.0">
<Account>1111 1111 1111 1111</Account>
<UserProfilePerson>
<FirstName>John</FirstName>
<MiddleName></MiddleName>
<LastName>Doe</LastName>
</UserProfilePerson>
</CheckAuthenticateTokenResponse>
</soap:Body>
</soap:Envelope>
TimeStamp field sets an expiration time to protect systems from reply attacks, but, the clocks on boths systems must be synchronized (we use UTC time everywhere ); the time on merchant’s services could differ by up to 15 min from real UTC time.
RelatesTo field explicitly binds the request and response, client *must* check integrity of this field to be sure that it has received the response to the request it had sent!
Let’s add a signature to the request. Besides a signature itself we must specify which key is used as a signature key reference inside it.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<MerchantNamespaceHeader d3p1:Id="Id-5bada063-c587-4e78-9d6f-b50935b5ef28" xmlns:d3p1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns=”http://on-linecard.com/Ns/1.0">
<MerchantNamespaceId>1234-444...</MerchantNamespaceId>
</MerchantNamespaceHeader>
<wsa:Action wsu:Id="Id-d69fafa0-db0e-4f6f-8551-59d21509f495">http://on-linecard.com/Ns/1.0/CheckAuthenticateToken</wsa:Action>
<wsa:MessageID wsu:Id="Id-6a0bbd31-afc1-4cfe-adb3-eabe15f4e213">uuid:0248a880-1fd5-4116-9b03-4715441a6619</wsa:MessageID>
<wsa:ReplyTo wsu:Id="Id-e0fc0c4d-c04f-405e-b26f-26e6b30cb798">
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:To wsu:Id="Id-e3f33536-fd19-48ab-9848-1626f3c08ad7">http://webservice.on-linecard.com/Merchant/Primary.asmx</wsa:To>
<wsse:Security soap:mustUnderstand="1">
<wsu:Timestamp wsu:Id="Timestamp-4d977850-cde1-406f-858f-a6fc93046db7">
<wsu:Created>2005-04-12T10:58:57Z</wsu:Created>
<wsu:Expires>2005-04-12T11:03:57Z</wsu:Expires>
</wsu:Timestamp>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" />
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
<Reference URI="#Id-5bada063-c587-4e78-9d6f-b50935b5ef28">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Id-d69fafa0-db0e-4f6f-8551-59d21509f495">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Id-6a0bbd31-afc1-4cfe-adb3-eabe15f4e213">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Id-e0fc0c4d-c04f-405e-b26f-26e6b30cb798">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Id-e3f33536-fd19-48ab-9848-1626f3c08ad7">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Timestamp-4d977850-cde1-406f-858f-a6fc93046db7">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
<Reference URI="#Id-c4286623-401d-4d6d-b3cc-62640e68bfbe">
<Transforms>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
<DigestValue>...</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>...</SignatureValue>
<KeyInfo>
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">...</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</KeyInfo>
</Signature>
</wsse:Security>
</soap:Header>
<soap:Body wsu:Id="Id-c4286623-401d-4d6d-b3cc-62640e68bfbe">
<CheckAuthenticateToken xmlns="http://on-linecard.com/Ns/1.0">
<AuthenticateToken>XfGb4gSol...</AuthenticateToken>
</CheckAuthenticateToken>
</soap:Body>
</soap:Envelope>
In accord with ws-addressing spec, we sign all headers, and of course, the body is signed too. MerchantNamespaceHeader is signed too as it is required by olc server’s security policy;
wsu:Id attributes added to document parts to reference them from the signature; response is consructed and processed the same way.
The last step is encryption; we build AES key, encrypt it by receiver’s key, and enrypt the body and signature by AES key. Signature must be encrypted as it is required by OLC server’s security policy.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<MerchantNamespaceHeader d3p1:Id="Id-5bada063-c587-4e78-9d6f-b50935b5ef28" xmlns:d3p1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns=”http://on-linecard.com/Ns/1.0">
<MerchantNamespaceId>1234-444...</MerchantNamespaceId>
</MerchantNamespaceHeader>
<wsa:Action wsu:Id="Id-d69fafa0-db0e-4f6f-8551-59d21509f495">http://on-linecard.com/Ns/1.0/CheckAuthenticateToken</wsa:Action>
<wsa:MessageID wsu:Id="Id-6a0bbd31-afc1-4cfe-adb3-eabe15f4e213">uuid:0248a880-1fd5-4116-9b03-4715441a6619</wsa:MessageID>
<wsa:ReplyTo wsu:Id="Id-e0fc0c4d-c04f-405e-b26f-26e6b30cb798">
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:To wsu:Id="Id-e3f33536-fd19-48ab-9848-1626f3c08ad7">http://webservice.on-linecard.com/Merchant/Primary.asmx</wsa:To>
<wsse:Security soap:mustUnderstand="1">
<wsu:Timestamp wsu:Id="Timestamp-4d977850-cde1-406f-858f-a6fc93046db7">
<wsu:Created>2005-04-12T10:58:57Z</wsu:Created>
<wsu:Expires>2005-04-12T11:03:57Z</wsu:Expires>
</wsu:Timestamp>
<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p" />
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">...</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>...</xenc:CipherValue>
</xenc:CipherData>
<xenc:ReferenceList>
<xenc:DataReference URI="#EncryptedContent-4803f9a1-97f6-46f9-915f-e7d52bb37b7f" />
</xenc:ReferenceList>
</xenc:EncryptedKey>
<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p" />
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">...</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>...</xenc:CipherValue>
</xenc:CipherData>
<xenc:ReferenceList>
<xenc:DataReference URI="#EncryptedContent-df950a4c-0173-4ba8-8aec-e6453bfd0f27" />
</xenc:ReferenceList>
</xenc:EncryptedKey>
<Signature Id="Signature-46ea8f03-8a24-44c9-b442-d44b0b06754d" xmlns="http://www.w3.org/2000/09/xmldsig#">
<xenc:EncryptedData Id="EncryptedContent-4803f9a1-97f6-46f9-915f-e7d52bb37b7f" Type="http://www.w3.org/2001/04/xmlenc#Content" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" />
<xenc:CipherData>
<xenc:CipherValue>...</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</Signature>
</wsse:Security>
</soap:Header>
<soap:Body wsu:Id="Id-ea6a7cb6-8c9d-497a-aa5d-4bc18677eb43">
<xenc:EncryptedData Id="EncryptedContent-df950a4c-0173-4ba8-8aec-e6453bfd0f27" Type="http://www.w3.org/2001/04/xmlenc#Content" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" />
<xenc:CipherData>
<xenc:CipherValue>... </xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</soap:Body>
</soap:Envelope>
Two security tokens were specified – one for encryption, one for signature; signature and the body content were replaced by EnryptedData. WSE 2.0 can not process EncryptedKey with two references, we must provide 2 different AES keys for the signature and for request body.
Errors are returned via SOAP Fault tag in the following form:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>...</soap:Header>
<soap:Body>
<soap:Fault>
<faultcode>code of fault</faultcode>
<faultstring>message describing the fault</faultstring>
<detail />
</soap:Fault>
</soap:Body>
</soap:Envelope>
If server knows the sender (signature is valid, server feels good, and request conforms to the policy) fault response is signed and encrypted too.
June 14, 2005 in 2. Transport Layer | Permalink | Comments (0)
