opensaml-3.0.1

Classes | Public Member Functions | Protected Attributes | Static Protected Attributes | List of all members
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:
[legend]
Collaboration diagram for opensaml::SecurityPolicy:
[legend]

## 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)
| Constructor for policy. More...
const saml2md::MetadataProvider * | getMetadataProvider () const
| Returns the locked MetadataProvider supplied to the policy. More...
virtual saml2md::MetadataProvider::Criteria & | getMetadataProviderCriteria () 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...
std::vector< const SecurityPolicyRule * > & | getRules ()
| Gets a mutable array of installed policy rules. 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 | 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 IssuerMatchingPolicy & | getIssuerMatchingPolicy () const
| Returns the IssuerMatchingPolicy in effect. More...
void | setIssuerMatchingPolicy (IssuerMatchingPolicy *matchingPolicy)
| Sets the IssuerMatchingPolicy in effect. More...

## Protected Attributes
saml2md::MetadataProvider::Criteria * | m_metadataCriteria
| Manufactured MetadataProvider::Criteria instance.

## Static Protected Attributes
static IssuerMatchingPolicy | m_defaultMatching
| A shared matching object that just supports the default matching rules.

## 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`
| ) |  |

Constructor for policy.

Parameters

  metadataProvider | locked MetadataProvider instance
  role | identifies the role (generally IdP or SP) of the policy peer
  trustEngine | TrustEngine to authenticate policy peer
  validate | true iff XML parsing should be done with validation

## 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

  messageOnly | true 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

  message | the incoming message
  request | the protocol request

Exceptions

  BindingException | raised if the message/request is invalid according to the supplied rules

## ◆ getAudiences() [1/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

## ◆ getAudiences() [2/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

## ◆ getCorrelationID()

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

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

Returns
  correlated 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

## ◆ 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

  entityOnly | require 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

  messageOnly | true 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

  auth | indicates 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

  correlationID | correlated message identifier

## ◆ setIssueInstant()

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

Sets the message timestamp as determined by the registered policies.

Parameters

  issueInstant | message 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

  issuer | issuer 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

  issuer | issuer 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

  matchingPolicy | the IssuerMatchingPolicy to use

## ◆ setIssuerMetadata()

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

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

Parameters

  issuerRole | metadata 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

  id | message identifier

## ◆ setMetadataProvider()

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

Sets a locked MetadataProvider for the policy.

Parameters

  metadata | a 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

  criteria | a MetadataProvider::Criteria instance, or nullptr

## ◆ setRole()

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

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

Parameters

  role | the 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

  ts | the time at which the message is being processed

## ◆ setTrustEngine()

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

Sets a TrustEngine for the policy.

Parameters

  trust | a 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

  validate | validation setting

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

- saml/binding/SecurityPolicy.h