SOAPQuickSigner Class

Properties   Methods   Events   Config Settings   Errors  

The SOAPQuickSigner class signs SOAP messages.

Syntax

secureblackbox.Soapquicksigner

Remarks

The purpose of the SOAPQuickSigner class is creating simple generic signatures over SOAP messages. Unlike SOAPSigner, it does not include chain validation and LTV features, and may be more appropriate for scenarios where no chain validation is required.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CanonicalizationMethod Property (SOAPQuickSigner Class)

Specifies XML canonicalization method to use.

Syntax

public int getCanonicalizationMethod();


public void setCanonicalizationMethod(int canonicalizationMethod);


Enumerated values:
  public final static int cxcmNone = 0;
  public final static int cxcmCanon = 1;
  public final static int cxcmCanonComment = 2;
  public final static int cxcmExclCanon = 3;
  public final static int cxcmExclCanonComment = 4;
  public final static int cxcmMinCanon = 5;
  public final static int cxcmCanon_v1_1 = 6;
  public final static int cxcmCanonComment_v1_1 = 7;

Default Value

1

Remarks

Use this property to specify the method for XML canonicalization of SignedInfo element. See XML-Signature Syntax and Processing specification for details.

Supported canonicalization methods:

EmbedCertificateMethod Property (SOAPQuickSigner Class)

Controls the certificate disposition within the signature.

Syntax

public int getEmbedCertificateMethod();


public void setEmbedCertificateMethod(int embedCertificateMethod);


Enumerated values:
  public final static int cwecInSignature = 0;
  public final static int cwecInBinarySecurityToken = 1;
  public final static int cwecInSignedBinarySecurityToken = 2;
  public final static int cwecInBinarySecurityTokenAndSignature = 3;
  public final static int cwecNone = 4;

Default Value

1

Remarks

This property controls the method of embedding the signing certificate(s) into the signature if WS-Security signature type is used.

Supported values:

Encoding Property (SOAPQuickSigner Class)

Specifies XML encoding.

Syntax

public String getEncoding();


public void setEncoding(String encoding);

Default Value

""

Remarks

Use this property to specify the encoding to apply to the XML documents.

ExternalCrypto Property (SOAPQuickSigner Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (SOAPQuickSigner Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

HashAlgorithm Property (SOAPQuickSigner Class)

Specifies the hash algorithm to be used.

Syntax

public String getHashAlgorithm();


public void setHashAlgorithm(String hashAlgorithm);

Default Value

"SHA256"

Remarks

Use this property to set the hash algorithm for signature calculation.

Supported values:

InputFile Property (SOAPQuickSigner Class)

Specifies the SOAP message to be signed.

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

Provide a full path to the SOAP message to be signed.

InputStream Property (SOAPQuickSigner Class)

A stream containing the SOAP message to be signed.

Syntax

public java.io.InputStream getInputStream();


public void setInputStream(java.io.InputStream inputStream);

Default Value

null

Remarks

Use this property to provide the SOAP message to the class in a stream.

This property is not available at design time.

OutputFile Property (SOAPQuickSigner Class)

A file where the signed SOAP message will be saved.

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

Provide a full path to the file where the signed SOAP message should be saved.

OutputStream Property (SOAPQuickSigner Class)

A stream to write the signed SOAP message to.

Syntax

public java.io.OutputStream getOutputStream();


public void setOutputStream(java.io.OutputStream outputStream);

Default Value

null

Remarks

Use this property to specify the stream to save the signed SOAP message to.

This property is not available at design time.

References Property (SOAPQuickSigner Class)

A list of references to the data to be signed.

Syntax

public XMLReferenceList getReferences();


public void setReferences(XMLReferenceList references);

Remarks

Electronic signature is computed over a set of data pieces. Each piece of data to be signed is specified by a reference.

This property is not available at design time.

Please refer to the XMLReference type for a complete list of fields.

SecurityHeaderIndex Property (SOAPQuickSigner Class)

Specifies the SecurityHeader index.

Syntax

public int getSecurityHeaderIndex();


public void setSecurityHeaderIndex(int securityHeaderIndex);

Default Value

-1

Remarks

Use this property to specify the index of SecurityHeader element where to put the signature. If the specified SecurityHeader element doesn't exist then a new SecurityHeader element will be created. The default value is "-1", in this case a new SecurityHeader element will be always created.

SignatureType Property (SOAPQuickSigner Class)

The SOAP signature type to use.

Syntax

public int getSignatureType();


public void setSignatureType(int signatureType);


Enumerated values:
  public final static int sstUnknown = 0;
  public final static int sstWSSSignature = 1;
  public final static int sstSOAPSignature = 2;

Default Value

1

Remarks

Use this property to specify the signature type to use when forming the signature.

Supported values:

SigningCertificate Property (SOAPQuickSigner Class)

The certificate to be used for signing.

Syntax

public Certificate getSigningCertificate();


public void setSigningCertificate(Certificate signingCertificate);

Remarks

Use this property to specify the certificate that shall be used for signing the data. Note that this certificate should have a private key associated with it. Use SigningChain to supply the rest of the certificate chain for inclusion into the signature.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SigningChain Property (SOAPQuickSigner Class)

The signing certificate chain.

Syntax

public CertificateList getSigningChain();


public void setSigningChain(CertificateList signingChain);

Remarks

Use this property to provide the chain for the signing certificate. Use the SigningCertificate property, if it is available, to provide the signing certificate itself.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

XPathNamespaces Property (SOAPQuickSigner Class)

Specifies namespaces for XPath expression.

Syntax

public XMLNamespaceList getXPathNamespaces();


public void setXPathNamespaces(XMLNamespaceList XPathNamespaces);

Remarks

Use this property to provide a list of prefixes and namespaceURIs to use in XPath expressions with TargetXMLElement and XPathPrefixList properties of the references.

This property is not available at design time.

Please refer to the XMLNamespace type for a complete list of fields.

AddBodyReference Method (Soapquicksigner Class)

Creates a new XML reference to the Body element of the SOAP message.

Syntax

public int addBodyReference(String customId, boolean autoGenerateId);

Remarks

Use this method to add a reference to the Body element of the SOAP message.

The reference's URI is set basing on the ID of the XML element. If the XML element doesn't have an ID then a CustomId value will be used. If CustomId is empty and AutoGenerateId is set, the ID will be generated automatically. An exception will be thrown otherwise.

Use CanonicalizationMethod and HashAlgorithm properties to specify the canonicalization method and hash algorithm to use.

The method returns the index of the new reference entry in the References collection.

AddDataReference Method (Soapquicksigner Class)

Creates a new XML reference to the specified data.

Syntax

public int addDataReference(String dataURI, byte[] data);

Remarks

Use this method to add a reference to the custom data. Pass the reference's URI via DataURI parameter.

Use HashAlgorithm property to specify the hash algorithm to use.

The method returns the index of the new reference entry in the References collection.

AddReference Method (Soapquicksigner Class)

Creates a new XML reference to the specified XML element.

Syntax

public int addReference(String targetXmlElement, String customId, boolean autoGenerateId);

Remarks

Use this method to add a reference to a particular XML element.

The reference's URI is set basing on the ID of the XML element. If the XML element doesn't have an ID then a CustomId value will be used. If CustomId is empty and AutoGenerateId is set, the ID will be generated automatically. An exception will be thrown otherwise.

Use CanonicalizationMethod and HashAlgorithm properties to specify the canonicalization method and hash algorithm to use.

The method returns the index of the new reference entry in the References collection.

Config Method (Soapquicksigner Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

DoAction Method (Soapquicksigner Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

ExtractAsyncData Method (Soapquicksigner Class)

Extracts user data from the DC signing service response.

Syntax

public String extractAsyncData(String asyncReply);

Remarks

Call this method before finalizing the asynchronous signing process to extract the data passed to the ExternalCrypto.Data property on the pre-signing stage.

The Data parameter can be used to pass some state or document identifier along with the signing request from the pre-signing to the completion async stage.

GetInnerXML Method (Soapquicksigner Class)

Get the inner XML content of the selected XML element.

Syntax

public String getInnerXML(String XPath);

Remarks

Call this method to get the inner XML content of the selected XML element.

GetOuterXML Method (Soapquicksigner Class)

Get the outer XML content of the selected XML element.

Syntax

public String getOuterXML(String XPath);

Remarks

Call this method to get the outer XML content of the selected XML element.

GetTextContent Method (Soapquicksigner Class)

Get the text content of the selected XML element.

Syntax

public String getTextContent(String XPath);

Remarks

Call this method to get the text content of the selected XML element.

SetInnerXML Method (Soapquicksigner Class)

Set the inner XML content of the selected XML element.

Syntax

public void setInnerXML(String XPath, String value);

Remarks

Call this method to set the inner XML content of the selected XML element.

SetTextContent Method (Soapquicksigner Class)

Set the text content of the selected XML element.

Syntax

public void setTextContent(String XPath, String value);

Remarks

Call this method to set the text content of the selected XML element.

Sign Method (Soapquicksigner Class)

Signs the SOAP message.

Syntax

public void sign();

Remarks

Call this method to generate a signed SOAP message.

SignAsyncBegin Method (Soapquicksigner Class)

Initiates the asynchronous signing operation.

Syntax

public String signAsyncBegin();

Remarks

When using the DC framework, call this method to initiate the asynchronous signing process. Upon completion, a pre-signed copy of the document will be saved in OutputFile (or OutputStream). Keep the pre-signed copy somewhere local, and pass the returned string ('the request state') to the DC processor for handling.

Upon receiving the response state from the DC processor, assign the path to the pre-signed copy to InputFile (or InputStream), and call SignAsyncEnd to finalize the signing.

Note that depending on the signing method and DC configuration used, you may still need to provide the public part of the signing certificate via the SigningCertificate property.

Use the ExternalCrypto.AsyncDocumentID property to supply a unique document ID to include in the request. This is helpful when creating batches of multiple async requests, as it allows you to pass the whole response batch to SignAsyncEnd and expect it to recover the correct response from the batch automatically.

AsyncState is a message of the distributed cryptography (DC) protocol. The DC protocol is based on the exchange of async states between a DC client (an application that wants to sign a PDF, XML, or Office document) and a DC server (an application that controls access to the private key). An async state can carry one or more signing requests, comprised of document hashes, or one or more signatures produced over those hashes.

In a typical scenario you get a client-side async state from the SignAsyncBegin method. This state contains document hashes to be signed on the DC server side. You then send the async state to the DC server (often represented by the DCAuth class), which processes it and produces a matching signature state. The async state produced by the server is then passed to the SignAsyncEnd method.

SignAsyncEnd Method (Soapquicksigner Class)

Completes the asynchronous signing operation.

Syntax

public void signAsyncEnd(String asyncReply);

Remarks

When using the DC framework, call this method upon receiving the response state from the DC processor to complete the asynchronous signing process.

Before calling this method, assign the path to the pre-signed copy of the document obtained from the prior SignAsyncBegin call to InputFile (or InputStream). The method will embed the signature into the pre-signed document, and save the complete signed document to OutputFile (or OutputStream).

Note that depending on the signing method and DC configuration used, you may still need to provide the public part of the signing certificate via the SigningCertificate property.

Use the ExternalCrypto.AsyncDocumentID parameter to pass a specific document ID if using batched AsyncReply. If used, it should match the value provided on the pre-signing (SignAsyncBegin) stage.

AsyncState is a message of the distributed cryptography (DC) protocol. The DC protocol is based on the exchange of async states between a DC client (an application that wants to sign a PDF, XML, or Office document) and a DC server (an application that controls access to the private key). An async state can carry one or more signing requests, comprised of document hashes, or one or more signatures produced over those hashes.

In a typical scenario you get a client-side async state from the SignAsyncBegin method. This state contains document hashes to be signed on the DC server side. You then send the async state to the DC server (often represented by the DCAuth class), which processes it and produces a matching signature state. The async state produced by the server is then passed to the SignAsyncEnd method.

SignExternal Method (Soapquicksigner Class)

Signs the document using an external signing facility.

Syntax

public void signExternal();

Remarks

Call this method to delegate the low-level signing operation to an external, remote, or custom signing engine. This method is useful if the signature has to be made by a device accessible through a custom or non-standard signing interface.

When all preparations are done and hash is computed, the class fires ExternalSign event which allows to pass the hash value for signing.

Error Event (Soapquicksigner Class)

Information about errors during signing.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void error(SoapquicksignerErrorEvent e) {}
  ...
}

public class SoapquicksignerErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The event is fired in case of exceptional conditions during signing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to SOAP.

ExternalSign Event (Soapquicksigner Class)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void externalSign(SoapquicksignerExternalSignEvent e) {}
  ...
}

public class SoapquicksignerExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData;
}

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the class via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact class being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The class uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

FormatElement Event (Soapquicksigner Class)

Reports the XML element that is currently being processed.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void formatElement(SoapquicksignerFormatElementEvent e) {}
  ...
}

public class SoapquicksignerFormatElementEvent {
  public String startTagWhitespace;
  public String endTagWhitespace;
  public int level;
  public String path;
  public boolean hasChildElements;
}

Remarks

Path and Level specify the path to the XML element being processed and its nesting level, respectively.

HasChildElements specify if processed XML element has child elements.

Among other purposes, this event may be used to add whitespace formatting before or after a particular element in the signature.

FormatText Event (Soapquicksigner Class)

Reports XML text that is currently being processed.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void formatText(SoapquicksignerFormatTextEvent e) {}
  ...
}

public class SoapquicksignerFormatTextEvent {
  public String text;
  public int textType;
  public int level;
  public String path;
}

Remarks

TextType parameter specifies the type of the XML text (normal or Base64-encoded) that is stored in the element; Path and Level specify the path to the XML element and its nesting level.

Among other purposes, this event may be used to add whitespace formatting before or after a particular element in the signature.

Notification Event (Soapquicksigner Class)

This event notifies the application about an underlying control flow event.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void notification(SoapquicksignerNotificationEvent e) {}
  ...
}

public class SoapquicksignerNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

ResolveReference Event (Soapquicksigner Class)

Asks the application to resolve a reference.

Syntax

public class DefaultSoapquicksignerEventListener implements SoapquicksignerEventListener {
  ...
  public void resolveReference(SoapquicksignerResolveReferenceEvent e) {}
  ...
}

public class SoapquicksignerResolveReferenceEvent {
  public int referenceIndex;
  public String URI;
}

Remarks

This event is fired when the control could not automatically resolve a reference and requires custom treatment.

URI contains a reference to the data.

ReferenceIndex specifies the index of the reference to process.

Based on the reference's URI the event handler should set either TargetXMLElement or TargetData property of the reference.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

public Certificate( bytes,  startIndex,  count,  password);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( bytes,  startIndex,  count);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

public Certificate( path,  password);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certPath,  keyPath,  password);

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

public Certificate( path);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

public Certificate( stream);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public Certificate( stream,  password);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certStream,  keyStream,  password);

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

public Certificate();

Creates a new object with default field values.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

public ExternalCrypto();

Creates a new ExternalCrypto object with default field values.

XMLNamespace Type

Represents an XML namespace map for XPath expressions.

Remarks

This class defines the correspondence between Prefixes and namespace URIs.

Fields

Constructors

public XMLNamespace();

Creates a new XML namespace object.

XMLReference Type

Represents an XML reference element.

Remarks

XMLReference specifies the digest algorithm and digest value, and, optionally: an identifier of the object being signed, the type of the object, and/or a list of transforms to be applied prior to digesting.

Fields

Constructors

public XMLReference();

Creates a new XML reference element.

public XMLReference( ID);

Creates a new XML reference element from its ID .

public XMLReference( ID,  URI);

Creates a new XML reference element from its ID and URI reference to the external data.

Config Settings (Soapquicksigner Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

SOAPQuickSigner Config Settings

Base Config Settings

Trappable Errors (Soapquicksigner Class)

SOAPQuickSigner Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) 
	33554433   Input file does not exist (SB_ERROR_SOAP_INPUTFILE_NOT_EXISTS)
	33554434   Invalid key type (SB_ERROR_SOAP_INVALID_KEY_TYPE)
	33554435   Signature not found (SB_ERROR_SOAP_SIGNATURE_NOT_FOUND)
	33554436   Unsupported signature type (SB_ERROR_SOAP_UNSUPPORTED_SIGNATURE_TYPE)