saml/binding/SecurityPolicy.h

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