# wsclient

### Table of Contents

## Introduction

wsclient acts as a Web Service client. Normally, wsclient uses a request/response pattern. The XML payload of the request is read from stdin and the XML payload of the received reply is written to stdout. wsclient supports two different bindings:

- SOAP. The XML payload is wrapped in a SOAP body element and then in a SOAP envelope element. With this binding, wsclient will act as a SOAP-compliant client. Any transport supported by the underlying SOAP engine can be used; the transport will be inferred from the URI scheme.

- HTTP. The XML payload is sent as the entity-body of an HTTP message. With this binding, wsclient will act as an HTTP-compliant client. Only HTTP can be used. By default, the POST method will be used.

The payload is conceptually an XML infoset rather than a byte-stream. By default, the XML infoset is serialized as a plain XML document on input and output, but wsclient also supports the use of XOP to allow the input and output to refer to external binary resources. When using the SOAP binding, wsclient can also use MTOM for sending and receiving the payload. Note that the serialization of the XML payload for input and output is independent of the serialization of the payload for sending and receiving.

Instead of being an XML infoset, the payload can be empty. This is represented on input and output as an empty file (0 bytes). With the SOAP binding, this corresponds to a SOAP body element with no children. With the HTTP binding, it corresponds to an HTTP message with no entity body.

By default, wsclient uses the HTTP binding. The SOAP binding may be used for just the reply or for both the request and the reply. The general form of the command is:
`wsclient` [options] [destURI].

The destURI argument is required unlesss the `–in-reply-to-message` option is used.

With the SOAP binding, if a fault message is recevied as the reply, the fault is output as normal, but the exit code will be 1 rather than 0.

[Options marked with * are suggested for 1.0.]

## HTTP binding options

The options in this section require the use of the HTTP binding for the request.

`–get`*

Uses GET as the HTTP method. Nothing will be read from the input.

`–put`

Uses PUT as the HTTP method.

`–content-type=content-type`*

The payload has content-type content-type. By default, with the HTTP binding, wsclient will use a content-type of application/xml. No content-type will be specified for the empty payload.

## SOAP binding options

The use of any option in this section implies `–soap`.

`–soap`*

Use the SOAP binding. This always enables the SOAP binding for the reply. It also enables the SOAP binding for the request, unless an option such as `–get` is used that requires the HTTP binding for the request. In the normal case, you will not need to specify the `–soap` option, because you will need to specify the `–action` option, which implies the use of the SOAP binding. It’s useful mainly in conjunction with `–get`.

`–soap1.1`

Use version 1.1 of SOAP.

`–send-only`*

Normally, wsclient uses a request/response pattern. With the SOAP binding, it will normally expect to get a SOAP message back and will exit with an exit code of 2, if it does not. With `–send-only`, it will not expect to get a SOAP message back (other than a fault); if it does get a SOAP message back, it will exit with an exit code of 2.

`-a`*
`–action=`uri*

Use uri as the SOAP action. This implies the use of WS-Addressing unless `–no-wsa` is used.

`–soap-header=`filename

Add the contents of filename as a SOAP header block. filename is parsed as an XML document. The document element of the resulting element is added as a SOAP header block. This option can be specified multiple times.

`–soap-out`*

Output the entire SOAP reply instead of just its XML payload.

`–soap-dump`*

Output the SOAP request to stdout instead of sending it.

`–soap-in`

### WS-Addressing options

`–no-wsa`*

Don’t add WS-Addressing headers.

`–to=`uri*

Uses uri as the To address instead of destURI. A wsa:To header will always be added unless `–no-wsa` is specified.

`–from=`uri*

Inserts a wsa:From header with an address of uri.

`–reply-to=`uri*

Uses uri as the ReplyTo address. If `–reply-to` is not specified and `–send-only` is specified, then `http://www.w3.org/2005/08/addressing/none` will be used as the wsa:ReplyTo address. If neither `–reply-to` nor `–send-only` is specified, then no wsa:ReplyTo address will be added.

`–fault-to=`uri*

Uses uri as the FaultTo address.

`–in-reply-to=`uri*

Inserts a wsa:RelatesTo header with a relationship of `http://www.w3.org/2005/08/addressing/reply`.

`–in-reply-to-message=`file

Inserts addressing headers appropriate for a message that is in reply to the SOAP message contained in file. destURI is optional in this case.

`–wsa-submission`

Use the WS-Addressing Submission rather the WS-Addressing 1.0 Recommendation.

### Security options

`–timestamp`*

Generates a timestamp element in the security header.

`–ttl=`duration

Makes the timestamp expire after an interval of duration. duration must be non-empty and match the regexp:

([0-9]+d)?([0-9]+h)?([0-9]+m)?(([0-9]+(\.[0-9]*)|\.[0-9]+?)s)?

A number followed by d, h, m or s specifies a duration in days, hours, minutes or seconds respectively. Implies –timestamp.

`–sign-body`

Signs the SOAP body.

`–sign-header=`QName

Signs any SOAP headers whose element name is the specified URI and local-name; local-name may be * to indicate all SOAP headers in that namespace; may be used multiple times.

The binding of any prefix in the QName to a namespace URI is controlled by the `–xmlns` option.

`–sign-element=`QName

Signs any elements in the message whose element name is the specified URI and local-name and that is not within any other element that is to be signed ; without this option, cipher data will automatically be identified as eligible for binary optimization.

The binding of any prefix in the QName to a namespace URI is controlled by the `–xmlns` option.

`–sign-timestamp`

Signs the timestamp. The timestamp must either already be present or –timestamp must be used to add one.

`–protect-tokens`

[Same as sp:ProtectTokens. Is this needed?]

`–certificate=`file

Includes an X509 security token from file, which is an X509 certificate in PEM format. This is a certificate for the sender which can be used for signing or supporting according to other options.

`–key=`file

Signs using the private key file, which must be the private key in PEM format. The certificate corresponding to the key must be specified using –certificate.

`–key-password=`passwd

Password for accessing the private key (needed if the private key is password-protected). This is not secure on a multi-user machine since passwords on the command-line are accessible to other users via utilities such as ps.

`–key-password-file=`file

File containing password for accessing the private key (needed if the private key is password-protected).

`–encrypt-payload`

Encrypts the contents of the SOAP body.

`–encrypt-element=`QName

Encrypts any elements in the message whose element name is the specified URI and local-name and that are not within any other element that is to be encrypted. May be specified multiple times.

The binding of any prefix in the QName to a namespace URI is controlled by the `–xmlns` option.

`–no-binary-optimize-cipher-data`

Prohibits cipher data from being binary-optimized.

`–encrypt-before-signing`

Encrypts before signing, in other words the signature is computed over the ciphertext; by default, when there a message is to be protected with both signing and encryption, wsclient will sign before encrypting, in other words, the signature will be computed over the plaintext.

`–encrypt-signature`

Encrypts the signature (when signing before encryption).

`–recipient-certificate=`file

Encrypts using the public key associated with file, which should be an X509 certificate in PEM format.

`–algorithmsuite=`algorithmsuite

Use the corresponding algorithmsuite for signature and encryption. The value is one from Web Services Security Policy language July-2005 [section 7.1 Algoruthmsuite Property]

eg:- –algorithmsuite=Basic256Rsa15

`–policy-file=`policy-file

This option is used to provide a security policy file for wsclient. When you give this option you can avoid using options like –timestamp, –sign-body, –encrypt-signature and –encrypt-payload because these could be specified in policy xml file.

eg:- -policy-file $WSFCPP_HOME/bin/samples/wsclient/data/policy.xml

`–user=`user*

Includes a username token with user as the username.

`–password=`passwd*

Uses passwd as the password for the username token. This is not secure on a multi-user machine since passwords on the command-line are accessible to other users via utilities such as ps.

`–password-file=`file*

Uses the password from file. Leading and trailing whitespace are stripped.

`–netrc`

Includes a username token using .netrc to select the username and password. The .netrc file is used by a number of client programs such as ftp and curl to map machine names to user/password pairs. See netrc(5). The machine name used to lookup the user/password in .netrc comes from the destination URI of the SOAP message.

`–digest`

Uses a password digest for the username token. This requires that there be options specifying the password (such as –user-password).

`–force-insecure`

By default, a plain text password will only be sent over a secure transport (https). This option will force a plain text password to be sent over an insecure transport. This option is insecure.

#### Complex SOAP security operations

WS-Security is very general and allows for multiple security tokens of multiple types which can separately be used to protect the message in complex interdependent ways. In order to support this, we allow each security token to be distinguished by an index, which can be any ASCII alphanumeric string. All of the options in the previous section (apart from `–timestamp` and `–ttl`) can optionally specify a token index. For options that take an argument, the token index is specified following a comma after the required argument. For options that don’t take an argument, the token index becomes an optional argument.

In addition there are two additional options:

`–sign-token=`[token index][`,`signing token index]

Signs token token index using token signing token index. If token index is omitted, all pre-existing tokens in the input message are signed.

`–sign-signature=`[signature token index][`,`signing token index]

Signs signature done using token signature token index using token signing token index. If signature token index is omitted, all pre-existing signatures in the input message are signed.

Example of SignedEndorsingSupportingTokens from 9.4 of Security Policy.

    wsclient --certificate=1.pem,1 --certificate=2.pem,2 \
      --sign-timestamp=1 --sign-token=2,1  --sign-signature=1,2

## MTOM options

`–no-mtom`*

Don’t use MTOM to optimize the sending of the XML infoset. This works with both the SOAP and the HTTP binding. MTOM is always supported for receiving. By default, MTOM is used for sending if there are any elements that are binary-optimized. When `–xop-in` is used, elements whose content was specified with xop:Include are binary optimized.

`–xop-in`[=dir]*

When constructing the logical XML infoset of the payload from the input XML, recognize xop:Include elements and resolve them. Resolving an xop:Include element means replacing the element by the base64 encoding of the resource referenced by the URI in the href attribute. The XOP specification restricts the URI to be a cid URI, but this restriction is not applied here. If `–no-mtom` has not been specified, then the net result is a MIME XOP package will be transmitted and the URI in each xop:Include element will be replaced by a cid URI.

The URI in the href attribute may be a relative URI. If it is, then it is resolved into an absolute URI using the absolute file URI corresponding to the directory dir as the base URI. Note that dir may be a relative path name (which is resolved relative to the current directory as usual). The dir option argument is optional. It defaults to `.` (the current directory).

`–xop-out`[=dir]*

Serialize the received reply by creating an XOP package, writing the extracted content as files in dir, and serializing the XOP document to stdout with the URIs in the xop:Include href attributes being relative URIs relative to dir referencing the extracted content. The elements whose content is extracted will be those that were binary optimized in the received reply. Thus the net result of `–xop-out` is to write the non-root parts to files in dir, and write the root part to stdout, replacing cid URIs by relative URIs referencing the files. The dir option argument is optional. It defaults to `.` (the current directory). The names of the output file will be chosen so as not to overwrite any existing files in dir.

## General HTTP options

These can be used with the SOAP binding only if the transport is HTTP.

`–http-header=line`*

Add line as an HTTP header.

`–output-http-headers=file`*

Output the HTTP headers in the response to file.

## Other options

`–xmlns=`prefix,namespace

A prefix of prefix in a QName on the command-line is interpreted as referring to the URI namespace. This is used by the `–sign-header`, `–sign-element` and `–encrypt-element` options.

`--help`

Print the help available for wsclient.

## Exit codes

- 0 everything OK
- 1 response is a fault message
- 2 problem receiving a response
- 3 problem sending the message
- 4 problem in the input or options