com.aaasec.sigserv.csspapp
Class SignSupportAPI

java.lang.Object
  com.aaasec.sigserv.csspapp.SignSupportAPI

public class SignSupportAPI
extends Object

This class defines a Java API for accessing services from a Central Signing Support service.

The support service is available in the form of a deployable .war, which ideally should be deployed on the same server as where the service provider service using this API is deployed, or at least on the same local network. However, it is quite possible to locate the support service anywhere if appropriate security measures are taken, such as through VPN protection.

In addition to obtaining services from a central signing support service, this API also provides a method for validating a signed document using an external TSL Trust signature validation service. Communication with such service should be SSL/TLS protected and appropriate measures should be added to verify the origin of the signature validation report data, through appropriate checks of the server certificate.

This API communicates with associated services through HTTP POST and HTTP GET requests. Before any of the API methods are called, this API must be initialized by setting appropriate values of the following parameters (using their associated setter functions):

maxMessageLength The maximum length of any data provided to the API using InputStream objects (Default set to 500 kBytes).

spSupportUrl The URL to the central signing support service.

tempFileLocation A file folder where this API can store temporary files.

validationServiceUrl The URL to the signature validation service (Only required if such service is used)

validationPolicy The name of the validation policy used to validate signed document (Only required if a validation service is used)

Author:

Stefan Santesson, 3xA Security AB (stefan@aaa-sec.com) on behalf of E-legitimatioinsnämnden (Licensing terms TBD)

Method Summary

static byte[]	getSignedDoc(String signTaskId) Gets the signed document base64 encoded bytes identified by the sign task ID.
static URL	getSignedDocumentUrl(String sigTaskId) Returns a Url for obtaining the signed document.
static String	getValidationReport(InputStream xmlDocIs) Sends a signed XML document for validation to a preconfigured signature validation service.
static String	getValidationReport(InputStream xmlDocIs, String policy) Sends a signed XML document for validation to a preconfigured signature validation service.
static void	setMaxMessageLength(int messageMaxLength) Sets the maximum message length that will be allowed in the exchange of data between the requesting service and the central signing support service.
static void	setSpSupportUrl(String spSupportUrl) Sets the URL for the Central signing support service
static void	setTempFileLocation(String tempFileLocation) Specifies the directory where temporary files are stored, holding return data from http post and http get requests.
static void	setValidationPolicy(String validationPolicy) Sets the name of the validation policy that is used when performing signature validation
static void	setValidationServiceUrl(String validationServiceUrl) Sets the URL for a signature validation service
static String	signRequest(InputStream docInputStream, String signerIdAttr, String signerId, String idpEntityId, byte[] signMessage) Send a HTTP POST message to the central signing support service, requesting a XHTML page to be passed to the client to initiate the central signing process.
static String	signRequest(InputStream xmlDocIs, String signerIdAttr, String signerId, String idpEntityId, String returnUrl, String spEntityId, byte[] signMessage, String sigAlgorithm) Send a HTTP POST message to the central signing support service, requesting a XHTML page to be passed to the client to initiate the central signing process.
static String	signResponse(byte[] sigResponse) Sends a signing response message obtained from the central signing service to the central signing support service for processing and validation.
static String	testCaseRequest(InputStream docInputStream, String signerIdAttr, String signerId, String idpEntityId, byte[] signMessage, String ref, String testCase) This call sends a request to the SP Support service to generate a testcase request to the signature service.
static String	testCaseRequest(InputStream xmlDocIs, String signerIdAttr, String signerId, String idpEntityId, String returnUrl, String spEntityId, byte[] signMessage, String sigAlgorithm, String ref, String testCase) This call sends a request to the SP Support service to generate a testcase request to the signature service.

Methods inherited from class java.lang.Object

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

Method Detail

setSpSupportUrl

public static void setSpSupportUrl(String spSupportUrl)

Sets the URL for the Central signing support service

Parameters:

spSupportUrl -

setMaxMessageLength

public static void setMaxMessageLength(int messageMaxLength)

Sets the maximum message length that will be allowed in the exchange of data between the requesting service and the central signing support service.

Parameters:

messageMaxLength - Integer specifying the maximum number of bytes

setValidationServiceUrl

public static void setValidationServiceUrl(String validationServiceUrl)

Sets the URL for a signature validation service

Parameters:

validationServiceUrl -

setValidationPolicy

public static void setValidationPolicy(String validationPolicy)

Sets the name of the validation policy that is used when performing signature validation

Parameters:

validationPolicy - name of the validation policy

setTempFileLocation

public static void setTempFileLocation(String tempFileLocation)

Specifies the directory where temporary files are stored, holding return data from http post and http get requests.

Parameters:

tempFileLocation - full path name of the temporary file directory

signRequest

public static String signRequest(InputStream docInputStream,
                                 String signerIdAttr,
                                 String signerId,
                                 String idpEntityId,
                                 byte[] signMessage)

Send a HTTP POST message to the central signing support service, requesting a XHTML page to be passed to the client to initiate the central signing process. This XHTML contains a form with a signed signing request and a post script that causes the client to post the signing request to the designated central signing server.

Parameters:

docInputStream - An Input stream providing the bytes of the XML document to be signed

signerIdAttr - A string representing the attribute OID of the signer identity. E.g. "1.2.752.29.4.13", not including any type declaratioins, such as "urn:oid:".

signerId - A string holding the signers identity value in the identified attribute

idpEntityId - The entityID of the IdP that should identify the signer in the central signing service

signMessage - A html message to be displayed to the signer in the central signing service

Returns:

A XHTML document that will initiate the central signing process through a form post when sent to the signer's web browser.

signRequest

public static String signRequest(InputStream xmlDocIs,
                                 String signerIdAttr,
                                 String signerId,
                                 String idpEntityId,
                                 String returnUrl,
                                 String spEntityId,
                                 byte[] signMessage,
                                 String sigAlgorithm)

Send a HTTP POST message to the central signing support service, requesting a XHTML page to be passed to the client to initiate the central signing process. This XHTML contains a form with a signed signing request and a post script that causes the client to post the signing request to the designated central signing server.

Parameters:

xmlDocIs - An Input stream providing the bytes of the document to be signed

signerIdAttr - A string representing the attribute OID of the signer identity. E.g. "1.2.752.29.4.13", not including any type declaratioins, such as "urn:oid:".

signerId - A string holding the signers identity value in the identified attribute

idpEntityId - The entityID of the IdP that should identify the signer in the central signing service

spEntityId - The entityID of the service provider requesting a signature. If this parameter is empty, then the default configured SP entity ID will be selected.

returnUrl - The URL where the response message is returned from the signing service. This parameter. If this string is null or empty, the pre-configured return URL in the support service is used.

signMessage - A html message to be displayed to the signer in the central signing service

sigAlgorithm - A URI identifier of a requested signature algorithm. If this string is null or empty, the default algorithm will be used.

Returns:

A XHTML document that will initiate the central signing process through a form post when sent to the signer's web browser.

testCaseRequest

public static String testCaseRequest(InputStream docInputStream,
                                     String signerIdAttr,
                                     String signerId,
                                     String idpEntityId,
                                     byte[] signMessage,
                                     String ref,
                                     String testCase)

This call sends a request to the SP Support service to generate a testcase request to the signature service.

Parameters:

docInputStream - An Input stream providing the bytes of the document to be signed

signerIdAttr - A string representing the attribute OID of the signer identity. E.g. "1.2.752.29.4.13", not including any type declaratioins, such as "urn:oid:".

signerId - A string holding the signers identity value in the identified attribute

idpEntityId - The entityID of the IdP that should identify the signer in the central signing service

signMessage - A html message to be displayed to the signer in the central signing service

ref - A reference to a previous request relevant for the test-case. This is only applicable for the replay test-case.

testCase - A string identifying the test-case. The test cases are:

oldReq Generates a request with old date.

predatedReq Generates a request with a date set in the future

badReqSig Generates a request signed by a valid requester but with a bad signature.

unknownRequester Generates a request signed by an unknown entity.

replay Replays a previous request identified by the ref parameter.

Returns:

A XHTML document that will initiate the central signing process through a form post when sent to the signer's web browser.

testCaseRequest

public static String testCaseRequest(InputStream xmlDocIs,
                                     String signerIdAttr,
                                     String signerId,
                                     String idpEntityId,
                                     String returnUrl,
                                     String spEntityId,
                                     byte[] signMessage,
                                     String sigAlgorithm,
                                     String ref,
                                     String testCase)

This call sends a request to the SP Support service to generate a testcase request to the signature service.

Parameters:

xmlDocIs - An Input stream providing the bytes of the XML document to be signed

signerIdAttr - A string representing the attribute OID of the signer identity. E.g. "1.2.752.29.4.13", not including any type declaratioins, such as "urn:oid:".

signerId - A string holding the signers identity value in the identified attribute

idpEntityId - The entityID of the IdP that should identify the signer in the central signing service

spEntityId - The entityID of the service provider requesting a signature. If this parameter is empty, then the default configured SP entity ID will be selected.

returnUrl - The URL where the response message is returned from the signing service. This parameter. If this string is null or empty, the pre-configured return URL in the support service is used.

signMessage - A html message to be displayed to the signer in the central signing service

sigAlgorithm - A URI identifier of a requested signature algorithm. If this string is null or empty, the default algorithm will be used.

ref - A reference to a previous request relevant for the test-case. This is only applicable for the replay test-case.

testCase - A string identifying the test-case. The test cases are:

oldReq Generates a request with old date.

predatedReq Generates a request with a date set in the future

badReqSig Generates a request signed by a valid requester but with a bad signature.

unknownRequester Generates a request signed by an unknown entity.

replay Replays a previous request identified by the ref parameter.

Returns:

A XHTML document that will initiate the central signing process through a form post when sent to the signer's web browser.

signResponse

public static String signResponse(byte[] sigResponse)

Sends a signing response message obtained from the central signing service to the central signing support service for processing and validation. The central signing service will process that response and compare it with earlier sign requests (max 10 minutes old). If a matching request is found a signed document will be created by adding the signature received in the response to the document received in the request.

Parameters:

sigResponse - The bytes of the signing response

Returns:

A JSON object holding status information about the result from processing the signing response. The JSON object holds the following values:

"status": "response" if a response has been received and processed,

"signTaskID": The unique identifier of this sign task,

"documentName": (empty) Not set by the support service,

"respSigValid": boolean true if the response was correctly signed,

"signedDocValid": boolean true true if the constucted document has a valid signature,

"validResponse": boolean true if the response indicate a successfull central signing,

"responseCode": "101" for successful signing,

"responseMessage": "OK" for successful signing,

"signingTime": Date and time for signing (Note that this is only a presentation string for the time. A machine readable time is provided in the sign response XML), * *

"userId": An array, holding signers identity attributes. Each element in the array holds the elements "name" (attribute id) and "value" (attribute value),

"pathLen": The number of certs in the signer cert path.

getSignedDoc

public static byte[] getSignedDoc(String signTaskId)

Gets the signed document base64 encoded bytes identified by the sign task ID. This call can be done up until 10 minutes after the signed document was created.

Parameters:

signTaskId - identifier of the signing task. This is the value of the "signTaskID" parameter in the JSON status report obtained through the signResponse method.

Returns:

signed XML document produced through the sign task with the specified signTaskId.

getSignedDocumentUrl

public static URL getSignedDocumentUrl(String sigTaskId)

Returns a Url for obtaining the signed document.

Parameters:

sigTaskId - identifier of the signing task. This is the value of * the "signTaskID" parameter in the JSON status report obtained through the signResponse method.

Returns:

A URL specifying the location of the signed XML document. This URL is valid 10 minutes after the signed document is created.

getValidationReport

public static String getValidationReport(InputStream xmlDocIs)

Sends a signed XML document for validation to a preconfigured signature validation service.

Parameters:

xmlDocIs - An input stream providing the bytes of the signed document

Returns:

A string representation of the validation report object. If the configured validation service is a TSL Trust signature validation service, then the signature validation response is an XML report according to a defined schema.

getValidationReport

public static String getValidationReport(InputStream xmlDocIs,
                                         String policy)

Sends a signed XML document for validation to a preconfigured signature validation service.

Parameters:

xmlDocIs - An input stream providing the bytes of the signed document

policy - The policy under which the validation is performed.

Returns:

A string representation of the validation report object. If the configured validation service is a TSL Trust signature validation service, then the signature validation response is an XML report according to a defined schema.