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 SAML audiences that represent the receiving peer.
 135          *
 136          * @return audience values of the peer processing the message
 137          */
 138         const std::vector<const XMLCh*>& getAudiences() const {
 139             return m_audiences;
 140         }
 141
 142         /**
 143          * Returns the SAML audiences that represent the receiving peer.
 144          *
 145          * @return audience values of the peer processing the message
 146          */
 147         std::vector<const XMLCh*>& getAudiences() {
 148             return m_audiences;
 149         }
 150
 151         /**
 152          * Gets the effective time of message processing.
 153          *
 154          * @return  the time at which the message is being processed
 155          */
 156         time_t getTime() const {
 157             if (m_ts == 0)
 158                 return m_ts = time(NULL);
 159             return m_ts;
 160         }
 161
 162         /**
 163          * Returns the message identifier to which the message being evaluated
 164          * is a response.
 165          *
 166          * @return correlated message identifier
 167          */
 168         const XMLCh* getCorrelationID() const {
 169             return m_correlationID;
 170         }
 171
 172         /**
 173          * Gets a mutable array of installed policy rules.
 174          *
 175          * <p>If adding rules, their lifetime must be at least as long as the policy object.
 176          *
 177          * @return  mutable array of rules
 178          */
 179         std::vector<const SecurityPolicyRule*>& getRules() {
 180             return m_rules;
 181         }
 182
 183         /**
 184          * Sets a locked MetadataProvider for the policy.
 185          *
 186          * @param metadata a locked MetadataProvider or NULL
 187          */
 188         void setMetadataProvider(const saml2md::MetadataProvider* metadata) {
 189             m_metadata = metadata;
 190         }
 191
 192         /**
 193          * Sets a MetadataProvider::Criteria instance suitable for use with the
 194          * installed MetadataProvider.
 195          *
 196          * <p>The policy will take ownership of the criteria object when this
 197          * method completes.
 198          *
 199          * @param criteria a MetadataProvider::Criteria instance, or NULL
 200          */
 201         void setMetadataProviderCriteria(saml2md::MetadataProvider::Criteria* criteria);
 202
 203         /**
 204          * Sets a peer role element/type for to the policy.
 205          *
 206          * @param role the peer role element/type or NULL
 207          */
 208         void setRole(const xmltooling::QName* role) {
 209             delete m_role;
 210             m_role = role ? new xmltooling::QName(*role) : NULL;
 211         }
 212
 213         /**
 214          * Sets a TrustEngine for the policy.
 215          *
 216          * @param trust a TrustEngine or NULL
 217          */
 218         void setTrustEngine(const xmltooling::TrustEngine* trust) {
 219             m_trust = trust;
 220         }
 221
 222         /**
 223          * Controls schema validation of incoming XML messages.
 224          * This is separate from other forms of programmatic validation of objects,
 225          * but can detect a much wider range of syntax errors.
 226          *
 227          * @param validate  validation setting
 228          */
 229         void setValidating(bool validate=true) {
 230             m_validate = validate;
 231         }
 232
 233         /**
 234          * Sets flag controlling non-entity issuer support.
 235          *
 236          * @param entityOnly require that Issuer be in entity format
 237          */
 238         void requireEntityIssuer(bool entityOnly=true) {
 239             m_entityOnly = entityOnly;
 240         }
 241
 242         /**
 243          * Sets effective time of message processing.
 244          *
 245          * <p>Assumed to be the time of policy instantiation, can be adjusted to pre- or post-date
 246          * message processing.
 247          *
 248          * @param ts    the time at which the message is being processed
 249          */
 250         void setTime(time_t ts) {
 251             m_ts = ts;
 252         }
 253
 254         /**
 255          * Sets the message identifier to which the message being evaluated
 256          * is a response.
 257          *
 258          * @param correlationID correlated message identifier
 259          */
 260         void setCorrelationID(const XMLCh* correlationID) {
 261             m_correlationID = correlationID;
 262         }
 263
 264         /**
 265          * Evaluates the policy against the given request and message,
 266          * possibly populating message information in the policy object.
 267          *
 268          * @param message           the incoming message
 269          * @param request           the protocol request
 270          *
 271          * @throws BindingException raised if the message/request is invalid according to the supplied rules
 272          */
 273         void evaluate(
 274             const xmltooling::XMLObject& message, const xmltooling::GenericRequest* request=NULL
 275             );
 276
 277         /**
 278          * Resets the policy object and/or clears any per-message state.
 279          *
 280          * <p>Resets can be complete (the default) or merely clear the previous message ID and timestamp
 281          * when evaluating multiple layers of a message.
 282          *
 283          * @param messageOnly   true iff security and issuer state should be left in place
 284          */
 285         virtual void reset(bool messageOnly=false);
 286
 287         /**
 288          * Resets the policy object and/or clears any per-message state for only this specific class.
 289          *
 290          * <p>Resets can be complete (the default) or merely clear the previous message ID and timestamp
 291          * when evaluating multiple layers of a message.
 292          *
 293          * @param messageOnly   true iff security and issuer state should be left in place
 294          */
 295         void _reset(bool messageOnly=false);
 296
 297         /**
 298          * Returns the message identifier as determined by the registered policies.
 299          *
 300          * @return message identifier as determined by the registered policies
 301          */
 302         const XMLCh* getMessageID() const {
 303             return m_messageID;
 304         }
 305
 306         /**
 307          * Returns the message timestamp as determined by the registered policies.
 308          *
 309          * @return message timestamp as determined by the registered policies
 310          */
 311         time_t getIssueInstant() const {
 312             return m_issueInstant;
 313         }
 314
 315         /**
 316          * Gets the issuer of the message as determined by the registered policies.
 317          *
 318          * @return issuer of the message as determined by the registered policies
 319          */
 320         const saml2::Issuer* getIssuer() const {
 321             return m_issuer;
 322         }
 323
 324         /**
 325          * Gets the metadata for the role the issuer is operating in.
 326          *
 327          * @return metadata for the role the issuer is operating in
 328          */
 329         const saml2md::RoleDescriptor* getIssuerMetadata() const {
 330             return m_issuerRole;
 331         }
 332
 333         /**
 334          * Returns the authentication status of the message as determined by the registered policies.
 335          *
 336          * @return true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated
 337          */
 338         bool isAuthenticated() const {
 339             return m_authenticated;
 340         }
 341
 342         /**
 343          * Sets the message identifier as determined by the registered policies.
 344          *
 345          * @param id message identifier
 346          */
 347         void setMessageID(const XMLCh* id) {
 348             xercesc::XMLString::release(&m_messageID);
 349             m_messageID = xercesc::XMLString::replicate(id);
 350         }
 351
 352         /**
 353          * Sets the message timestamp as determined by the registered policies.
 354          *
 355          * @param issueInstant message timestamp
 356          */
 357         void setIssueInstant(time_t issueInstant) {
 358             m_issueInstant = issueInstant;
 359         }
 360
 361         /**
 362          * Sets the issuer of the message as determined by the registered policies.
 363          *
 364          * @param issuer issuer of the message
 365          */
 366         void setIssuer(const saml2::Issuer* issuer);
 367
 368         /**
 369          * Sets the issuer of the message as determined by the registered policies.
 370          *
 371          * @param issuer issuer of the message
 372          */
 373         void setIssuer(const XMLCh* issuer);
 374
 375         /**
 376          * Sets the metadata for the role the issuer is operating in.
 377          *
 378          * @param issuerRole metadata for the role the issuer is operating in
 379          */
 380         void setIssuerMetadata(const saml2md::RoleDescriptor* issuerRole);
 381
 382         /**
 383          * Sets the authentication status of the message as determined by the registered policies.
 384          *
 385          * @param auth indicates whether the issuer/message has been authenticated
 386          */
 387         void setAuthenticated(bool auth) {
 388             m_authenticated = auth;
 389         }
 390
 391         /** Allows override of rules for comparing saml2:Issuer information. */
 392         class SAML_API IssuerMatchingPolicy {
 393             MAKE_NONCOPYABLE(IssuerMatchingPolicy);
 394         public:
 395             IssuerMatchingPolicy() {}
 396             virtual ~IssuerMatchingPolicy() {}
 397
 398             /**
 399              * Returns true iff the two operands "match". Applications can override this method to
 400              * support non-standard issuer matching for complex policies.
 401              *
 402              * <p>The default implementation does a basic comparison of the XML content, treating
 403              * an unsupplied Format as an "entityID".
 404              *
 405              * @param issuer1   the first Issuer to match
 406              * @param issuer2   the second Issuer to match
 407              * @return  true iff the operands match
 408              */
 409             virtual bool issuerMatches(const saml2::Issuer* issuer1, const saml2::Issuer* issuer2) const;
 410
 411             /**
 412              * Returns true iff the two operands "match". Applications can override this method to
 413              * support non-standard issuer matching for complex policies.
 414              *
 415              * <p>The default implementation does a basic comparison of the XML content, treating
 416              * an unsupplied Format as an "entityID".
 417              *
 418              * @param issuer1   the first Issuer to match
 419              * @param issuer2   the second Issuer to match
 420              * @return  true iff the operands match
 421              */
 422             virtual bool issuerMatches(const saml2::Issuer* issuer1, const XMLCh* issuer2) const;
 423         };
 424
 425         /**
 426          * Returns the IssuerMatchingPolicy in effect.
 427          *
 428          * @return the effective IssuerMatchingPolicy
 429          */
 430         const IssuerMatchingPolicy& getIssuerMatchingPolicy() const {
 431             return m_matchingPolicy ? *m_matchingPolicy : m_defaultMatching;
 432         }
 433
 434         /**
 435          * Sets the IssuerMatchingPolicy in effect. Setting no policy will
 436          * cause the simple, default approach to be used.
 437          *
 438          * <p>The matching object will be freed by the SecurityPolicy.
 439          *
 440          * @param matchingPolicy the IssuerMatchingPolicy to use
 441          */
 442         void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy) {
 443             delete m_matchingPolicy;
 444             m_matchingPolicy = matchingPolicy;
 445         }
 446
 447     protected:
 448         /** A shared matching object that just supports the default matching rules. */
 449         static IssuerMatchingPolicy m_defaultMatching;
 450
 451         /** Manufactured MetadataProvider::Criteria instance. */
 452         mutable saml2md::MetadataProvider::Criteria* m_metadataCriteria;
 453
 454     private:
 455         // information extracted from message
 456         XMLCh* m_messageID;
 457         time_t m_issueInstant;
 458         saml2::Issuer* m_issuer;
 459         const saml2md::RoleDescriptor* m_issuerRole;
 460         bool m_authenticated;
 461
 462         // components governing policy rules
 463         IssuerMatchingPolicy* m_matchingPolicy;
 464         std::vector<const SecurityPolicyRule*> m_rules;
 465         const saml2md::MetadataProvider* m_metadata;
 466         xmltooling::QName* m_role;
 467         const xmltooling::TrustEngine* m_trust;
 468         bool m_validate;
 469         bool m_entityOnly;
 470
 471         // contextual information
 472         mutable time_t m_ts;
 473         const XMLCh* m_correlationID;
 474         std::vector<const XMLCh*> m_audiences;
 475     };
 476
 477 };
 478
 479 #if defined (_MSC_VER)
 480     #pragma warning( pop )
 481 #endif
 482
 483 #endif /* __saml_secpol_h__ */