IAIK High-Level API
version 1.1

iaik.hlapi
Class XMLSignerEncrypter

java.lang.Object
  extended by iaik.hlapi.SignerEncrypter
      extended by iaik.hlapi.XMLSignerEncrypter

public class XMLSignerEncrypter
extends SignerEncrypter

This SignerEncrypter implementation creates XML signatures.

It automatically adds the signing time and the certificate chain to the signature. Moreover, it selects a signature algorithm automatically depending on the given signature key. If the given key is a RSA key, it will select a suitable hash algorithm depending on the key length.

Using setIncludeSignedProperties(boolean), the application tell this object not to include any signature properties,. In this case, the resulting signature will not contain a dsig:Object for properties at all.

The output is a UTF-8 encoded XML signature. Per default, it creates enveloping XML signatures, i.e. signatures that contain the content data inside a dsig:Object element. To create detached XML signatures, the application can use setIncludeData(false). In addition, setting context namespaces using setContextNamespaces(Map) allows embedding of the resulting XML signature in an XML document without breaking the signature, i.e. making it an enveloped signature.

Detached XML signatures provide a higher performance than enveloping and enveloped signatures.

If the application does not specify a signing key, per default, this implementation will pass through the data unmodified. After calling setIncludeData(false), the result of SignerEncrypter.process(byte[]) and process(OutputStream) will be empty (but not null).


Constructor Summary
XMLSignerEncrypter()
          Construct a new XML signer/encrypter.
 
Method Summary
 void addRecipient(X509Certificate recipientCert)
          This method is unsupported and always throws a HlApiException.
 OutputStream process(OutputStream out)
          This implementation overwrites SignerEncrypter.process(OutputStream).
 void setContentType(String contentType)
          Set the media content type of the signed data, i.e. the data that the URI points to.
 void setContextNamespaces(Map namespaces)
          Set the namespace declarations that are visible in the context of the dsig:Signature element.
 void setExclusiveCanonicalization(boolean exclusiveCanonicalization)
          If the application sets this to true, the signature will use exclusive canonicalization (http://www.w3.org/2001/10/xml-exc-c14n#) in the CanonicalizationMethod element and as Transform in the reference to the SignedProperties.
 void setIncludeData(boolean includeData)
          Specify if the signed data is included in the result.
 void setIncludeSignedProperties(boolean includeProperties)
          Enable or disable including signed properties.
 void setReferenceTransformElements(String dsigTransformElements)
          Set optional dsig:Transform elements which should be included in the reference to the signed data.
 void setReferenceURI(String uri)
          Set the value of the URI parameter that points to the signed data.
 void setXAdESVersion(String version)
          Set the version string for the signed properties.
 
Methods inherited from class iaik.hlapi.SignerEncrypter
clearRecipients, dropSigningKey, process, setSigningKey
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLSignerEncrypter

public XMLSignerEncrypter()
Construct a new XML signer/encrypter.

Method Detail

addRecipient

public void addRecipient(X509Certificate recipientCert)
                  throws HlApiException
This method is unsupported and always throws a HlApiException.

Overrides:
addRecipient in class SignerEncrypter
Parameters:
recipientCert - The X.509 certificate of the recipient.
Throws:
HlApiException - If the certificate is invalid for encryption.
See Also:
SignerEncrypter.clearRecipients()

process

public OutputStream process(OutputStream out)
                     throws IOException,
                            HlApiException
This implementation overwrites SignerEncrypter.process(OutputStream).

If setIncludeData(boolean) is set to true, this method writes an enveloping signature containing the signed data within a dsig:Object inside the dsig:Signature. If setIncludeData(boolean) is set to false, it only writes the dsig:Signature to the output stream but not the signed data.

Specified by:
process in class SignerEncrypter
Parameters:
out - The stream which receives the signed and/or encrypted data.
Returns:
The OutputStream to which the application writes the data to be signed and/or encrypted.
Throws:
IOException - If writing to the given stream fails.
HlApiException - If signing fails.
Preconditions
(data != null)
Postconditions
(result != null)

setXAdESVersion

public void setXAdESVersion(String version)
                     throws HlApiException
Set the version string for the signed properties. The allowed version strings are: The default value is 1.3.2. Setting the XAdES version has an effect only if the signed properties are included (see setIncludeSignedProperties(boolean).

Parameters:
version - The version string.
Throws:
HlApiException - If the version is unsupported.
Preconditions
version != null

setReferenceURI

public void setReferenceURI(String uri)
Set the value of the URI parameter that points to the signed data. Note, that this class does not dereference this URI. The application has to provide this data to the process method. This class writes this URI into the resulting XML signature as it is.

Parameters:
uri - The URI that refers to the signed data.
Preconditions
(uri != null)

setContentType

public void setContentType(String contentType)
Set the media content type of the signed data, i.e. the data that the URI points to. This value is included in the signed properties of new signatures.

Per default, no content type is set (i.e. null).

Parameters:
contentType - The content type, e.g. text/xml. Set to null to use no content type.

setReferenceTransformElements

public void setReferenceTransformElements(String dsigTransformElements)
Set optional dsig:Transform elements which should be included in the reference to the signed data. This string must contain the the dsig:Transform elements in canonical form, but it must not contain the dsig:Transforms parent element! Note that the XML Signature namespace is already declared in this context with the prefix dsig.

For example:

 <dsig:Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
   <dsig:XPath>ancestor-or-self::Payload</ds:XPath> 
 </dsig:Transform>
 <dsig:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"> 
 </dsig:Transform>
 

Parameters:
dsigTransformElements - The (canonical) encoded Transform elements. Set the null to disable.

setContextNamespaces

public void setContextNamespaces(Map namespaces)
Set the namespace declarations that are visible in the context of the dsig:Signature element. This is useful if the application embeds the resulting signature in another XML document. The class uses these namespaces during the canonicalization steps. However, these namespaces will not appear in the resulting signature.

Setting context namespace nodes is not required if the signature uses exclusive canonical XML (see setExclusiveCanonicalization(boolean)).

The given map does not need to include the XML dsig and the ETSI namespace declarations. The signer class will include them automatically.

Parameters:
namespaces - The table that maps the prefix strings to the namespace URI strings. This parameter may be null.
See Also:
setExclusiveCanonicalization(boolean)

setExclusiveCanonicalization

public void setExclusiveCanonicalization(boolean exclusiveCanonicalization)
If the application sets this to true, the signature will use exclusive canonicalization (http://www.w3.org/2001/10/xml-exc-c14n#) in the CanonicalizationMethod element and as Transform in the reference to the SignedProperties. In this case, setting the context namespaces using setContextNamespaces(Map) is not required.

The default value is false.

Parameters:
exclusiveCanonicalization - true to use exclusive canonical XML false to use canonical XML.
See Also:
setContextNamespaces(Map)

setIncludeSignedProperties

public void setIncludeSignedProperties(boolean includeProperties)
Enable or disable including signed properties.

Per default, signed properties are included.

Parameters:
includeProperties - true to include signed properties.

setIncludeData

public void setIncludeData(boolean includeData)
Specify if the signed data is included in the result. Default is true (included).

Parameters:
includeData - true to include data, false to exclude it.

IAIK High-Level API
version 1.1

Copyright © 2007, IAIK, Graz University of Technology
Copyright © 2007, Stiftung SIC