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:
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.]
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.
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
–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.
–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.
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
–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.
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.
–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.