org.globus.gridshib.security.x509
Class SAMLX509Extension

java.lang.Object
  org.globus.gsi.X509Extension
      org.globus.gridshib.security.x509.X509Extension
          org.globus.gridshib.security.x509.NonCriticalX509Extension
              org.globus.gridshib.security.x509.SAMLX509Extension

public final class SAMLX509Extension
extends NonCriticalX509Extension

The SAML X.509 extension is a non-critical X.509 extension containing a SAML V1.1 subject-based assertion.

According to RFC 3280, an X.509 v3 certificate extension consists of an OID, a boolean flag indicating whether or not the extension is critical, and a DER-encoded extension value:

Extension  ::=  SEQUENCE  {
    extnID      OBJECT IDENTIFIER,
    critical    BOOLEAN DEFAULT FALSE,
    extnValue   OCTET STRING
}

In the case of the SAML X.509 Extension, the OID is

1.3.6.1.4.1.3536.1.1.1.12

and the criticality is FALSE. Moreover, the extension value has the following ASN.1 structure:

SAMLAssertion  ::=  UTF8String (SIZE (1..MAX))

that is, the extension type is defined to be a DER-encoded UTF8 string.

For backward compatibility, the static methods of this class distinguish between the standard SAML X.509 Extension (represented by a SAMLX509Extension instance) and the legacy SAML X.509 Extension.

See Also:

NonCriticalX509Extension

Field Summary

static String	LEGACY_OID The OID of the legacy SAML X.509 Extension.
static String	OID The OID of the standard SAML X.509 Extension.

Fields inherited from class org.globus.gridshib.security.x509.NonCriticalX509Extension

CRITICAL

Fields inherited from class org.globus.gsi.X509Extension

critical, oid, value

Constructor Summary

SAMLX509Extension()
Deprecated. This constructor will be removed in the next version of the GridShib Security Framework. Use SAMLX509Extension(SAMLAssertion) instead.

SAMLX509Extension(SAMLAssertion assertion)
Creates an instance of SAMLX509Extension with the appropriate OID and criticality.

Method Summary

static byte[]	getExtensionValue(X509Certificate cert) Gets the value of the standard SAML X.509 Extension for the given certificate.
static byte[]	getLegacyExtensionValue(X509Certificate cert) Gets the value of the legacy SAML X.509 Extension for the given certificate.
static SAMLSubjectAssertion	getSAMLAssertion(X509Certificate cert) Gets the certificate extension value from the given certificate and attempts to parse it as a SAML assertion.
static boolean	hasSAMLExtension(X509Certificate cert) Determines if the given certificate contains a non-critical X.509 extension at the appropriate OID.
void	setOid(String oid) This method does nothing.

Methods inherited from class org.globus.gridshib.security.x509.NonCriticalX509Extension

setCritical

Methods inherited from class org.globus.gridshib.security.x509.X509Extension

encodeDERUTF8String, hasCriticalExtension, hasNonCriticalExtension, printValue, writeValueToFile, writeValueToFile

Methods inherited from class org.globus.gsi.X509Extension

getExtensionValue, getOid, getValue, isCritical, setValue

Methods inherited from class java.lang.Object

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

Field Detail

OID

public static final String OID

The OID of the standard SAML X.509 Extension. All instances of SAMLX509Extension are associated with this OID.

Since:

0.3.0

See Also:

Constant Field Values

LEGACY_OID

public static final String LEGACY_OID

The OID of the legacy SAML X.509 Extension.

Since:

0.3.0

See Also:

Constant Field Values

Constructor Detail

SAMLX509Extension

public SAMLX509Extension()

Deprecated. This constructor will be removed in the next version of the GridShib Security Framework. Use SAMLX509Extension(SAMLAssertion) instead.

Creates an instance of SAMLX509Extension with the appropriate OID and criticality.

The initial value of an instance created with this constructor is null. Call the X509Extension.setValue(byte[]) method of the superclass to set the value of this extension.

SAMLX509Extension

public SAMLX509Extension(SAMLAssertion assertion)
                  throws IOException

Creates an instance of SAMLX509Extension with the appropriate OID and criticality. Encodes the given SAML assertion as a DER-encoded UTF8 string.

This constructor takes an ordinary SAMLAssertion instance and creates a SAML X.509 Extension. If the extension is to be consumed by the GridShib Security Framework (i.e., this code library), the assertion MUST be a SAMLSubjectAssertion instance.

Parameters:

assertion - the SAML assertion to bind to this SAMLX509Extension instance

Throws:

IOException

Method Detail

setOid

public void setOid(String oid)

This method does nothing. It simply preserves the OID of this SAMLX509Extension instance.

Overrides:

setOid in class X509Extension

getExtensionValue

public static byte[] getExtensionValue(X509Certificate cert)
                                throws IOException

Gets the value of the standard SAML X.509 Extension for the given certificate.

Note: Prior to 0.3.0, this method returned the value of the legacy SAML X.509 Extension. In that sense, this method is new in 0.3.0.

Parameters:

cert - a certificate with a bound SAML assertion

Returns:

the DER-encoded octet string for the extension value (which may be null if the certificate does not contain a standard SAML X.509 Extension)

Throws:

IOException - If unable to get the extension value

See Also:

X509Extension.getExtensionValue(X509Certificate, String)

getLegacyExtensionValue

public static byte[] getLegacyExtensionValue(X509Certificate cert)
                                      throws IOException

Gets the value of the legacy SAML X.509 Extension for the given certificate.

Parameters:

cert - a certificate with a bound SAML assertion

Returns:

the DER-encoded octet string for the legacy extension value (which may be null if the certificate does not contain a legacy SAML X.509 Extension)

Throws:

IOException - If unable to get the extension value

Since:

0.3.0

See Also:

X509Extension.getExtensionValue(X509Certificate, String)

getSAMLAssertion

public static SAMLSubjectAssertion getSAMLAssertion(X509Certificate cert)
                                             throws IOException,
                                                    SAMLException

Gets the certificate extension value from the given certificate and attempts to parse it as a SAML assertion. If the extension does not exist, this method returns null.

This method first checks for a non-critical extension at OID. If the standard extension does not exist, it then checks for a non-critical extension at LEGACY_OID. If the legacy extension does not exist either, this method returns null.

Parameters:

cert - an X.509 certificate that may or may not contain an embedded SAML assertion

Returns:

a SAML subject assertion (or null if the given certificate does not contain an embedded SAML assertion)

Throws:

IOException - If unable to decode the certificate extension

SAMLException - If unable to parse the SAML assertion

Since:

0.3.0

hasSAMLExtension

public static boolean hasSAMLExtension(X509Certificate cert)

Determines if the given certificate contains a non-critical X.509 extension at the appropriate OID. If the certificate is not a v3 certificate, this method short-circuits and returns false.

For backward compatibility, this method checks for a non-critical extension at both LEGACY_OID and OID.

Parameters:

cert - a non-null X509Certificate instance

Returns:

true if and only if the given certificate has a non-critical X.509 extension at OID or LEGACY_OID

Since:

0.3.0

See Also:

X509Extension.hasNonCriticalExtension(X509Certificate, String)