saml/binding/SecurityPolicy.h

   1 /*
   2  *  Copyright 2001-2007 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             ) : m_metadataCriteria(NULL), m_messageID(NULL), m_issueInstant(0), m_issuer(NULL), m_issuerRole(NULL), m_authenticated(false),
  74                 m_matchingPolicy(NULL), m_metadata(metadataProvider), m_role(NULL), m_trust(trustEngine), m_validate(validate), m_entityOnly(true) {
  75             if (role)
  76                 m_role = new xmltooling::QName(*role);
  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             return m_metadata;
  88         }
  89
  90         /**
  91          * Returns a reference to a MetadataProvider::Criteria instance suitable for use with the
  92          * installed MetadataProvider.
  93          *
  94          * @return reference to a MetadataProvider::Criteria instance
  95          */
  96         virtual saml2md::MetadataProvider::Criteria& getMetadataProviderCriteria() const;
  97
  98         /**
  99          * Returns the peer role element/type supplied to the policy.
 100          *
 101          * @return the peer role element/type, or an empty QName
 102          */
 103         const xmltooling::QName* getRole() const {
 104             return m_role;
 105         }
 106
 107         /**
 108          * Returns the TrustEngine supplied to the policy.
 109          *
 110          * @return the supplied TrustEngine or NULL
 111          */
 112         const xmltooling::TrustEngine* getTrustEngine() const {
 113             return m_trust;
 114         }
 115
 116         /**
 117          * Returns XML message validation setting.
 118          *
 119          * @return validation flag
 120          */
 121         bool getValidating() const {
 122             return m_validate;
 123         }
 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             return m_entityOnly;
 132         }
 133
 134         /**
 135          * Gets a mutable array of installed policy rules.
 136          *
 137          * <p>If adding rules, their lifetime must be at least as long as the policy object.
 138          *
 139          * @return  mutable array of rules
 140          */
 141         std::vector<const SecurityPolicyRule*>& getRules() {
 142             return m_rules;
 143         }
 144
 145         /**
 146          * Sets a locked MetadataProvider for the policy.
 147          *
 148          * @param metadata a locked MetadataProvider or NULL
 149          */
 150         void setMetadataProvider(const saml2md::MetadataProvider* metadata) {
 151             m_metadata = metadata;
 152         }
 153
 154         /**
 155          * Sets a peer role element/type for to the policy.
 156          *
 157          * @param role the peer role element/type or NULL
 158          */
 159         void setRole(const xmltooling::QName* role) {
 160             delete m_role;
 161             m_role = role ? new xmltooling::QName(*role) : NULL;
 162         }
 163
 164         /**
 165          * Sets a TrustEngine for the policy.
 166          *
 167          * @param trust a TrustEngine or NULL
 168          */
 169         void setTrustEngine(const xmltooling::TrustEngine* trust) {
 170             m_trust = trust;
 171         }
 172
 173         /**
 174          * Controls schema validation of incoming XML messages.
 175          * This is separate from other forms of programmatic validation of objects,
 176          * but can detect a much wider range of syntax errors.
 177          *
 178          * @param validate  validation setting
 179          */
 180         void setValidating(bool validate=true) {
 181             m_validate = validate;
 182         }
 183
 184         /**
 185          * Sets flag controlling non-entity issuer support.
 186          *
 187          * @param entityOnly require that Issuer be in entity format
 188          */
 189         void requireEntityIssuer(bool entityOnly=true) {
 190             m_entityOnly = entityOnly;
 191         }
 192
 193         /**
 194          * Evaluates the policy against the given request and message,
 195          * possibly populating message information in the policy object.
 196          *
 197          * @param message           the incoming message
 198          * @param request           the protocol request
 199          *
 200          * @throws BindingException raised if the message/request is invalid according to the supplied rules
 201          */
 202         void evaluate(
 203             const xmltooling::XMLObject& message, const xmltooling::GenericRequest* request=NULL
 204             );
 205
 206         /**
 207          * Resets the policy object and/or clears any per-message state.
 208          *
 209          * <p>Resets can be complete (the default) or merely clear the previous message ID and timestamp
 210          * when evaluating multiple layers of a message.
 211          *
 212          * @param messageOnly   true iff security and issuer state should be left in place
 213          */
 214         void reset(bool messageOnly=false);
 215
 216         /**
 217          * Returns the message identifier as determined by the registered policies.
 218          *
 219          * @return message identifier as determined by the registered policies
 220          */
 221         const XMLCh* getMessageID() const {
 222             return m_messageID;
 223         }
 224
 225         /**
 226          * Returns the message timestamp as determined by the registered policies.
 227          *
 228          * @return message timestamp as determined by the registered policies
 229          */
 230         time_t getIssueInstant() const {
 231             return m_issueInstant;
 232         }
 233
 234         /**
 235          * Gets the issuer of the message as determined by the registered policies.
 236          *
 237          * @return issuer of the message as determined by the registered policies
 238          */
 239         const saml2::Issuer* getIssuer() const {
 240             return m_issuer;
 241         }
 242
 243         /**
 244          * Gets the metadata for the role the issuer is operating in.
 245          *
 246          * @return metadata for the role the issuer is operating in
 247          */
 248         const saml2md::RoleDescriptor* getIssuerMetadata() const {
 249             return m_issuerRole;
 250         }
 251
 252         /**
 253          * Returns the authentication status of the message as determined by the registered policies.
 254          *
 255          * @return true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated
 256          */
 257         bool isAuthenticated() const {
 258             return m_authenticated;
 259         }
 260
 261         /**
 262          * Sets the message identifier as determined by the registered policies.
 263          *
 264          * @param id message identifier
 265          */
 266         void setMessageID(const XMLCh* id) {
 267             xercesc::XMLString::release(&m_messageID);
 268             m_messageID = xercesc::XMLString::replicate(id);
 269         }
 270
 271         /**
 272          * Sets the message timestamp as determined by the registered policies.
 273          *
 274          * @param issueInstant message timestamp
 275          */
 276         void setIssueInstant(time_t issueInstant) {
 277             m_issueInstant = issueInstant;
 278         }
 279
 280         /**
 281          * Sets the issuer of the message as determined by the registered policies.
 282          *
 283          * @param issuer issuer of the message
 284          */
 285         void setIssuer(const saml2::Issuer* issuer);
 286
 287         /**
 288          * Sets the issuer of the message as determined by the registered policies.
 289          *
 290          * @param issuer issuer of the message
 291          */
 292         void setIssuer(const XMLCh* issuer);
 293
 294         /**
 295          * Sets the metadata for the role the issuer is operating in.
 296          *
 297          * @param issuerRole metadata for the role the issuer is operating in
 298          */
 299         void setIssuerMetadata(const saml2md::RoleDescriptor* issuerRole);
 300
 301         /**
 302          * Sets the authentication status of the message as determined by the registered policies.
 303          *
 304          * @param auth indicates whether the issuer/message has been authenticated
 305          */
 306         void setAuthenticated(bool auth) {
 307             m_authenticated = auth;
 308         }
 309
 310         /** Allows override of rules for comparing saml2:Issuer information. */
 311         class SAML_API IssuerMatchingPolicy {
 312             MAKE_NONCOPYABLE(IssuerMatchingPolicy);
 313         public:
 314             IssuerMatchingPolicy() {}
 315             virtual ~IssuerMatchingPolicy() {}
 316
 317             /**
 318              * Returns true iff the two operands "match". Applications can override this method to
 319              * support non-standard issuer matching for complex policies.
 320              *
 321              * <p>The default implementation does a basic comparison of the XML content, treating
 322              * an unsupplied Format as an "entityID".
 323              *
 324              * @param issuer1   the first Issuer to match
 325              * @param issuer2   the second Issuer to match
 326              * @return  true iff the operands match
 327              */
 328             virtual bool issuerMatches(const saml2::Issuer* issuer1, const saml2::Issuer* issuer2) const;
 329
 330             /**
 331              * Returns true iff the two operands "match". Applications can override this method to
 332              * support non-standard issuer matching for complex policies.
 333              *
 334              * <p>The default implementation does a basic comparison of the XML content, treating
 335              * an unsupplied Format as an "entityID".
 336              *
 337              * @param issuer1   the first Issuer to match
 338              * @param issuer2   the second Issuer to match
 339              * @return  true iff the operands match
 340              */
 341             virtual bool issuerMatches(const saml2::Issuer* issuer1, const XMLCh* issuer2) const;
 342         };
 343
 344         /**
 345          * Returns the IssuerMatchingPolicy in effect.
 346          *
 347          * @return the effective IssuerMatchingPolicy
 348          */
 349         const IssuerMatchingPolicy& getIssuerMatchingPolicy() const {
 350             return m_matchingPolicy ? *m_matchingPolicy : m_defaultMatching;
 351         }
 352
 353         /**
 354          * Sets the IssuerMatchingPolicy in effect. Setting no policy will
 355          * cause the simple, default approach to be used.
 356          *
 357          * <p>The matching object will be freed by the SecurityPolicy.
 358          *
 359          * @param matchingPolicy the IssuerMatchingPolicy to use
 360          */
 361         void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy) {
 362             delete m_matchingPolicy;
 363             m_matchingPolicy = matchingPolicy;
 364         }
 365
 366     protected:
 367         /** A shared matching object that just supports the default matching rules. */
 368         static IssuerMatchingPolicy m_defaultMatching;
 369
 370         /** Manufactured MetadataProvider::Criteria instance. */
 371         mutable saml2md::MetadataProvider::Criteria* m_metadataCriteria;
 372
 373     private:
 374         // information extracted from message
 375         XMLCh* m_messageID;
 376         time_t m_issueInstant;
 377         saml2::Issuer* m_issuer;
 378         const saml2md::RoleDescriptor* m_issuerRole;
 379         bool m_authenticated;
 380
 381         // components governing policy rules
 382         IssuerMatchingPolicy* m_matchingPolicy;
 383         std::vector<const SecurityPolicyRule*> m_rules;
 384         const saml2md::MetadataProvider* m_metadata;
 385         xmltooling::QName* m_role;
 386         const xmltooling::TrustEngine* m_trust;
 387         bool m_validate;
 388         bool m_entityOnly;
 389     };
 390
 391 };
 392
 393 #if defined (_MSC_VER)
 394     #pragma warning( pop )
 395 #endif
 396
 397 #endif /* __saml_secpol_h__ */