web_service_set_security

Example: web_service_set_security and web_service_cancel_securityWeb 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.

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.

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.

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.