X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=saml%2Fbinding%2FSecurityPolicy.h;h=b75b1394bb99297a5bc1fc4dd6cbffdfe98d492f;hb=04482c5c0e5fac5b688b0d23713526a15c51bd31;hp=2074e79c3e6218e557dd05bc0241876ab6079361;hpb=f753e2293ab6a40575bc9b294490e134eac5db9e;p=shibboleth%2Fcpp-opensaml.git diff --git a/saml/binding/SecurityPolicy.h b/saml/binding/SecurityPolicy.h index 2074e79..b75b139 100644 --- a/saml/binding/SecurityPolicy.h +++ b/saml/binding/SecurityPolicy.h @@ -1,51 +1,65 @@ -/* - * Copyright 2001-2006 Internet2 - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at +/** + * Licensed to the University Corporation for Advanced Internet + * Development, Inc. (UCAID) under one or more contributor license + * agreements. See the NOTICE file distributed with this work for + * additional information regarding copyright ownership. + * + * UCAID licenses this file to you under the Apache License, + * Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the + * License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, + * either express or implied. See the License for the specific + * language governing permissions and limitations under the License. */ /** * @file saml/binding/SecurityPolicy.h - * + * * Overall policy used to verify the security of an incoming message. */ #ifndef __saml_secpol_h__ #define __saml_secpol_h__ -#include +#include + +#include #include +#include #if defined (_MSC_VER) #pragma warning( push ) #pragma warning( disable : 4250 4251 ) #endif +namespace xmltooling { + class XMLTOOL_API GenericRequest; + class XMLTOOL_API TrustEngine; +}; + namespace opensaml { - namespace saml2md { - class SAML_API MetadataProvider; + namespace saml2 { + class SAML_API Issuer; }; - + + class SAML_API SecurityPolicyRule; + /** * A policy used to verify the security of an incoming message. - * + * *

Its security mechanisms may be used to examine the transport layer * (e.g client certificates and HTTP basic auth passwords) or to check the * payload of a request to ensure it meets certain criteria (e.g. valid * digital signature, freshness, replay). - * - *

Policy objects can be reused, but are not thread-safe. + * + *

Policy objects can be reused, but are not thread-safe. */ class SAML_API SecurityPolicy { @@ -55,202 +69,356 @@ namespace opensaml { * Constructor for policy. * * @param metadataProvider locked MetadataProvider instance - * @param role identifies the role (generally IdP or SP) of the policy peer + * @param role identifies the role (generally IdP or SP) of the policy peer * @param trustEngine TrustEngine to authenticate policy peer + * @param validate true iff XML parsing should be done with validation */ SecurityPolicy( - const saml2md::MetadataProvider* metadataProvider=NULL, - const xmltooling::QName* role=NULL, - const TrustEngine* trustEngine=NULL - ) : m_issuer(NULL), m_issuerRole(NULL), m_matchingPolicy(NULL), m_metadata(metadataProvider), - m_role(role ? *role : xmltooling::QName()), m_trust(trustEngine) { - } + const saml2md::MetadataProvider* metadataProvider=nullptr, + const xmltooling::QName* role=nullptr, + const xmltooling::TrustEngine* trustEngine=nullptr, + bool validate=true + ); + + virtual ~SecurityPolicy(); /** - * Constructor for policy using existing rules. The lifetime of the policy rules - * must be at least as long as the policy object. + * Returns the locked MetadataProvider supplied to the policy. * - * @param rules reference to array of policy rules to use - * @param metadataProvider locked MetadataProvider instance - * @param role identifies the role (generally IdP or SP) of the policy peer - * @param trustEngine TrustEngine to authenticate policy peer + * @return the supplied MetadataProvider or nullptr */ - SecurityPolicy( - const std::vector& rules, - const saml2md::MetadataProvider* metadataProvider=NULL, - const xmltooling::QName* role=NULL, - const TrustEngine* trustEngine=NULL - ) : m_issuer(NULL), m_issuerRole(NULL), m_matchingPolicy(NULL), m_rules(rules), m_metadata(metadataProvider), - m_role(role ? *role : xmltooling::QName()), m_trust(trustEngine) { - } - - virtual ~SecurityPolicy(); + const saml2md::MetadataProvider* getMetadataProvider() const; /** - * Returns the locked MetadataProvider supplied to the policy. - * - * @return the supplied MetadataProvider or NULL + * Returns a reference to a MetadataProvider::Criteria instance suitable for use with the + * installed MetadataProvider. + * + *

The object will be cleared/reset when returned, so do not mutate it and then + * call the method again before using it. + * + * @return reference to a MetadataProvider::Criteria instance */ - const saml2md::MetadataProvider* getMetadataProvider() const { - return m_metadata; - } + virtual saml2md::MetadataProvider::Criteria& getMetadataProviderCriteria() const; /** * Returns the peer role element/type supplied to the policy. - * + * * @return the peer role element/type, or an empty QName */ - const xmltooling::QName* getRole() const { - return &m_role; - } + const xmltooling::QName* getRole() const; /** * Returns the TrustEngine supplied to the policy. - * - * @return the supplied TrustEngine or NULL + * + * @return the supplied TrustEngine or nullptr */ - const TrustEngine* getTrustEngine() const { - return m_trust; - } + const xmltooling::TrustEngine* getTrustEngine() const; /** - * Adds a SecurityPolicyRule to the policy. The lifetime of the policy rule - * must be at least as long as the policy object. - * - * @param rule SecurityPolicyRule to add + * Returns XML message validation setting. + * + * @return validation flag */ - void addRule(const SecurityPolicyRule* rule) { - m_rules.push_back(rule); - } + bool getValidating() const; + + /** + * Returns flag controlling non-entity issuer support. + * + * @return flag controlling non-entity issuer support + */ + bool requireEntityIssuer() const; + + /** + * Returns the SAML audiences that represent the receiving peer. + * + * @return audience values of the peer processing the message + */ + const std::vector& getAudiences() const; + + /** + * Returns the SAML audiences that represent the receiving peer. + * + * @return audience values of the peer processing the message + */ + std::vector& getAudiences(); + + /** + * Gets the effective time of message processing. + * + * @return the time at which the message is being processed + */ + time_t getTime() const; + + /** + * Returns the message identifier to which the message being evaluated + * is a response. + * + * @return correlated message identifier + */ + const XMLCh* getCorrelationID() const; + + /** + * Gets a mutable array of installed policy rules. + * + *

If adding rules, their lifetime must be at least as long as the policy object. + * + * @return mutable array of rules + */ + std::vector& getRules(); /** * Sets a locked MetadataProvider for the policy. - * - * @param metadata a locked MetadataProvider or NULL + * + * @param metadata a locked MetadataProvider or nullptr + */ + void setMetadataProvider(const saml2md::MetadataProvider* metadata); + + /** + * Sets a MetadataProvider::Criteria instance suitable for use with the + * installed MetadataProvider. + * + *

The policy will take ownership of the criteria object when this + * method completes. + * + * @param criteria a MetadataProvider::Criteria instance, or nullptr */ - void setMetadataProvider(const saml2md::MetadataProvider* metadata) { - m_metadata = metadata; - } + void setMetadataProviderCriteria(saml2md::MetadataProvider::Criteria* criteria); /** * Sets a peer role element/type for to the policy. - * - * @param role the peer role element/type or NULL + * + * @param role the peer role element/type or nullptr */ - void setRole(const xmltooling::QName* role) { - m_role = (role ? *role : xmltooling::QName()); - } + void setRole(const xmltooling::QName* role); /** * Sets a TrustEngine for the policy. - * - * @param trust a TrustEngine or NULL + * + * @param trust a TrustEngine or nullptr */ - void setTrustEngine(const TrustEngine* trust) { - m_trust = trust; - } + void setTrustEngine(const xmltooling::TrustEngine* trust); /** - * Evaluates the rule against the given request and message, - * possibly populating issuer information in the policy object. - * - * @param request the protocol request + * Controls schema validation of incoming XML messages. + * This is separate from other forms of programmatic validation of objects, + * but can detect a much wider range of syntax errors. + * + * @param validate validation setting + */ + void setValidating(bool validate=true); + + /** + * Sets flag controlling non-entity issuer support. + * + * @param entityOnly require that Issuer be in entity format + */ + void requireEntityIssuer(bool entityOnly=true); + + /** + * Sets effective time of message processing. + * + *

Assumed to be the time of policy instantiation, can be adjusted to pre- or post-date + * message processing. + * + * @param ts the time at which the message is being processed + */ + void setTime(time_t ts); + + /** + * Sets the message identifier to which the message being evaluated + * is a response. + * + * @param correlationID correlated message identifier + */ + void setCorrelationID(const XMLCh* correlationID); + + /** + * Evaluates the policy against the given request and message, + * possibly populating message information in the policy object. + * * @param message the incoming message - * @return the identity of the message issuer, in one or more of two forms, or NULL - * - * @throws BindingException thrown if the request/message do not meet the requirements of this rule + * @param request the protocol request + * + * @throws BindingException raised if the message/request is invalid according to the supplied rules + */ + void evaluate(const xmltooling::XMLObject& message, const xmltooling::GenericRequest* request=nullptr); + + /** + * Resets the policy object and/or clears any per-message state. + * + *

Resets can be complete (the default) or merely clear the previous message ID and timestamp + * when evaluating multiple layers of a message. + * + * @param messageOnly true iff security and issuer state should be left in place + */ + virtual void reset(bool messageOnly=false); + + /** + * Resets the policy object and/or clears any per-message state for only this specific class. + * + *

Resets can be complete (the default) or merely clear the previous message ID and timestamp + * when evaluating multiple layers of a message. + * + * @param messageOnly true iff security and issuer state should be left in place */ - void evaluate(const GenericRequest& request, const xmltooling::XMLObject& message); + void _reset(bool messageOnly=false); + + /** + * Returns the message identifier as determined by the registered policies. + * + * @return message identifier as determined by the registered policies + */ + const XMLCh* getMessageID() const; + + /** + * Returns the message timestamp as determined by the registered policies. + * + * @return message timestamp as determined by the registered policies + */ + time_t getIssueInstant() const; /** * Gets the issuer of the message as determined by the registered policies. - * + * * @return issuer of the message as determined by the registered policies */ - const saml2::Issuer* getIssuer() const { - return m_issuer; - } + const saml2::Issuer* getIssuer() const; /** * Gets the metadata for the role the issuer is operating in. - * + * * @return metadata for the role the issuer is operating in */ - const saml2md::RoleDescriptor* getIssuerMetadata() const { - return m_issuerRole; - } + const saml2md::RoleDescriptor* getIssuerMetadata() const; + + /** + * Returns the authentication status of the message as determined by the registered policies. + * + * @return true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated + */ + bool isAuthenticated() const; + + /** + * Sets the message identifier as determined by the registered policies. + * + * @param id message identifier + */ + void setMessageID(const XMLCh* id); + + /** + * Sets the message timestamp as determined by the registered policies. + * + * @param issueInstant message timestamp + */ + void setIssueInstant(time_t issueInstant); /** - * Sets the issuer of the message as determined by external factors. - * The policy object takes ownership of the Issuer object. - * + * Sets the issuer of the message as determined by the registered policies. + * * @param issuer issuer of the message */ - void setIssuer(saml2::Issuer* issuer); - + void setIssuer(const saml2::Issuer* issuer); + + /** + * Sets the issuer of the message as determined by the registered policies. + * + * @param issuer issuer of the message + */ + void setIssuer(const XMLCh* issuer); + /** * Sets the metadata for the role the issuer is operating in. - * + * * @param issuerRole metadata for the role the issuer is operating in */ void setIssuerMetadata(const saml2md::RoleDescriptor* issuerRole); - + + /** + * Sets the authentication status of the message as determined by the registered policies. + * + * @param auth indicates whether the issuer/message has been authenticated + */ + void setAuthenticated(bool auth); + /** Allows override of rules for comparing saml2:Issuer information. */ class SAML_API IssuerMatchingPolicy { MAKE_NONCOPYABLE(IssuerMatchingPolicy); public: - IssuerMatchingPolicy() {} - virtual ~IssuerMatchingPolicy() {} - + IssuerMatchingPolicy(); + virtual ~IssuerMatchingPolicy(); + /** * Returns true iff the two operands "match". Applications can override this method to - * support non-standard issuer matching for complex policies. - * + * support non-standard issuer matching for complex policies. + * *

The default implementation does a basic comparison of the XML content, treating * an unsupplied Format as an "entityID". - * + * * @param issuer1 the first Issuer to match * @param issuer2 the second Issuer to match * @return true iff the operands match */ virtual bool issuerMatches(const saml2::Issuer* issuer1, const saml2::Issuer* issuer2) const; + + /** + * Returns true iff the two operands "match". Applications can override this method to + * support non-standard issuer matching for complex policies. + * + *

The default implementation does a basic comparison of the XML content, treating + * an unsupplied Format as an "entityID". + * + * @param issuer1 the first Issuer to match + * @param issuer2 the second Issuer to match + * @return true iff the operands match + */ + virtual bool issuerMatches(const saml2::Issuer* issuer1, const XMLCh* issuer2) const; }; /** * Returns the IssuerMatchingPolicy in effect. - * + * * @return the effective IssuerMatchingPolicy */ - const IssuerMatchingPolicy& getIssuerMatchingPolicy() const { - return m_matchingPolicy ? *m_matchingPolicy : m_defaultMatching; - } + const IssuerMatchingPolicy& getIssuerMatchingPolicy() const; /** * Sets the IssuerMatchingPolicy in effect. Setting no policy will * cause the simple, default approach to be used. - * + * *

The matching object will be freed by the SecurityPolicy. - * + * * @param matchingPolicy the IssuerMatchingPolicy to use */ - void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy) { - delete m_matchingPolicy; - m_matchingPolicy = matchingPolicy; - } + void setIssuerMatchingPolicy(IssuerMatchingPolicy* matchingPolicy); protected: /** A shared matching object that just supports the default matching rules. */ static IssuerMatchingPolicy m_defaultMatching; + /** Manufactured MetadataProvider::Criteria instance. */ + mutable saml2md::MetadataProvider::Criteria* m_metadataCriteria; + private: + // information extracted from message + xmltooling::xstring m_messageID; + time_t m_issueInstant; saml2::Issuer* m_issuer; const saml2md::RoleDescriptor* m_issuerRole; - + bool m_authenticated; + + // components governing policy rules IssuerMatchingPolicy* m_matchingPolicy; std::vector m_rules; const saml2md::MetadataProvider* m_metadata; - xmltooling::QName m_role; - const TrustEngine* m_trust; + xmltooling::QName* m_role; + const xmltooling::TrustEngine* m_trust; + bool m_validate; + bool m_entityOnly; + + // contextual information + mutable time_t m_ts; + xmltooling::xstring m_correlationID; + std::vector m_audiences; }; };