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