Share this page

# web_service_set_security

Web Services Functions (SOAP, WEB_SERVICE, Silverlight)

Adds security tokens to subsequent soap and web service calls.

    int web_service_set_security ( [const char * TtlIsSeconds ,] SECURITY_TOKEN, const char * attributes, [SECURITY_TOKEN , attributes... , SECURITY_TOKEN, attributes,] MESSAGE_SIGNATURE, const char * attributes, [MESSAGE_SIGNATURE, attributes, ..., MESSAGE_SIGNATURE, attributes,] ENCRYPTED_DATA, const char * attributes, [ENCRYPTED_DATA, attributes,... ENCRYPTED_DATA, attributes,] LAST );

TtlIsSeconds | The period for which the message is valid from the time of its creation in seconds.
SECURITY_TOKEN | Each section beginning with a SECURITY_TOKEN marker specifies a token. For details of the attributes, see below.
MESSAGE_SIGNATURE | Each section beginning with a MESSAGE_SIGNATURE marker specifies that subsequent web service requests will be signed with the specified token. The signature can apply to the entire message, to the specified token, or to specified portions of the SOAP envelope. For details of the attributes, see below.
ENCRYPTED_DATA | Each section beginning with an ENCRYPTED_DATA marker specifies that subsequent web service requests will be encrypted with the specified token. The encryption can apply to the entire message, to the specified token, or to specified portions of the SOAP envelope. For details of the attributes, see below.
WS_ADDRESSING | The version of WS-addressing such as WSA1.0.
TIME_STAMP | Includes or excludes the time stamp in the header. See the example for the correct syntax.
LAST | A marker that indicates the end of the arguments list.

The web_service_set_security function specifies tokens to be attached at each subsequent soap_request and web_service_call invocation. The tokens remain in effect until the next web_service_set_security or web_service_cancel_security call.

At each web_service_call, security tokens are processed before attachments.

## Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure. Note that in many cases, this return value indicates the technical success of the function, and not the result. For example, a function that registers a string to be found in a subsequent step returns LR_PASS to indicate that the registration was successful. This does not indicate that the string was found in the server response.

## Parameterization

All attribute values of web_service_set_security can be parameterized except as noted in the descriptions of the attributes.

### SECURITY_TOKEN

A security token specification requires attributes. The data required depends on the type of token. All tokens have the following attributes:

Type: The type of token. The token type cannot be parameterized.

LogicalName: The logical name of the token. LogicalName cannot be parameterized.

Add (Optional): A Boolean value indicating whether to add this token to the request. The default is `True`.

Different types have additional attributes, as specified below:

- Type=Username

UserName: The user name associated with the security token.

Password: The password for the user name associated with the security token. VuGen may record the password argument as a call to lr_unmask. The lr_unmask invocation replaces the entire argument. For example, instead of `"Password=abcabc"`, the argument might be `lr_unmask("123456789abcdef123456789abcdef12345678")`.

PasswordOptions (Optional): A value specifying how the password is sent in SOAP messages. Possible values are `SendPlainText, SendNone,` and `SendHashed`.

- Type=X509

StoreName: The name of the certificate store. For an up-to-date list of possible values, see the Microsoft .NET Framework class library StoreName Enumeration documentation.

IDType: One of the following must be specified to identify the certificate:

`Base64KeyID`: A unique identifier for the certificate converted to base64.

`Base64Hash`: The hash value of the certificate converted to base64.

`SubjectName`: The certificate name value.

IDValue: The value of the certificate identifier.

StoreLocation(Optional): The store location. Possible values are CurrentUser and LocalMachine.

- Type=Kerberos,Kerberos2

Host: The name of the computer hosting the web service.

Domain: The domain of which the web service host is a member.

- Type=SecurityContext

BaseToken: The LogicalName of a previously defined token that is used for signing the security token request. BaseToken cannot be parameterized.

IssuerToken (Optional): The LogicalName of a previously defined token that encrypts the sender's entropy value. IssuerToken cannot be parameterized.

AddAppliesTo (Optional): Boolean value. If true, the web service URL with which the token will communicate is specified.

EndPointUri (Optional): The server that issues the token. If not specified, the web service host is used .

- Type=Derived

DeriveFrom: The LogicalName of previously defined token from which to derive this token (.NET DerivedKeyToken). DeriveFrom cannot be parameterized.

### MESSAGE_SIGNATURE

The message signature argument has the following attributes:

UseToken: The LogicalName of a previously defined token used to sign. UseToken cannot be parameterized.

Section to sign (Optional). If not specified, the entire contents of the Body element and the Timestamp element of the Security header are signed. To restrict the portion signed, specify one of the following:

TargetToken: The LogicalName of a previously defined token to sign. TargetToken cannot be parameterized.

TargetPath: The portion of the soap envelope to sign.

### ENCRYPTED_DATA

The encrypted data argument has the following attributes:

UseToken: The LogicalName of previously defined token that is used for encryption. UseToken cannot be parameterized.

Section to encrypt (Optional). If not specified, the entire contents of the Body element and none of the SOAP headers are encrypted. To restrict the portion encrypted, specify one of the following:

TargetToken: The LogicalName of previously defined token to encrypt. TargetToken cannot be parameterized.

TargetPath: The portion of the soap envelope to encrypt.

## Example

After the call to web_service_set_security in this example, every soap_request and web_service_call until the next web_service_set_security or web_service_cancel_security call will sent with three tokens: a Username token, a Derived token, and a binary X509 token.

All tags that correspond to the XPath statement: =//soap:Body/View will be signed using the username token.

The body of the Soap Envelope will be encrypted using the X509 token.

The Username token will be encrypted using the X509 token.

After the call to web_service_cancel_security, the tokens are no longer sent.

Copy code

    web_service_set_security("30",

      SECURITY_TOKEN,
        "TokenName=MyUserNameToken",
        "Type=Username",
        "UserName=admin", "Password=test",
        "PasswordOptions=SendPlainText",
        "IDType=SubjectName",

      MESSAGE_SIGNATURE,
        "UseToken=MyUserNameToken",
        "TargetPath=//soap:Body/View",
        "SignatureOptions=IncludeBody|IncludeAddressing|IncludeTimestamp",
        "TransformAlgorithm=http://www.w3.org/2001/10/xml-exc-c14n#",
        "CanonicalizationAlgorithm= http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/#WithComments",

      ENCRYPTED_DATA ,
        "EncryptionType=Content",
        "KeyAlgorithm=RSA15",
        "SessionAlgorithm=TripleDES",

      WS_ADDRESSING,
        "Version=WSA1.0",

      TIME_STAMP,
        "Exclude=True/False",

      LAST);
    ...

    web_service_cancel_security( );

Tips to improve your search results... VuGen Function Reference Version 26.1-26.3 Function Reference 26.1-26.3 All View Local Help Center View Online Help Center Version: