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<xmltooling::xstring>& 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<xmltooling::xstring>& 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.c_str();
 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.erase();
 262             if (correlationID)
 263                 m_correlationID = correlationID;
 264         }
 265
 266         /**
 267          * Evaluates the policy against the given request and message,
 268          * possibly populating message information in the policy object.
 269          *
 270          * @param message           the incoming message
 271          * @param request           the protocol request
 272          *
 273          * @throws BindingException raised if the message/request is invalid according to the supplied rules
 274          */
 275         void evaluate(const xmltooling::XMLObject& message, const xmltooling::GenericRequest* request=NULL);
 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.c_str();
 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             m_messageID.erase();
 349             if (id)
 350                 m_messageID = id;
 351         }
 352
 353         /**
 354          * Sets the message timestamp as determined by the registered policies.
 355          *
 356          * @param issueInstant message timestamp
 357          */
 358         void setIssueInstant(time_t issueInstant) {
 359             m_issueInstant = issueInstant;
 360         }
 361
 362         /**
 363          * Sets the issuer of the message as determined by the registered policies.
 364          *
 365          * @param issuer issuer of the message
 366          */
 367         void setIssuer(const saml2::Issuer* issuer);
 368
 369         /**
 370          * Sets the issuer of the message as determined by the registered policies.
 371          *
 372          * @param issuer issuer of the message
 373          */
 374         void setIssuer(const XMLCh* issuer);
 375
 376         /**
 377          * Sets the metadata for the role the issuer is operating in.
 378          *
 379          * @param issuerRole metadata for the role the issuer is operating in
 380          */
 381         void setIssuerMetadata(const saml2md::RoleDescriptor* issuerRole);
 382
 383         /**
 384          * Sets the authentication status of the message as determined by the registered policies.
 385          *
 386          * @param auth indicates whether the issuer/message has been authenticated
 387          */
 388         void setAuthenticated(bool auth) {
 389             m_authenticated = auth;
 390         }
 391
 392         /** Allows override of rules for comparing saml2:Issuer information. */
 393         class SAML_API IssuerMatchingPolicy {
 394             MAKE_NONCOPYABLE(IssuerMatchingPolicy);
 395         public:
 396             IssuerMatchingPolicy() {}
 397             virtual ~IssuerMatchingPolicy() {}
 398
 399             /**
 400              * Returns true iff the two operands "match". Applications can override this method to
 401              * support non-standard issuer matching for complex policies.
 402              *
 403              * <p>The default implementation does a basic comparison of the XML content, treating
 404              * an unsupplied Format as an "entityID".
 405              *
 406              * @param issuer1   the first Issuer to match
 407              * @param issuer2   the second Issuer to match
 408              * @return  true iff the operands match
 409              */
 410             virtual bool issuerMatches(const saml2::Issuer* issuer1, const saml2::Issuer* issuer2) const;
 411
 412             /**
 413              * Returns true iff the two operands "match". Applications can override this method to
 414              * support non-standard issuer matching for complex policies.
 415              *
 416              * <p>The default implementation does a basic comparison of the XML content, treating
 417              * an unsupplied Format as an "entityID".
 418              *
 419              * @param issuer1   the first Issuer to match
 420              * @param issuer2   the second Issuer to match
 421              * @return  true iff the operands match
 422              */
 423             virtual bool issuerMatches(const saml2::Issuer* issuer1, const XMLCh* issuer2) const;
 424         };
 425
 426         /**
 427          * Returns the IssuerMatchingPolicy in effect.
 428          *
 429          * @return the effective IssuerMatchingPolicy
 430          */
 431         const IssuerMatchingPolicy& getIssuerMatchingPolicy() const {
 432             return m_matchingPolicy ? *m_matchingPolicy : m_defaultMatching;
 433         }
 434
 435         /**
 436          * Sets the IssuerMatchingPolicy in effect. Setting no policy will
 437          * cause the simple, default approach to be used.
 438          *
 439          * <p>The matching object will be freed by the SecurityPolicy.
 440          *
 441          * @param matchingPolicy the IssuerMatchingPolicy to use
 442          */
 443         void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy) {
 444             delete m_matchingPolicy;
 445             m_matchingPolicy = matchingPolicy;
 446         }
 447
 448     protected:
 449         /** A shared matching object that just supports the default matching rules. */
 450         static IssuerMatchingPolicy m_defaultMatching;
 451
 452         /** Manufactured MetadataProvider::Criteria instance. */
 453         mutable saml2md::MetadataProvider::Criteria* m_metadataCriteria;
 454
 455     private:
 456         // information extracted from message
 457         xmltooling::xstring m_messageID;
 458         time_t m_issueInstant;
 459         saml2::Issuer* m_issuer;
 460         const saml2md::RoleDescriptor* m_issuerRole;
 461         bool m_authenticated;
 462
 463         // components governing policy rules
 464         IssuerMatchingPolicy* m_matchingPolicy;
 465         std::vector<const SecurityPolicyRule*> m_rules;
 466         const saml2md::MetadataProvider* m_metadata;
 467         xmltooling::QName* m_role;
 468         const xmltooling::TrustEngine* m_trust;
 469         bool m_validate;
 470         bool m_entityOnly;
 471
 472         // contextual information
 473         mutable time_t m_ts;
 474         xmltooling::xstring m_correlationID;
 475         std::vector<xmltooling::xstring> m_audiences;
 476     };
 477
 478 };
 479
 480 #if defined (_MSC_VER)
 481     #pragma warning( pop )
 482 #endif
 483
 484 #endif /* __saml_secpol_h__ */