opensaml-3.2.1
opensaml::SecurityPolicy Class Reference

A policy used to verify the security of an incoming message. More...

#include <saml/binding/SecurityPolicy.h>

Inheritance diagram for opensaml::SecurityPolicy:
opensaml::saml2::SAML2AssertionPolicy

Classes

class  IssuerMatchingPolicy
 Allows override of rules for comparing saml2:Issuer information. More...
 

Public Member Functions

 SecurityPolicy (const saml2md::MetadataProvider *metadataProvider=0, const xmltooling::QName *role=0, const xmltooling::TrustEngine *trustEngine=0, bool validate=true, const char *profile=0)
 Constructor for policy. More...
 
const char * getProfile () const
 Returns the profile identifier associated with the transaction. More...
 
const saml2md::MetadataProvidergetMetadataProvider () const
 Returns the locked MetadataProvider supplied to the policy. More...
 
virtual saml2md::MetadataProvider::CriteriagetMetadataProviderCriteria () const
 Returns a reference to a MetadataProvider::Criteria instance suitable for use with the installed MetadataProvider. More...
 
const xmltooling::QName * getRole () const
 Returns the peer role element/type supplied to the policy. More...
 
const xmltooling::TrustEngine * getTrustEngine () const
 Returns the TrustEngine supplied to the policy. More...
 
bool getValidating () const
 Returns XML message validation setting. More...
 
bool requireEntityIssuer () const
 Returns flag controlling non-entity issuer support. More...
 
const std::vector< xmltooling::xstring > & getAudiences () const
 Returns the SAML audiences that represent the receiving peer. More...
 
std::vector< xmltooling::xstring > & getAudiences ()
 Returns the SAML audiences that represent the receiving peer. More...
 
time_t getTime () const
 Gets the effective time of message processing. More...
 
const XMLCh * getCorrelationID () const
 Returns the message identifier to which the message being evaluated is a response. More...
 
const XMLCh * getInResponseTo () const
 Returns the message identifier to which the message being evaluated claims to be a response. More...
 
std::vector< const SecurityPolicyRule * > & getRules ()
 Gets a mutable array of installed policy rules. More...
 
void setProfile (const char *id)
 Sets the profile identifier associated with the transaction. More...
 
void setMetadataProvider (const saml2md::MetadataProvider *metadata)
 Sets a locked MetadataProvider for the policy. More...
 
void setMetadataProviderCriteria (saml2md::MetadataProvider::Criteria *criteria)
 Sets a MetadataProvider::Criteria instance suitable for use with the installed MetadataProvider. More...
 
void setRole (const xmltooling::QName *role)
 Sets a peer role element/type for to the policy. More...
 
void setTrustEngine (const xmltooling::TrustEngine *trust)
 Sets a TrustEngine for the policy. More...
 
void setValidating (bool validate=true)
 Controls schema validation of incoming XML messages. More...
 
void requireEntityIssuer (bool entityOnly=true)
 Sets flag controlling non-entity issuer support. More...
 
void setTime (time_t ts)
 Sets effective time of message processing. More...
 
void setCorrelationID (const XMLCh *correlationID)
 Sets the message identifier to which the message being evaluated is a response. More...
 
void setInResponseTo (const XMLCh *id)
 Sets the message identifier to which the message being evaluated was responding (i.e., the value to be compared to the correlation ID). More...
 
void evaluate (const xmltooling::XMLObject &message, const xmltooling::GenericRequest *request=0)
 Evaluates the policy against the given request and message, possibly populating message information in the policy object. More...
 
virtual void reset (bool messageOnly=false)
 Resets the policy object and/or clears any per-message state. More...
 
void _reset (bool messageOnly=false)
 Resets the policy object and/or clears any per-message state for only this specific class. More...
 
const XMLCh * getMessageID () const
 Returns the message identifier as determined by the registered policies. More...
 
time_t getIssueInstant () const
 Returns the message timestamp as determined by the registered policies. More...
 
const saml2::Issuer * getIssuer () const
 Gets the issuer of the message as determined by the registered policies. More...
 
const saml2md::RoleDescriptor * getIssuerMetadata () const
 Gets the metadata for the role the issuer is operating in. More...
 
bool isAuthenticated () const
 Returns the authentication status of the message as determined by the registered policies. More...
 
void setMessageID (const XMLCh *id)
 Sets the message identifier as determined by the registered policies. More...
 
void setIssueInstant (time_t issueInstant)
 Sets the message timestamp as determined by the registered policies. More...
 
void setIssuer (const saml2::Issuer *issuer)
 Sets the issuer of the message as determined by the registered policies. More...
 
void setIssuer (const XMLCh *issuer)
 Sets the issuer of the message as determined by the registered policies. More...
 
void setIssuerMetadata (const saml2md::RoleDescriptor *issuerRole)
 Sets the metadata for the role the issuer is operating in. More...
 
void setAuthenticated (bool auth)
 Sets the authentication status of the message as determined by the registered policies. More...
 
const IssuerMatchingPolicygetIssuerMatchingPolicy () const
 Returns the IssuerMatchingPolicy in effect. More...
 
void setIssuerMatchingPolicy (IssuerMatchingPolicy *matchingPolicy)
 Sets the IssuerMatchingPolicy in effect. More...
 

Protected Attributes

saml2md::MetadataProvider::Criteriam_metadataCriteria
 Manufactured MetadataProvider::Criteria instance. More...
 

Static Protected Attributes

static IssuerMatchingPolicy m_defaultMatching
 A shared matching object that just supports the default matching rules. More...
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ SecurityPolicy()

opensaml::SecurityPolicy::SecurityPolicy ( const saml2md::MetadataProvider metadataProvider = 0,
const xmltooling::QName *  role = 0,
const xmltooling::TrustEngine *  trustEngine = 0,
bool  validate = true,
const char *  profile = 0 
)

Constructor for policy.

Parameters
metadataProviderlocked MetadataProvider instance
roleidentifies the role (generally IdP or SP) of the policy peer
trustEngineTrustEngine to authenticate policy peer
validatetrue iff XML parsing should be done with validation
profileprofile identifier

Member Function Documentation

◆ _reset()

void opensaml::SecurityPolicy::_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.

Parameters
messageOnlytrue iff security and issuer state should be left in place

◆ evaluate()

void opensaml::SecurityPolicy::evaluate ( const xmltooling::XMLObject &  message,
const xmltooling::GenericRequest *  request = 0 
)

Evaluates the policy against the given request and message, possibly populating message information in the policy object.

Parameters
messagethe incoming message
requestthe protocol request
Exceptions
BindingExceptionraised if the message/request is invalid according to the supplied rules

◆ getAudiences() [1/2]

const std::vector<xmltooling::xstring>& opensaml::SecurityPolicy::getAudiences ( ) const

Returns the SAML audiences that represent the receiving peer.

Returns
audience values of the peer processing the message

◆ getAudiences() [2/2]

std::vector<xmltooling::xstring>& opensaml::SecurityPolicy::getAudiences ( )

Returns the SAML audiences that represent the receiving peer.

Returns
audience values of the peer processing the message

◆ getCorrelationID()

const XMLCh* opensaml::SecurityPolicy::getCorrelationID ( ) const

Returns the message identifier to which the message being evaluated is a response.

Returns
correlated message identifier

◆ getInResponseTo()

const XMLCh* opensaml::SecurityPolicy::getInResponseTo ( ) const

Returns the message identifier to which the message being evaluated claims to be a response.

Returns
correlatable message identifier

◆ getIssueInstant()

time_t opensaml::SecurityPolicy::getIssueInstant ( ) const

Returns the message timestamp as determined by the registered policies.

Returns
message timestamp as determined by the registered policies

◆ getIssuer()

const saml2::Issuer* opensaml::SecurityPolicy::getIssuer ( ) const

Gets the issuer of the message as determined by the registered policies.

Returns
issuer of the message as determined by the registered policies

◆ getIssuerMatchingPolicy()

const IssuerMatchingPolicy& opensaml::SecurityPolicy::getIssuerMatchingPolicy ( ) const

Returns the IssuerMatchingPolicy in effect.

Returns
the effective IssuerMatchingPolicy

◆ getIssuerMetadata()

const saml2md::RoleDescriptor* opensaml::SecurityPolicy::getIssuerMetadata ( ) const

Gets the metadata for the role the issuer is operating in.

Returns
metadata for the role the issuer is operating in

◆ getMessageID()

const XMLCh* opensaml::SecurityPolicy::getMessageID ( ) const

Returns the message identifier as determined by the registered policies.

Returns
message identifier as determined by the registered policies

◆ getMetadataProvider()

const saml2md::MetadataProvider* opensaml::SecurityPolicy::getMetadataProvider ( ) const

Returns the locked MetadataProvider supplied to the policy.

Returns
the supplied MetadataProvider or nullptr

◆ getMetadataProviderCriteria()

virtual saml2md::MetadataProvider::Criteria& opensaml::SecurityPolicy::getMetadataProviderCriteria ( ) const
virtual

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.

Returns
reference to a MetadataProvider::Criteria instance

◆ getProfile()

const char* opensaml::SecurityPolicy::getProfile ( ) const

Returns the profile identifier associated with the transaction.

Returns
the profile identifier

◆ getRole()

const xmltooling::QName* opensaml::SecurityPolicy::getRole ( ) const

Returns the peer role element/type supplied to the policy.

Returns
the peer role element/type, or an empty QName

◆ getRules()

std::vector<const SecurityPolicyRule*>& opensaml::SecurityPolicy::getRules ( )

Gets a mutable array of installed policy rules.

If adding rules, their lifetime must be at least as long as the policy object.

Returns
mutable array of rules

◆ getTime()

time_t opensaml::SecurityPolicy::getTime ( ) const

Gets the effective time of message processing.

Returns
the time at which the message is being processed

◆ getTrustEngine()

const xmltooling::TrustEngine* opensaml::SecurityPolicy::getTrustEngine ( ) const

Returns the TrustEngine supplied to the policy.

Returns
the supplied TrustEngine or nullptr

◆ getValidating()

bool opensaml::SecurityPolicy::getValidating ( ) const

Returns XML message validation setting.

Returns
validation flag

◆ isAuthenticated()

bool opensaml::SecurityPolicy::isAuthenticated ( ) const

Returns the authentication status of the message as determined by the registered policies.

Returns
true iff a SecurityPolicyRule has indicated the issuer/message has been authenticated

◆ requireEntityIssuer() [1/2]

bool opensaml::SecurityPolicy::requireEntityIssuer ( ) const

Returns flag controlling non-entity issuer support.

Returns
flag controlling non-entity issuer support

◆ requireEntityIssuer() [2/2]

void opensaml::SecurityPolicy::requireEntityIssuer ( bool  entityOnly = true)

Sets flag controlling non-entity issuer support.

Parameters
entityOnlyrequire that Issuer be in entity format

◆ reset()

virtual void opensaml::SecurityPolicy::reset ( bool  messageOnly = false)
virtual

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.

Parameters
messageOnlytrue iff security and issuer state should be left in place

Reimplemented in opensaml::saml2::SAML2AssertionPolicy.

◆ setAuthenticated()

void opensaml::SecurityPolicy::setAuthenticated ( bool  auth)

Sets the authentication status of the message as determined by the registered policies.

Parameters
authindicates whether the issuer/message has been authenticated

◆ setCorrelationID()

void opensaml::SecurityPolicy::setCorrelationID ( const XMLCh *  correlationID)

Sets the message identifier to which the message being evaluated is a response.

Parameters
correlationIDcorrelated message identifier

◆ setInResponseTo()

void opensaml::SecurityPolicy::setInResponseTo ( const XMLCh *  id)

Sets the message identifier to which the message being evaluated was responding (i.e., the value to be compared to the correlation ID).

Parameters
idcorrelatable message identifier

◆ setIssueInstant()

void opensaml::SecurityPolicy::setIssueInstant ( time_t  issueInstant)

Sets the message timestamp as determined by the registered policies.

Parameters
issueInstantmessage timestamp

◆ setIssuer() [1/2]

void opensaml::SecurityPolicy::setIssuer ( const saml2::Issuer *  issuer)

Sets the issuer of the message as determined by the registered policies.

Parameters
issuerissuer of the message

◆ setIssuer() [2/2]

void opensaml::SecurityPolicy::setIssuer ( const XMLCh *  issuer)

Sets the issuer of the message as determined by the registered policies.

Parameters
issuerissuer of the message

◆ setIssuerMatchingPolicy()

void opensaml::SecurityPolicy::setIssuerMatchingPolicy ( IssuerMatchingPolicy matchingPolicy)

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.

Parameters
matchingPolicythe IssuerMatchingPolicy to use

◆ setIssuerMetadata()

void opensaml::SecurityPolicy::setIssuerMetadata ( const saml2md::RoleDescriptor *  issuerRole)

Sets the metadata for the role the issuer is operating in.

Parameters
issuerRolemetadata for the role the issuer is operating in

◆ setMessageID()

void opensaml::SecurityPolicy::setMessageID ( const XMLCh *  id)

Sets the message identifier as determined by the registered policies.

Parameters
idmessage identifier

◆ setMetadataProvider()

void opensaml::SecurityPolicy::setMetadataProvider ( const saml2md::MetadataProvider metadata)

Sets a locked MetadataProvider for the policy.

Parameters
metadataa locked MetadataProvider or nullptr

◆ setMetadataProviderCriteria()

void opensaml::SecurityPolicy::setMetadataProviderCriteria ( saml2md::MetadataProvider::Criteria criteria)

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.

Parameters
criteriaa MetadataProvider::Criteria instance, or nullptr

◆ setProfile()

void opensaml::SecurityPolicy::setProfile ( const char *  id)

Sets the profile identifier associated with the transaction.

Parameters
idthe profile identifier

◆ setRole()

void opensaml::SecurityPolicy::setRole ( const xmltooling::QName *  role)

Sets a peer role element/type for to the policy.

Parameters
rolethe peer role element/type or nullptr

◆ setTime()

void opensaml::SecurityPolicy::setTime ( time_t  ts)

Sets effective time of message processing.

Assumed to be the time of policy instantiation, can be adjusted to pre- or post-date message processing.

Parameters
tsthe time at which the message is being processed

◆ setTrustEngine()

void opensaml::SecurityPolicy::setTrustEngine ( const xmltooling::TrustEngine *  trust)

Sets a TrustEngine for the policy.

Parameters
trusta TrustEngine or nullptr

◆ setValidating()

void opensaml::SecurityPolicy::setValidating ( bool  validate = true)

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.

Parameters
validatevalidation setting

Member Data Documentation

◆ m_defaultMatching

IssuerMatchingPolicy opensaml::SecurityPolicy::m_defaultMatching
staticprotected

A shared matching object that just supports the default matching rules.

◆ m_metadataCriteria

saml2md::MetadataProvider::Criteria* opensaml::SecurityPolicy::m_metadataCriteria
mutableprotected

Manufactured MetadataProvider::Criteria instance.


The documentation for this class was generated from the following file: