com.rsa.swsj.signature
Class XMLSignature

java.lang.Object
  com.rsa.swsj.XMLSecurityOperation
      com.rsa.swsj.signature.XMLSignature

public final class XMLSignature

extends XMLSecurityOperation

This class builds and stores XML Signatures. XML Signatures are applied to arbitrary digital content data (data objects) via an indirection. Data objects are digested; the resulting value is placed in an element and that element is then digested and cryptographically signed. Enveloped or enveloping signatures are over data within the same XML document as the signature. Detached signatures are over data external to the signature element. XML digital signatures are represented by the Signature element which has the following structure.The following conventions are used:

• "?"
denotes zero or one occurrence
• "+"
denotes one or more occurrences
• "*"
denotes zero or more occurrences

 <Signature ID?>                                        
    <SignedInfo>
      <CanonicalizationMethod/>
      <SignatureMethod/>
     (<Reference URI? >
       (<Transforms>)?
       <DigestMethod>
         <DigestValue>
       </Reference>)+
    </SignedInfo>
    <SignatureValue> 
    (<KeyInfo>)?
    (<Object ID?>)*
 </Signature>

Field Summary
static java.lang.String	ALG_SIGNATURE_DSA_SHA1 Specifies the DSA signature algorithm.
static java.lang.String	ALG_SIGNATURE_HMAC_SHA1 Specifies that the MAC algorithm HMAC-SHA1 is used in XML Signature.
static java.lang.String	ALG_SIGNATURE_RSA_SHA1 Specifies the RSA signature algorithm.
static int	DETACHED Specifies that the signature is detached.
static int	ENVELOPED Specifies that the signature is enveloped.
static int	ENVELOPING Specifies that the signature is enveloping.

 

Constructor Summary

XMLSignature(SWSJContext context) Creates an empty XMLSignature object initialized only with a context.

XMLSignature(SWSJContext context, java.lang.String reference, java.security.PrivateKey privKey, java.security.cert.X509Certificate cert, java.security.cert.X509Certificate[] certChain) Creates XMLSignature object set with all nessesary values.

 

Method Summary
void	addManifest(java.lang.String id, SigReference[] references) Adds a manifest to the message and sets the references within that manifest.
void	addReference(Reference reference) Adds a SigReference.
java.lang.String	getCanonicalizationMethod() Gets the canonicalization method.
int	getHMACOutputLen() Gets the HMAC output length, in bits, as an integer.
char[]	getHMACPassword() Gets the HMAC password used for signing and verification.
java.lang.String	getSignatureMethod() Gets the signature method.
byte[]	getSignatureValue() Gets the signature value as a byte array.
int	getType() Gets the signature type as an integer value.
void	removeSignatureProperties() Removes all the signature properties associated with this signature; if this method is called, <SignatureProperty> element that holds the signing time will not be created for this signature.
void	setCanonicalizationMethod(java.lang.String c14nMethod) Sets the canonicalization method to c14nMethod.
void	setCertificates(java.security.cert.X509Certificate[] certificates) Sets the array of known certificates to use when attempting to verify a signature.
void	setHMACOutputLen(int length) Sets the HMAC output length, in bits, to the given value.
void	setHMACPassword(char[] password) Sets the HMAC password to use for signing and verification.
void	setPrivateKey(java.security.PrivateKey privKey) Sets the private key to use when signing.
void	setPublicKeys(java.security.PublicKey[] pubKeys) Sets the array of known public keys to use when attempting to verifiy a signature.
void	setReferences(Reference[] references) Sets the array of references.
void	setType(int type) Sets the signature type to type.

 

Methods inherited from class com.rsa.swsj.XMLSecurityOperation

getContext, getId, getNamespacePrefix, getOutputStream, getParameters, getReferences, getStatusInfo, getTimestamp, setExpirationTime, setId, setLocation, setNamespacePrefix, setOutputStream, setParameters, skip

 

Methods inherited from class java.lang.Object

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

 

Field Detail

DETACHED

public static final int DETACHED

Specifies that the signature is detached. The signature is over content external to the signature element.

See Also:

Constant Field Values

ENVELOPING

public static final int ENVELOPING

Specifies that the signature is enveloping. The signature is over content found within an Object element of the signature itself.

See Also:

Constant Field Values

ENVELOPED

public static final int ENVELOPED

Specifies that the signature is enveloped. The signature is over XML content that contains the signature as an element.

See Also:

Constant Field Values

ALG_SIGNATURE_HMAC_SHA1

public static final java.lang.String ALG_SIGNATURE_HMAC_SHA1

Specifies that the MAC algorithm HMAC-SHA1 is used in XML Signature.

ALG_SIGNATURE_DSA_SHA1

public static final java.lang.String ALG_SIGNATURE_DSA_SHA1

Specifies the DSA signature algorithm. It is required by the XML signature specification.

ALG_SIGNATURE_RSA_SHA1

public static final java.lang.String ALG_SIGNATURE_RSA_SHA1

Specifies the RSA signature algorithm. It is recommended by the XML signature specification.

XMLSignature

public XMLSignature(SWSJContext context)
             throws InvalidParameterException

Creates an empty XMLSignature object initialized only with a context. This constructor is the default constructor.

Parameters:

context - An object that collects a number of common parameters and state variables; for example, JCE provider.

Throws:

InvalidParameterException - If context is invalid.

XMLSignature

public XMLSignature(SWSJContext context,
                    java.lang.String reference,
                    java.security.PrivateKey privKey,
                    java.security.cert.X509Certificate cert,
                    java.security.cert.X509Certificate[] certChain)
             throws InvalidParameterException

Creates XMLSignature object set with all nessesary values. Use this constructor in simple cases.

Parameters:

context - An object that collects a number of common parameters and state variables; for example, JCE provider.

reference - The data to sign. By default no transform is provided.

privKey - The private key to use for signing.

cert - A certificate containing the public key to verify the signature. If null is passed, public key must be passed later; otherwise, KeyInfo X509Data will be created.

certChain - The list of certificates used to verify the cert. If null is passed, the certificates must be passed later or invoke context.setCertValidator(null) explicitly to skip the validation of the cert; otherwise, the passed certificates are added to KeyInfo.

Throws:

InvalidParameterException - If an invalid value is set.

setType

public void setType(int type)
             throws InvalidParameterException

Sets the signature type to type.

Call this method only when signing the document.

Specified by:

setType in class XMLSecurityOperation

Parameters:

type - An integer containing the value of the signature type, defined in this class. The signature can be described as detached, enveloping, or enveloped.

Throws:

InvalidParameterException - If type is invalid.

getType

public int getType()

Gets the signature type as an integer value.

Specified by:

getType in class XMLSecurityOperation

Returns:

The integer value of the signature type.

setHMACOutputLen

public void setHMACOutputLen(int length)

Sets the HMAC output length, in bits, to the given value. HMAC output length is optional. The length should be a positive integer, a multiple of 8, and should not be larger than 160. This method should be called before HMAC signing.

Parameters:

length - The integer value of the required HMAC output length, in bits.

getHMACOutputLen

public int getHMACOutputLen()

Gets the HMAC output length, in bits, as an integer. If the HMAC output length is not set, 0 is returned.

Returns:

The HMAC output length, in bits, as an integer.

getSignatureMethod

public java.lang.String getSignatureMethod()

Gets the signature method.

Returns:

The signature algorithm name as a String.

setCanonicalizationMethod

public void setCanonicalizationMethod(java.lang.String c14nMethod)
                               throws InvalidParameterException

Sets the canonicalization method to c14nMethod.

Parameters:

c14nMethod - The required element as a String defined in the Reference class that specifies the canonicalization algorithm applied to the SignedInfo element prior to signature calculations.

Throws:

InvalidParameterException - If c14nMethod is invalid.

getCanonicalizationMethod

public java.lang.String getCanonicalizationMethod()

Gets the canonicalization method.

Returns:

The canonicalization algorithm as a String that is defined in the Reference class.

getSignatureValue

public byte[] getSignatureValue()

Gets the signature value as a byte array.

Returns:

The signatureValue of this XMLSignature as a byte array.

addManifest

public void addManifest(java.lang.String id,
                        SigReference[] references)
                 throws InvalidParameterException

Adds a manifest to the message and sets the references within that manifest. This API also adds a reference to the signature that points to new manifest.

Parameters:

id - An identifier for the new manifest.

references - An array of signature references to set.

Throws:

InvalidParameterException - If any parameter is invalid.

setHMACPassword

public void setHMACPassword(char[] password)
                     throws InvalidParameterException

Sets the HMAC password to use for signing and verification.

In case of WSSDocument objects, if a UsernameToken object is set in the WSSParameters the password set in that UsernameToken object will be used as the HMAC password.

Parameters:

password - The HMAC Password.

Throws:

InvalidParameterException - If password is invalid.

getHMACPassword

public char[] getHMACPassword()

Gets the HMAC password used for signing and verification.

In case of WSSDocument objects, if a UsernameToken object is set in the WSSParameters the password set in that UsernameToken object will be used as the HMAC password.

Returns:

The HMAC Password.

setCertificates

public void setCertificates(java.security.cert.X509Certificate[] certificates)

Sets the array of known certificates to use when attempting to verify a signature. This method is normally called by an application when XMLSecurityHandler.needPublicKeys() is invoked. This operation does not report any errors.

Parameters:

certificates - An array of X509Certificates.

setPublicKeys

public void setPublicKeys(java.security.PublicKey[] pubKeys)

Sets the array of known public keys to use when attempting to verifiy a signature. This method is normally called by an application when XMLSecurityHandler.needPublicKeys() is invoked. This operation does not report any errors.

Parameters:

pubKeys - An array of public keys.

setPrivateKey

public void setPrivateKey(java.security.PrivateKey privKey)

Sets the private key to use when signing. This operation does not report any errors.

Parameters:

privKey - The private key to use for signing.

removeSignatureProperties

public void removeSignatureProperties()

Removes all the signature properties associated with this signature; if this method is called, <SignatureProperty> element that holds the signing time will not be created for this signature.

addReference

public void addReference(Reference reference)
                  throws InvalidParameterException

Adds a SigReference.

Overrides:

addReference in class XMLSecurityOperation

Parameters:

reference - The reference to add.

Throws:

InvalidParameterException - If the reference is null.

setReferences

public void setReferences(Reference[] references)
                   throws InvalidParameterException

Sets the array of references.

Overrides:

setReferences in class XMLSecurityOperation

Parameters:

references - An array of references.

Throws:

InvalidParameterException - If the any of the references is null.