WS-SecurityPolicy is a very interesting specification. It really shows that it incorporated the feedback of people which actually used WS-Security: it address historical concerns like the order of operations, the role of the tokens (initiator rather than recipient), the protection of elements of the wsse:security header... hey, it even acknowledges that sometimes the security may come from the transport! It gives up some "mathematical" beauty in favor of a more immediate usage, at the price of a proliferation of the assertions. And it's clear from the property approach that it was designed also with the enforcing stage in mind, besided the checking one. However it got pretty think, it's a 90 pg PDF: and some part of it is inevitably syntactic sugar.
So I thought it could be useful to pull out a Bignami out of it. "Bignami" was (is?) a collection of small sub-pocket books, which covered the absolute essentials of various school subject (Math, Latin, Italian, Phisics...) and was especially handy before classworks. I have to warn you, in the shrinking effort I may leave out important things or simplify to the point of being wrong (despite mr. Einstein advice. BTW: I had the pleasure to have tea more than once with mr. Trautman, he's an exquisite person); plus, here it's way past midnight and the usual drowsiness is already clouding my judgement 🙂
WS-SecurityPolicy describes an assertion framework which covers WSS, WS-Trust and WS-SecueConversation; however it can leverage security features of transport, too. Let's have a short summary of relevant sections.
3.1 - WS-SP assertions fall in 5 main categories. protection assertions rule confidentiality and integrity; conditional assettions express conditions; security binding assertions gather general assertions, ruling how to deal with parts: quoting the spec, "At its simplest form, the security binding restricts what can be placed in the wsse:Security header and the associated processing rules."; supporting token assertions describe token which perform "ancillary" operations in respect to the ones which determines the binding pattern (more about this later); WSS & trust assertions express how certain specific aspects of the specifications are applied.
3.2 - in depht explanation of nesting and "combinatorial" assetion algebra
3.3 - gives more detail about what a binding is. WS-SP supplies 3 bindings: symmetric binding, asymmetric binding, transport binding. They represent common patterns, that's to say specific values for the following carachteristics:
- which tokens will have to be there, and their role in the message
- how to transfer keys
- which message parts are mandatory
- how wsse:security will look like in terms of kind, number & order of elements
- how the messages will be correlated
4 - details of the nesting machanism. From now on, every assertion will implicitly have a sp:policy subassertion evan if I don't mention it
4.2 - policy subjects. there are 3 possible subjects to which the policy may refer to: Message, Operation, Endpoint. Different kinds of assertions apply to different subjects.
5 - Protection Assertions, straightforward.
5-1 Integrity, tells you what to sign. Comes in 2 flavors: SignedParts, which can specify parts by qname (body or headers, nothing inside wsse:security), and SignedElements, which specify the signee via XPath.
5-2 Confidentiality, with EncryptedParts and EncryptedElements pretty symmetric to the aboves.
5-3 RequiredElemnts, tells you (via XPath) what must be present in the message
6 token assertions. Features a complete collection of modern kinds. I'll be very quick & cryptic from now on
6-1-1: TokenInclusion property: determines how the token must be included
- Never: the token must not travel, ever.You can use references
- Once: it must travel the first time the target endpoint is contacted, then no more. useful for spreading session.
- AlwaysToRecipient: everytime the initiator sends a message, the token must appear; everytime the recipient sends a message back, it must not
- Always: !(Never)
6-2 Derived Keys property: indicates if it is mandated what is explained in ws-SecureConversation spec.
U can speciffy the ut profile version (10,11). Usual worning about cryptographic weakness.
Interesting! A token issued as described in ws-trust. Subassertions:
- Issuer (an EP)
Standard X509 token. Usual properties, distinction per profile level
Includeserial,keyid,thumbprint, X509 token profile props
Include, derived, keyid, kerberos profile
635 SpnegoContextToken (n-leg ws-trust)
Include, issuer, derivedkeys
Assumes you already have one SCT; otherwise you need SecureConversationToken (below) or IssuedToken
If it describes full cycle (issue+usage) of SCT, there's the need for 2 policies: Bootstrap and Outer
Include, issuer (if different from target), derived, externaluri
638 SamlToken (assumes u already have one)
Include, derivedm, samlvers(10,11,20)+profvers(10,11)
Include,requirederived, requirekeyidrf, relver (10,20)+profvers (10,11)
Indicates use of HTTPS. Can specify if the client certificate is mandatory
7 Security Bindings Properties
Like variables in code, properties are assigned according to the content of the corresponding assertions. it seems that all together they are the state of the policy. quick descriptions
71 algorithm suite, kind of algorithm used (DES and similar)
73 protection order (encryptbeforesigning, signbeforeencrypting)
74 Signature protection (signature has to be encrypted)
75 tokenprotection (token has to be included in the signature)
76 entire header and body signature (most patrs have to be signed)
77 SecurityHeaderLayout (how wsse:security elements order is affected by the policy)
- Strict, everything must be declared before being used (a signing token appears before the signature, signed elements in wsse:security must appear before their signature, etc)
- Lax doesn't matter
- LaxTimestampFirst doesn't matter, but Timestam as first thing
- LaxTimestampLast doesn't matter, but Timestam as last thing
8 securitybinding assertions
how properties are mapped into assertions
81 AlgorithmSuite sp:Basic128, sp:TripleDes, etc etc
82 Layout sp:Strict,… LaxTsFist,…
This is the first security binding we meet. No WSS requested. It has the following subassertions:
Transporttoken, Algorithmsuite, Layout, includetimestamp
Assumes symmetric interaction between initiator and recipient. And the use of WSS, of course.
Can have EncryptionToken and SignatureToken, OR ProtectionToken (used for both encryption and signing). The two sides of the OR cannot mix. If the messages go back and forth, the above directives will be honored also from ecipient to intiator (SignatureToken will sign both requeste and replies). Subassertions:
Algosuite, layout, includets, encryptbeforesign, protectstoken, onlysignentireheadersandbody
Assumes asymmetrical communication. And WSS.
InitiatorToken is used for signing initiator->recipient and encrypting recipient->initiator, RecipientToken is specular. Subassertions:
algosuite, layout, includets, encbeforesign, protrctstoken, onlysignentireheadersandbody
9 Supporting Tokens assertions
Those tokens are not the ones which determines the kind of security binding, yet they are present in the message and they often perform an active role. 4 kinds.
91 SupportingTokens simply appear in wsse:security. They can sign and encrypt different parts. Subassertions:
Token assertion, Algosuite, SignedParts/Elements,encparts/els
92 SignedSupportingTokens, as the above but they are included in the main signature (the one of the security binding level)
93 EndorsingSupportingTokens, they sign the main signature
94 SignedEndorsingSupportingTokens. The two tokens sign each other (92+93)
10: wss options
Those are options of the WSS standard,can't really dig them at this hour of the night 🙂 two main flavor: Wss10, Wss11. They decide the version of WSS to which they refer to, and they contains the options in form of subassertions. For example a property may decide if the refcipien must be able to understand embedded tokens, or references made by serial number.
11: ws-trust options
Same as above, but for WS-Trust. Trust10 is the container of MustSupportClientchallenge, Server challenge, Client entropy, Server entropy, IssuedToken...