net.shibboleth.tool.xmlsectool

Class XMLSecTool

java.lang.Object

net.shibboleth.tool.xmlsectool.XMLSecTool

public final class XMLSecTool
extends Object

A command line tool for checking an XML file for well-formedness and validity as well as signing and checking signatures.

Field Summary

Fields

Modifier and Type	Field and Description
private static Logger	log Class logger.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	XMLSecTool() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	addSignatureELement(CommandLineArguments cli, Element root, Element signature) Adds the signature element at the appropriate place in the document.
protected static String	determineSignatureAlgorithm(CommandLineArguments cli, org.opensaml.security.x509.X509Credential signingCredential) Determine the signature algorithm to use.
protected static Reference	extractReference(XMLSignature signature) Extract the reference within the provided XML signature while ensuring that there is only one such reference.
protected static org.opensaml.security.x509.X509Credential	getCredential(CommandLineArguments cli) Gets the credentials used for signing and signature verification.
protected static Collection<X509CRL>	getCRLs(CommandLineArguments cli) Gets the CRLs referenced on the command line, if any.
protected static DocumentBuilder	getParser() Constructs a DOM parser used to parse the input XML.
protected static Element	getSignatureElement(Document xmlDoc) Gets the signature element from the document.
protected static String	getSignatureReferenceUri(CommandLineArguments cli, Element rootElement) Gets the reference of the URI to use for the signature.
protected static InputStream	getXmlInputStreamFromFile(CommandLineArguments cli) Creates an input stream that reads the input XML from a file.
protected static InputStream	getXmlInputStreamFromUrl(CommandLineArguments cli) Creates an input stream that reads the input XML from an HTTP URL.
protected static void	initLogging(CommandLineArguments cli) Initialize the logging subsystem.
static void	main(String[] args) Main command-line entry point.
protected static void	markIdAttribute(Element docElement, Reference reference) Reconcile the given reference with the document element, by making sure that the appropriate attribute is marked as an ID attribute.
protected static Document	parseXML(CommandLineArguments cli) Parses the input XML from its source and converts it to a DOM document.
protected static void	populateKeyInfo(Document doc, KeyInfo keyInfo, org.opensaml.security.x509.X509Credential credential) Populates an XML signature's KeyInfo with X.509 credential information.
protected static void	schemaValidate(CommandLineArguments cli, Document xml) Validates the document against the schema source indicated by the CLI arguments.
protected static void	sign(CommandLineArguments cli, org.opensaml.security.x509.X509Credential signingCredential, Document xml) Signs a document.
protected static void	validateSignatureReference(Document xmlDocument, Reference ref) Validates the reference within the XML signature by performing the following checks.
protected static void	validateSignatureReferenceUri(Document xmlDocument, Reference reference) Validates that the element resolved by the signature validation layer is the same as the element resolved by the DOM layer.
protected static void	validateSignatureTransforms(Reference reference) Validate the transforms included in the Signature Reference.
protected static void	verifySignature(CommandLineArguments cli, org.opensaml.security.x509.X509Credential credential, Document xmlDocument) Verifies that the signature on a document is valid.
protected static void	writeDocument(CommandLineArguments cli, Node xml) Writes a DOM element to the output file.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static Logger log

Class logger.

Constructor Detail

XMLSecTool

private XMLSecTool()

Constructor.

Method Detail

main

public static void main(String[] args)

Main command-line entry point.

Parameters:

args - command-line arguments

parseXML

protected static Document parseXML(CommandLineArguments cli)

Parses the input XML from its source and converts it to a DOM document.

Parameters:

cli - command line arguments

Returns:

the parsed DOM document

getXmlInputStreamFromFile

protected static InputStream getXmlInputStreamFromFile(CommandLineArguments cli)

Creates an input stream that reads the input XML from a file.

Parameters:

cli - command line arguments

Returns:

XML input stream

getXmlInputStreamFromUrl

protected static InputStream getXmlInputStreamFromUrl(CommandLineArguments cli)

Creates an input stream that reads the input XML from an HTTP URL.

Parameters:

cli - command line arguments

Returns:

XML input stream

getParser

protected static DocumentBuilder getParser()

Constructs a DOM parser used to parse the input XML.

Returns:

the DOM parser

schemaValidate

protected static void schemaValidate(CommandLineArguments cli,
                  Document xml)

Validates the document against the schema source indicated by the CLI arguments.

Parameters:

cli - command line arguments

xml - document to validate

sign

protected static void sign(@Nonnull
        CommandLineArguments cli,
        @Nonnull
        org.opensaml.security.x509.X509Credential signingCredential,
        @Nonnull
        Document xml)

Signs a document.

Parameters:

cli - command line arguments

signingCredential - credential to use for signing

xml - document to be signed

determineSignatureAlgorithm

protected static String determineSignatureAlgorithm(@Nonnull
                                 CommandLineArguments cli,
                                 @Nonnull
                                 org.opensaml.security.x509.X509Credential signingCredential)

Determine the signature algorithm to use.

• if the CLI signatureAlgorithm has been used, it takes precedence.
• for RSA or ECDSA credentials, use an algorithm dependent on the digest algorithm chosen
• for DSA, always use DSA + SHA-1

Parameters:

cli - command line arguments

signingCredential - credential to use for signing

Returns:

algorithm URI as a String

populateKeyInfo

protected static void populateKeyInfo(Document doc,
                   KeyInfo keyInfo,
                   org.opensaml.security.x509.X509Credential credential)

Populates an XML signature's KeyInfo with X.509 credential information.

Parameters:

doc - XML document in which the elements will be rooted

keyInfo - the KeyInfo to be populated

credential - the credential

getSignatureReferenceUri

protected static String getSignatureReferenceUri(CommandLineArguments cli,
                              Element rootElement)

Gets the reference of the URI to use for the signature. If a reference attribute name is given, is present on the document root element, and contains a value, that value is used. Otherwise an empty string is used.

Parameters:

cli - command line arguments

rootElement - document root element

Returns:

the signature reference URI, never null

addSignatureELement

protected static void addSignatureELement(CommandLineArguments cli,
                       Element root,
                       Element signature)

Adds the signature element at the appropriate place in the document.

Parameters:

cli - command line argument

root - element to which the signature will be added as a child

signature - signature to be added to the document's root element

markIdAttribute

protected static void markIdAttribute(Element docElement,
                   Reference reference)

Reconcile the given reference with the document element, by making sure that the appropriate attribute is marked as an ID attribute.

Parameters:

docElement - document element whose appropriate attribute should be marked

reference - reference which references the document element

verifySignature

protected static void verifySignature(CommandLineArguments cli,
                   @Nonnull
                   org.opensaml.security.x509.X509Credential credential,
                   Document xmlDocument)

Verifies that the signature on a document is valid.

Parameters:

cli - command line argument

credential - credential to use for validation

xmlDocument - document whose signature will be validated

extractReference

protected static Reference extractReference(XMLSignature signature)

Extract the reference within the provided XML signature while ensuring that there is only one such reference.

Parameters:

signature - signature to extract the reference from

Returns:

the extracted reference

validateSignatureReference

protected static void validateSignatureReference(Document xmlDocument,
                              Reference ref)

Validates the reference within the XML signature by performing the following checks.

• check that the XML signature layer resolves that reference to the same element as the DOM layer does
• check that only enveloped and, optionally, exclusive canonicalization transforms are used

Parameters:

xmlDocument - current XML document

ref - reference to be verified

validateSignatureReferenceUri

protected static void validateSignatureReferenceUri(Document xmlDocument,
                                 Reference reference)

Validates that the element resolved by the signature validation layer is the same as the element resolved by the DOM layer.

Parameters:

xmlDocument - the signed document

reference - the reference to be validated

validateSignatureTransforms

protected static void validateSignatureTransforms(Reference reference)

Validate the transforms included in the Signature Reference. The Reference may contain at most 2 transforms. One of them must be the Enveloped signature transform. An Exclusive Canonicalization transform (with or without comments) may also be present. No other transforms are allowed.

Parameters:

reference - the Signature reference containing the transforms to evaluate

getSignatureElement

protected static Element getSignatureElement(Document xmlDoc)

Gets the signature element from the document. The signature must be a child of the document root.

Parameters:

xmlDoc - document from which to pull the signature

Returns:

the signature element, or null

getCredential

protected static org.opensaml.security.x509.X509Credential getCredential(CommandLineArguments cli)

Gets the credentials used for signing and signature verification.

Parameters:

cli - command line arguments

Returns:

the credentials

getCRLs

protected static Collection<X509CRL> getCRLs(CommandLineArguments cli)

Gets the CRLs referenced on the command line, if any.

Parameters:

cli - command line arguments

Returns:

collection of CRLs

writeDocument

protected static void writeDocument(CommandLineArguments cli,
                 Node xml)

Writes a DOM element to the output file.

Parameters:

cli - command line arguments

xml - the XML element to output

initLogging

protected static void initLogging(CommandLineArguments cli)

Initialize the logging subsystem.

Parameters:

cli - command line arguments