uk.ac.soton.itinnovation.grid.types
Class MatchRule

java.lang.Object
  uk.ac.soton.itinnovation.grid.types.MatchRule

All Implemented Interfaces:

Comparable

public class MatchRule
extends Object
implements Comparable

A rule used in determining whether a user has a process role.

When determining whether a SOAP operation should be permitted, the PBAC PDP must first find the set of process roles which the caller has in the context of the resource. This is done by evaluating each of the resource's MatchRules.

There are various different types of MatchRule, although all are handled by this single class, rather than with subclasses:

World matches match anyone at all.

Wildcarded issuer matches match anyone whose identity is vouched for by a particular CA. This could be used to ensure that people can't open new accounts under bogus names, for example.

Specific subject matches only match someone with that exact distinguished name (DN), signed by a given CA. Note that only the distinguished name is taken from the user's certificate, not their public key. If the user generates a new key they can still get the role, provided it has the same DN and is signed by the same issuer. This allows the use of short-lived X.509 user certificates.

Group matches match anyone who is a member of the specified group. Each group is itself a resource, and has its own set of match rules to determine who is a member. See GroupUtils for more details about groups.

SAML attribute matches match anyone who presents a SAML assertion signed by a given authority, stating that they have the specified attribute.

Note: MatchRule is being phased out and replaced by the MatchPattern and PolicyRule classes.

Constructor Summary

MatchRule()
Create an empty match rule.

MatchRule(MatchPattern pattern, String processRole, boolean deny)
Create a rule from a pattern.

MatchRule(MatchRule rule)
Create a rule based on an existing one.

MatchRule(PolicyRule rule)

MatchRule(String memberOfGroup, String processRole, boolean deny)
Group membership rule.

MatchRule(String attributeName, String attributeValue, X509Certificate authority, String processRole, boolean deny)
Full constructor that allows setting all values for a SAML attribute.

MatchRule(String subjectDN, X509Certificate authority, String processRole, boolean deny)
Full constructor that allows setting all values for an X.509 match.

MatchRule(SubjectDescription subject, SubjectDescription authority, String processRole)
Convenience constructor that extracts the subject DN from 'subject', and the issuer certificate from 'authority'.

Method Summary

void	checkRole(String role) Check that the role is correct.
void	checkValid() Ensure that all required fields are set, and no fields conflict.
int	compareTo(Object otherObj) Used to ensure a stable sort order for display.
static MatchRule	createAnyoneRule(String processRole) Create a rule that will give anyone at all this role.
MatchPattern	extractMatchPattern() Return the pattern component of this rule.
String	getAttributeName() Get SAML attribute name.
String	getAttributeValue() Get SAML attribute value.
boolean	getDeny()
String	getIssuerCertificate() Get a serialised form of the issuer's certificate, or null if there isn't one.
String	getMemberOfGroup()
String	getProcessRole()
String	getSubjectDN()
static TypeDesc	getTypeDesc() Return type metadata object for Axis serialisation.
X509Certificate	parseIssuerCertificate() Decode the issuerCertificate into an X509Certificate.
void	setAttributeName(String value) Set required SAML attribute name (for SAML match rules).
void	setAttributeValue(String value) Set required SAML attribute value (for SAML match rules).
void	setDeny(boolean deny)
void	setIssuerCertificate(String issuerCertificate)
void	setMemberOfGroup(String memberOfGroup) For group rules: set the group of which the subject must be a member.
void	setProcessRole(String processRole)
void	setSubjectDN(String subjectDN)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MatchRule

public MatchRule()

Create an empty match rule. This is mainly useful for systems which populate the object using the setters (e.g., hibernate or Axis deserialisers).

MatchRule

public MatchRule(PolicyRule rule)

MatchRule

public MatchRule(MatchRule rule)
          throws InvalidMatchRuleException

Create a rule based on an existing one. Mainly used by the internal SavedMatchRule class.

Throws:

InvalidMatchRuleException

MatchRule

public MatchRule(SubjectDescription subject,
                 SubjectDescription authority,
                 String processRole)

Convenience constructor that extracts the subject DN from 'subject', and the issuer certificate from 'authority'.

Parameters:

subject - subject containing the DN to extract

authority - authority containing the X.509 certificate to extract

processRole - the role which should be granted to the subject

MatchRule

public MatchRule(String subjectDN,
                 X509Certificate authority,
                 String processRole,
                 boolean deny)

Full constructor that allows setting all values for an X.509 match.

Parameters:

subjectDN - the client certificate's subject DN must match this string.

authority - the client certificate must be signed by this certificate's public key.

processRole - the role to grant (or deny) if the rule matches.

deny - if true, matching this rule denies access.

MatchRule

public MatchRule(String attributeName,
                 String attributeValue,
                 X509Certificate authority,
                 String processRole,
                 boolean deny)

Full constructor that allows setting all values for a SAML attribute.

Parameters:

attributeName - the name of the SAML attribute

attributeValue - the value of the SAML attribute

authority - the assertion must be signed by this certificate's public key; use null to match only trusted attributes (verified outside of PBAC)

processRole - the role to grant (or deny) if the rule matches.

deny - if true, matching this rule denies access.

MatchRule

public MatchRule(String memberOfGroup,
                 String processRole,
                 boolean deny)

Group membership rule.

Parameters:

memberOfGroup - the group resource in which users must have PDP.GROUP_MEMBER_ROLE.

processRole - the role to grant (or deny) if the rule matches.

deny - if true, matching this rule denies access.

MatchRule

public MatchRule(MatchPattern pattern,
                 String processRole,
                 boolean deny)

Create a rule from a pattern.

Parameters:

pattern - the pattern which must match for this rule to be used

processRole - the role which this pattern affects

deny - if true, matching this rule denies access Note that this constructor takes a reference to the pattern rather than making a copy.

Method Detail

createAnyoneRule

public static MatchRule createAnyoneRule(String processRole)

Create a rule that will give anyone at all this role. This is not a constructor because there are too many of them and it's getting confusing.

Parameters:

processRole - the role that anyone will get

Returns:

the new rule

extractMatchPattern

public MatchPattern extractMatchPattern()

Return the pattern component of this rule. Not called getMatchPattern so that Axis doesn't serialise it.

getIssuerCertificate

public String getIssuerCertificate()

Get a serialised form of the issuer's certificate, or null if there isn't one.

See Also:

parseIssuerCertificate()

setIssuerCertificate

public void setIssuerCertificate(String issuerCertificate)

setSubjectDN

public void setSubjectDN(String subjectDN)

getSubjectDN

public String getSubjectDN()

setAttributeName

public void setAttributeName(String value)

Set required SAML attribute name (for SAML match rules).

setAttributeValue

public void setAttributeValue(String value)

Set required SAML attribute value (for SAML match rules).

getAttributeName

public String getAttributeName()

Get SAML attribute name.

getAttributeValue

public String getAttributeValue()

Get SAML attribute value.

setMemberOfGroup

public void setMemberOfGroup(String memberOfGroup)

For group rules: set the group of which the subject must be a member.

getMemberOfGroup

public String getMemberOfGroup()

setDeny

public void setDeny(boolean deny)

getDeny

public boolean getDeny()

setProcessRole

public void setProcessRole(String processRole)

getProcessRole

public String getProcessRole()

toString

public String toString()

Overrides:

toString in class Object

checkValid

public void checkValid()
                throws InvalidMatchRuleException

Ensure that all required fields are set, and no fields conflict.

Throws:

InvalidMatchRuleException

checkRole

public void checkRole(String role)
               throws GridFailureException

Check that the role is correct.

Parameters:

role - the required role

Throws:

GridFailureException - if the rule's role is not set or is different to 'role'

getTypeDesc

public static TypeDesc getTypeDesc()

Return type metadata object for Axis serialisation.

parseIssuerCertificate

public X509Certificate parseIssuerCertificate()

Decode the issuerCertificate into an X509Certificate.

Returns:

the X.509 certificate of the authority

Throws:

RuntimeException - if no certificate is set, or if the certificate cannot be decoded

compareTo

public int compareTo(Object otherObj)

Used to ensure a stable sort order for display.

Specified by:

compareTo in interface Comparable