Signature Web Service

Description	Signature services
Namespace	http://portwise.com/ws/v3/signature
Endpoint	https://<hostname>/ws/v3/services/Signature
Style	Document/Literal
WSDL	https://<host>/ws/v3/services/Signature?wsdl
Since	6.0.1

This service facilitates requesting Users to make Signatures, and also a means to verify those Signatures.

Signing Methods are identified with a unique integer ID, which can be obtained by consulting the installation's configuration via the Administration portal.

Signing Methods may employ long running strategies for creating Signatures, in such cases a polling flow is utilized. If a call to sign cannot be immediately replied to with a Signature - e.g. due to asynchronous user interaction - state information will instead be returned which must be included in subsequent calls to poll.

Endpoint Services

Name

sign

Description

Request a signature of the given TBS using the specified Signing Method.

Input

subject	a Subject representing the entity requesting the Signature.
signer	a Subject representing the entity that should generate the Signature.
method	an integer with the ID of the Signing Method to be used. Check the Administrator for the Signing Method's ID.
request	a SigningRequest describing the TBS and the requested Signature.

Output

A SigningResponse describing the Signature.
If no Signature could be returned immediately and the Signing Method supports polling, the response will contain state information and signer session ID that must be submitted in subsequent calls to poll.

Since

6.0.1

Faults

SigningException

if signing failed.

Name

poll

Description

Request a signature of the given TBS using the specified Signing Method.

Input

subject	a Subject representing the entity polling for the Signature.
method	an integer with the ID of the Signing Method to be used. Check the Administrator for the Signing Method's ID.
request	a SigningRequest describing the state of the polling Session. Must contain the state and signerSessionId values returned from the initial call to sign.
signerSessionId	ID of signer session which will be used for signing service.

Output

A SigningResponse describing the signature.

Since

6.0.1

Faults

SigningException

if signing/polling failed.

Name

verify

Description

Verify that the given Signature is made over the given TBS and by the specified Subject.

Input

subject	a Subject representing the entity verifying the Signature.
signer	a Subject representing the entity that supposedly made the Signature.
method	an integer with the ID of the Signing Method to be used. Check the Administrator for the Signing Method's ID.
request	a VerificationRequest describing the TBS and Signature to be verified.

Output

true if the Signature is valid; false otherwise.

Since

6.0.1

Faults

SigningException

if verification failed.

Java Example

This example shows how to request a signature of a given TBS, and how to verify it.

    // Locate Signing Web Service
    SignService signProxy = new SignService();
    Sign sign = signProxy.getSignature();

    String tbs = "Message to be signed";

    // Create Signing Request
    SigningRequest signReq = new SigningRequest();
    signReq.setTbs(tbs.getBytes(StandardCharsets.UTF_8));
    signReq.setTbsContentType("text/plain");
    signReq.setSignatureFormat("JWS");

    // Sign
    System.out.println("Sending Signing Request...");
    SigningResponse signResp = sign.sign(subject, signer, 0, signReq);

    // Poll for Signature, if required
    while (signResp.getSignature() == null && signResp.getState() != null) {
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            throw e;
        }
        System.out.println("Polling for signature...");

        // Create Polling Request
        SigningRequest pollReq = new SigningRequest();
        pollReq.setState(signResp.getState());
	pollReq.setSignerSessionId(signResp.getSignerSessionId());
        // Poll
        signResp = sign.poll(subject, 0, pollReq);
    }

    if (signResp.getSignature() != null) {
        System.out.println("Signing successful");
        byte[] signature = signResp.getSignature();

        // Create Verification Request
        VerificationRequest verifyReq = new VerificationRequest();
        verifyReq.setSignature(signature);
        verifyReq.setSignatureFormat(signResp.getSignatureFormat());
        verifyReq.setTbs(tbs.getBytes(StandardCharsets.UTF_8));

        // Verify Signature
        if (sign.verify(subject, signer, 0, verifyReq)) {
            System.out.println("Signature successfully verified");
        }
    }