X-Git-Url: http://www.project-moonshot.org/gitweb/?p=shibboleth%2Fcpp-opensaml.git;a=blobdiff_plain;f=saml%2Fbinding%2FSecurityPolicy.h;h=b655d01e478a6621e2ed0e5dd334f33338f63eed;hp=fed55f7f74b9c01bc14dae49d3a5b3705eb41cfd;hb=c3cd4ec3fa87d0ad3c6f65c1a5e15f548b1b6cc2;hpb=0542de711d105e1cdfd2d9273764e01ccf2fa92a diff --git a/saml/binding/SecurityPolicy.h b/saml/binding/SecurityPolicy.h index fed55f7..b655d01 100644 --- a/saml/binding/SecurityPolicy.h +++ b/saml/binding/SecurityPolicy.h @@ -1,6 +1,6 @@ /* - * Copyright 2001-2007 Internet2 - * + * Copyright 2001-2009 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 @@ -16,18 +16,17 @@ /** * @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 #include #include @@ -41,22 +40,18 @@ namespace opensaml { namespace saml2 { class SAML_API Issuer; }; - namespace saml2md { - class SAML_API MetadataProvider; - class SAML_API RoleDescriptor; - }; - + 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 { @@ -64,9 +59,9 @@ namespace opensaml { public: /** * 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 */ @@ -75,17 +70,13 @@ namespace opensaml { const xmltooling::QName* role=NULL, const xmltooling::TrustEngine* trustEngine=NULL, bool validate=true - ) : m_messageID(NULL), m_issueInstant(0), m_issuer(NULL), m_issuerRole(NULL), m_authenticated(false), - m_matchingPolicy(NULL), m_metadata(metadataProvider), m_role(NULL), m_trust(trustEngine), m_validate(validate), m_entityOnly(true) { - if (role) - m_role = new xmltooling::QName(*role); - } + ); virtual ~SecurityPolicy(); /** * Returns the locked MetadataProvider supplied to the policy. - * + * * @return the supplied MetadataProvider or NULL */ const saml2md::MetadataProvider* getMetadataProvider() const { @@ -93,8 +84,19 @@ namespace opensaml { } /** + * 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 + */ + 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 { @@ -103,7 +105,7 @@ namespace opensaml { /** * Returns the TrustEngine supplied to the policy. - * + * * @return the supplied TrustEngine or NULL */ const xmltooling::TrustEngine* getTrustEngine() const { @@ -112,16 +114,16 @@ namespace opensaml { /** * Returns XML message validation setting. - * + * * @return validation flag */ bool getValidating() const { return m_validate; } - + /** * Returns flag controlling non-entity issuer support. - * + * * @return flag controlling non-entity issuer support */ bool requireEntityIssuer() const { @@ -129,10 +131,30 @@ namespace opensaml { } /** + * Returns the entityID of the receiving entity. + * + * @return entityID of the peer processing the message + */ + const XMLCh* getRecipient() { + return m_recipient; + } + + /** + * Gets the effective time of message processing. + * + * @return the time at which the message is being processed + */ + time_t getTime() { + if (m_ts == 0) + return m_ts = time(NULL); + return m_ts; + } + + /** * 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() { @@ -141,7 +163,7 @@ namespace opensaml { /** * Sets a locked MetadataProvider for the policy. - * + * * @param metadata a locked MetadataProvider or NULL */ void setMetadataProvider(const saml2md::MetadataProvider* metadata) { @@ -149,8 +171,19 @@ namespace opensaml { } /** + * 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 NULL + */ + 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 */ void setRole(const xmltooling::QName* role) { @@ -160,7 +193,7 @@ namespace opensaml { /** * Sets a TrustEngine for the policy. - * + * * @param trust a TrustEngine or NULL */ void setTrustEngine(const xmltooling::TrustEngine* trust) { @@ -170,8 +203,8 @@ namespace opensaml { /** * 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. - * + * but can detect a much wider range of syntax errors. + * * @param validate validation setting */ void setValidating(bool validate=true) { @@ -180,17 +213,38 @@ namespace opensaml { /** * Sets flag controlling non-entity issuer support. - * - * @param entityOnly require that Issuer be in entity format + * + * @param entityOnly require that Issuer be in entity format */ void requireEntityIssuer(bool entityOnly=true) { m_entityOnly = entityOnly; } - + + /** + * Sets entityID of receiving entity. + * + * @param recipient the entityID of the peer processing the message + */ + void setRecipient(const XMLCh* recipient) { + m_recipient = recipient; + } + + /** + * 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) { + m_ts = ts; + } + /** * Evaluates the policy against the given request and message, * possibly populating message information in the policy object. - * + * * @param message the incoming message * @param request the protocol request * @@ -208,11 +262,21 @@ namespace opensaml { * * @param messageOnly true iff security and issuer state should be left in place */ - void reset(bool messageOnly=false); - + 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 _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 { @@ -221,7 +285,7 @@ namespace opensaml { /** * Returns the message timestamp as determined by the registered policies. - * + * * @return message timestamp as determined by the registered policies */ time_t getIssueInstant() const { @@ -230,7 +294,7 @@ namespace opensaml { /** * 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 { @@ -239,7 +303,7 @@ namespace opensaml { /** * 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 { @@ -248,8 +312,8 @@ namespace opensaml { /** * 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 + * + * @return true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated */ bool isAuthenticated() const { return m_authenticated; @@ -257,7 +321,7 @@ namespace opensaml { /** * Sets the message identifier as determined by the registered policies. - * + * * @param id message identifier */ void setMessageID(const XMLCh* id) { @@ -267,7 +331,7 @@ namespace opensaml { /** * Sets the message timestamp as determined by the registered policies. - * + * * @param issueInstant message timestamp */ void setIssueInstant(time_t issueInstant) { @@ -276,48 +340,48 @@ namespace opensaml { /** * Sets the issuer of the message as determined by the registered policies. - * + * * @param issuer issuer of the message */ 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) { m_authenticated = auth; } - + /** Allows override of rules for comparing saml2:Issuer information. */ class SAML_API IssuerMatchingPolicy { MAKE_NONCOPYABLE(IssuerMatchingPolicy); public: 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 @@ -326,11 +390,11 @@ namespace opensaml { /** * 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 @@ -340,7 +404,7 @@ namespace opensaml { /** * Returns the IssuerMatchingPolicy in effect. - * + * * @return the effective IssuerMatchingPolicy */ const IssuerMatchingPolicy& getIssuerMatchingPolicy() const { @@ -350,9 +414,9 @@ namespace opensaml { /** * 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) { @@ -364,14 +428,17 @@ namespace opensaml { /** 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 + // information extracted from message XMLCh* 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; @@ -380,6 +447,10 @@ namespace opensaml { const xmltooling::TrustEngine* m_trust; bool m_validate; bool m_entityOnly; + + // contextual information + const XMLCh* m_recipient; + time_t m_ts; }; };