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