saml/binding/SecurityPolicy.h

   1 /*
   2  *  Copyright 2001-2009 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file saml/binding/SecurityPolicy.h
  19  *
  20  * Overall policy used to verify the security of an incoming message.
  21  */
  22
  23 #ifndef __saml_secpol_h__
  24 #define __saml_secpol_h__
  25
  26 #include <saml/saml2/metadata/MetadataProvider.h>
  27
  28 #include <ctime>
  29 #include <vector>
  30 #include <xmltooling/io/GenericRequest.h>
  31 #include <xmltooling/security/TrustEngine.h>
  32
  33 #if defined (_MSC_VER)
  34     #pragma warning( push )
  35     #pragma warning( disable : 4250 4251 )
  36 #endif
  37
  38 namespace opensaml {
  39
  40     namespace saml2 {
  41         class SAML_API Issuer;
  42     };
  43
  44     class SAML_API SecurityPolicyRule;
  45
  46     /**
  47      * A policy used to verify the security of an incoming message.
  48      *
  49      * <p>Its security mechanisms may be used to examine the transport layer
  50      * (e.g client certificates and HTTP basic auth passwords) or to check the
  51      * payload of a request to ensure it meets certain criteria (e.g. valid
  52      * digital signature, freshness, replay).
  53      *
  54      * <p>Policy objects can be reused, but are not thread-safe.
  55      */
  56     class SAML_API SecurityPolicy
  57     {
  58         MAKE_NONCOPYABLE(SecurityPolicy);
  59     public:
  60         /**
  61          * Constructor for policy.
  62          *
  63          * @param metadataProvider  locked MetadataProvider instance
  64          * @param role              identifies the role (generally IdP or SP) of the policy peer
  65          * @param trustEngine       TrustEngine to authenticate policy peer
  66          * @param validate          true iff XML parsing should be done with validation
  67          */
  68         SecurityPolicy(
  69             const saml2md::MetadataProvider* metadataProvider=NULL,
  70             const xmltooling::QName* role=NULL,
  71             const xmltooling::TrustEngine* trustEngine=NULL,
  72             bool validate=true
  73             );
  74
  75         virtual ~SecurityPolicy();
  76
  77         /**
  78          * Returns the locked MetadataProvider supplied to the policy.
  79          *
  80          * @return the supplied MetadataProvider or NULL
  81          */
  82         const saml2md::MetadataProvider* getMetadataProvider() const {
  83             return m_metadata;
  84         }
  85
  86         /**
  87          * Returns a reference to a MetadataProvider::Criteria instance suitable for use with the
  88          * installed MetadataProvider.
  89          *
  90          * <p>The object will be cleared/reset when returned, so do not mutate it and then
  91          * call the method again before using it.
  92          *
  93          * @return reference to a MetadataProvider::Criteria instance
  94          */
  95         virtual saml2md::MetadataProvider::Criteria& getMetadataProviderCriteria() const;
  96
  97         /**
  98          * Returns the peer role element/type supplied to the policy.
  99          *
 100          * @return the peer role element/type, or an empty QName
 101          */
 102         const xmltooling::QName* getRole() const {
 103             return m_role;
 104         }
 105
 106         /**
 107          * Returns the TrustEngine supplied to the policy.
 108          *
 109          * @return the supplied TrustEngine or NULL
 110          */
 111         const xmltooling::TrustEngine* getTrustEngine() const {
 112             return m_trust;
 113         }
 114
 115         /**
 116          * Returns XML message validation setting.
 117          *
 118          * @return validation flag
 119          */
 120         bool getValidating() const {
 121             return m_validate;
 122         }
 123
 124         /**
 125          * Returns flag controlling non-entity issuer support.
 126          *
 127          * @return flag controlling non-entity issuer support
 128          */
 129         bool requireEntityIssuer() const {
 130             return m_entityOnly;
 131         }
 132
 133         /**
 134          * Returns the entityID of the receiving entity.
 135          *
 136          * @return entityID of the peer processing the message
 137          */
 138         const XMLCh* getRecipient() {
 139             return m_recipient;
 140         }
 141
 142         /**
 143          * Gets the effective time of message processing.
 144          *
 145          * @return  the time at which the message is being processed
 146          */
 147         time_t getTime() {
 148             if (m_ts == 0)
 149                 return m_ts = time(NULL);
 150             return m_ts;
 151         }
 152
 153         /**
 154          * Gets a mutable array of installed policy rules.
 155          *
 156          * <p>If adding rules, their lifetime must be at least as long as the policy object.
 157          *
 158          * @return  mutable array of rules
 159          */
 160         std::vector<const SecurityPolicyRule*>& getRules() {
 161             return m_rules;
 162         }
 163
 164         /**
 165          * Sets a locked MetadataProvider for the policy.
 166          *
 167          * @param metadata a locked MetadataProvider or NULL
 168          */
 169         void setMetadataProvider(const saml2md::MetadataProvider* metadata) {
 170             m_metadata = metadata;
 171         }
 172
 173         /**
 174          * Sets a MetadataProvider::Criteria instance suitable for use with the
 175          * installed MetadataProvider.
 176          *
 177          * <p>The policy will take ownership of the criteria object when this
 178          * method completes.
 179          *
 180          * @param criteria a MetadataProvider::Criteria instance, or NULL
 181          */
 182         void setMetadataProviderCriteria(saml2md::MetadataProvider::Criteria* criteria);
 183
 184         /**
 185          * Sets a peer role element/type for to the policy.
 186          *
 187          * @param role the peer role element/type or NULL
 188          */
 189         void setRole(const xmltooling::QName* role) {
 190             delete m_role;
 191             m_role = role ? new xmltooling::QName(*role) : NULL;
 192         }
 193
 194         /**
 195          * Sets a TrustEngine for the policy.
 196          *
 197          * @param trust a TrustEngine or NULL
 198          */
 199         void setTrustEngine(const xmltooling::TrustEngine* trust) {
 200             m_trust = trust;
 201         }
 202
 203         /**
 204          * Controls schema validation of incoming XML messages.
 205          * This is separate from other forms of programmatic validation of objects,
 206          * but can detect a much wider range of syntax errors.
 207          *
 208          * @param validate  validation setting
 209          */
 210         void setValidating(bool validate=true) {
 211             m_validate = validate;
 212         }
 213
 214         /**
 215          * Sets flag controlling non-entity issuer support.
 216          *
 217          * @param entityOnly require that Issuer be in entity format
 218          */
 219         void requireEntityIssuer(bool entityOnly=true) {
 220             m_entityOnly = entityOnly;
 221         }
 222
 223         /**
 224          * Sets entityID of receiving entity.
 225          *
 226          * @param recipient the entityID of the peer processing the message
 227          */
 228         void setRecipient(const XMLCh* recipient) {
 229             m_recipient = recipient;
 230         }
 231
 232         /**
 233          * Sets effective time of message processing.
 234          *
 235          * <p>Assumed to be the time of policy instantiation, can be adjusted to pre- or post-date
 236          * message processing.
 237          *
 238          * @param ts    the time at which the message is being processed
 239          */
 240         void setTime(time_t ts) {
 241             m_ts = ts;
 242         }
 243
 244         /**
 245          * Evaluates the policy against the given request and message,
 246          * possibly populating message information in the policy object.
 247          *
 248          * @param message           the incoming message
 249          * @param request           the protocol request
 250          *
 251          * @throws BindingException raised if the message/request is invalid according to the supplied rules
 252          */
 253         void evaluate(
 254             const xmltooling::XMLObject& message, const xmltooling::GenericRequest* request=NULL
 255             );
 256
 257         /**
 258          * Resets the policy object and/or clears any per-message state.
 259          *
 260          * <p>Resets can be complete (the default) or merely clear the previous message ID and timestamp
 261          * when evaluating multiple layers of a message.
 262          *
 263          * @param messageOnly   true iff security and issuer state should be left in place
 264          */
 265         virtual void reset(bool messageOnly=false);
 266
 267         /**
 268          * Resets the policy object and/or clears any per-message state for only this specific class.
 269          *
 270          * <p>Resets can be complete (the default) or merely clear the previous message ID and timestamp
 271          * when evaluating multiple layers of a message.
 272          *
 273          * @param messageOnly   true iff security and issuer state should be left in place
 274          */
 275         void _reset(bool messageOnly=false);
 276
 277         /**
 278          * Returns the message identifier as determined by the registered policies.
 279          *
 280          * @return message identifier as determined by the registered policies
 281          */
 282         const XMLCh* getMessageID() const {
 283             return m_messageID;
 284         }
 285
 286         /**
 287          * Returns the message timestamp as determined by the registered policies.
 288          *
 289          * @return message timestamp as determined by the registered policies
 290          */
 291         time_t getIssueInstant() const {
 292             return m_issueInstant;
 293         }
 294
 295         /**
 296          * Gets the issuer of the message as determined by the registered policies.
 297          *
 298          * @return issuer of the message as determined by the registered policies
 299          */
 300         const saml2::Issuer* getIssuer() const {
 301             return m_issuer;
 302         }
 303
 304         /**
 305          * Gets the metadata for the role the issuer is operating in.
 306          *
 307          * @return metadata for the role the issuer is operating in
 308          */
 309         const saml2md::RoleDescriptor* getIssuerMetadata() const {
 310             return m_issuerRole;
 311         }
 312
 313         /**
 314          * Returns the authentication status of the message as determined by the registered policies.
 315          *
 316          * @return true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated
 317          */
 318         bool isAuthenticated() const {
 319             return m_authenticated;
 320         }
 321
 322         /**
 323          * Sets the message identifier as determined by the registered policies.
 324          *
 325          * @param id message identifier
 326          */
 327         void setMessageID(const XMLCh* id) {
 328             xercesc::XMLString::release(&m_messageID);
 329             m_messageID = xercesc::XMLString::replicate(id);
 330         }
 331
 332         /**
 333          * Sets the message timestamp as determined by the registered policies.
 334          *
 335          * @param issueInstant message timestamp
 336          */
 337         void setIssueInstant(time_t issueInstant) {
 338             m_issueInstant = issueInstant;
 339         }
 340
 341         /**
 342          * Sets the issuer of the message as determined by the registered policies.
 343          *
 344          * @param issuer issuer of the message
 345          */
 346         void setIssuer(const saml2::Issuer* issuer);
 347
 348         /**
 349          * Sets the issuer of the message as determined by the registered policies.
 350          *
 351          * @param issuer issuer of the message
 352          */
 353         void setIssuer(const XMLCh* issuer);
 354
 355         /**
 356          * Sets the metadata for the role the issuer is operating in.
 357          *
 358          * @param issuerRole metadata for the role the issuer is operating in
 359          */
 360         void setIssuerMetadata(const saml2md::RoleDescriptor* issuerRole);
 361
 362         /**
 363          * Sets the authentication status of the message as determined by the registered policies.
 364          *
 365          * @param auth indicates whether the issuer/message has been authenticated
 366          */
 367         void setAuthenticated(bool auth) {
 368             m_authenticated = auth;
 369         }
 370
 371         /** Allows override of rules for comparing saml2:Issuer information. */
 372         class SAML_API IssuerMatchingPolicy {
 373             MAKE_NONCOPYABLE(IssuerMatchingPolicy);
 374         public:
 375             IssuerMatchingPolicy() {}
 376             virtual ~IssuerMatchingPolicy() {}
 377
 378             /**
 379              * Returns true iff the two operands "match". Applications can override this method to
 380              * support non-standard issuer matching for complex policies.
 381              *
 382              * <p>The default implementation does a basic comparison of the XML content, treating
 383              * an unsupplied Format as an "entityID".
 384              *
 385              * @param issuer1   the first Issuer to match
 386              * @param issuer2   the second Issuer to match
 387              * @return  true iff the operands match
 388              */
 389             virtual bool issuerMatches(const saml2::Issuer* issuer1, const saml2::Issuer* issuer2) const;
 390
 391             /**
 392              * Returns true iff the two operands "match". Applications can override this method to
 393              * support non-standard issuer matching for complex policies.
 394              *
 395              * <p>The default implementation does a basic comparison of the XML content, treating
 396              * an unsupplied Format as an "entityID".
 397              *
 398              * @param issuer1   the first Issuer to match
 399              * @param issuer2   the second Issuer to match
 400              * @return  true iff the operands match
 401              */
 402             virtual bool issuerMatches(const saml2::Issuer* issuer1, const XMLCh* issuer2) const;
 403         };
 404
 405         /**
 406          * Returns the IssuerMatchingPolicy in effect.
 407          *
 408          * @return the effective IssuerMatchingPolicy
 409          */
 410         const IssuerMatchingPolicy& getIssuerMatchingPolicy() const {
 411             return m_matchingPolicy ? *m_matchingPolicy : m_defaultMatching;
 412         }
 413
 414         /**
 415          * Sets the IssuerMatchingPolicy in effect. Setting no policy will
 416          * cause the simple, default approach to be used.
 417          *
 418          * <p>The matching object will be freed by the SecurityPolicy.
 419          *
 420          * @param matchingPolicy the IssuerMatchingPolicy to use
 421          */
 422         void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy) {
 423             delete m_matchingPolicy;
 424             m_matchingPolicy = matchingPolicy;
 425         }
 426
 427     protected:
 428         /** A shared matching object that just supports the default matching rules. */
 429         static IssuerMatchingPolicy m_defaultMatching;
 430
 431         /** Manufactured MetadataProvider::Criteria instance. */
 432         mutable saml2md::MetadataProvider::Criteria* m_metadataCriteria;
 433
 434     private:
 435         // information extracted from message
 436         XMLCh* m_messageID;
 437         time_t m_issueInstant;
 438         saml2::Issuer* m_issuer;
 439         const saml2md::RoleDescriptor* m_issuerRole;
 440         bool m_authenticated;
 441
 442         // components governing policy rules
 443         IssuerMatchingPolicy* m_matchingPolicy;
 444         std::vector<const SecurityPolicyRule*> m_rules;
 445         const saml2md::MetadataProvider* m_metadata;
 446         xmltooling::QName* m_role;
 447         const xmltooling::TrustEngine* m_trust;
 448         bool m_validate;
 449         bool m_entityOnly;
 450
 451         // contextual information
 452         const XMLCh* m_recipient;
 453         time_t m_ts;
 454     };
 455
 456 };
 457
 458 #if defined (_MSC_VER)
 459     #pragma warning( pop )
 460 #endif
 461
 462 #endif /* __saml_secpol_h__ */