WsCreateXmlSecurityToken function (webservices.h)

Creates a security token from its specified XML form.

Syntax

HRESULT WsCreateXmlSecurityToken(
  [in]           WS_XML_BUFFER                        *tokenXml,
  [in, optional] WS_SECURITY_KEY_HANDLE               *tokenKey,
                 const WS_XML_SECURITY_TOKEN_PROPERTY *properties,
  [in]           ULONG                                propertyCount,
                 WS_SECURITY_TOKEN                    **token,
  [in, optional] WS_ERROR                             *error
);

Parameters

[in] tokenXml

Pointer to a WS_XML_BUFFER structure containing the security token in its XML form. The referenced buffer must have exactly one top level XML element.

[in, optional] tokenKey

Pointer to a SECURITY_KEY_HANDLE structure that may or may not contain a cryptographic proof-of-possession key. If present the key can be used to bind this security token to a message. If the value of the tokenKey parameter is not NULL, the token is assumed to have a proof-of-possession key. If the value is NULL, the structure is assumed to be a "bearer token" as defined below.

• A bearer token also called a basic or keyless token is serialized in a message to demonstrate the message's possession of the token, and to indicate the intention to apply the claims from the token to that message.
• A proof-of-possession token also called a PoP or cryptographic token has an associated cryptographic key which must be used to "sign" a message in order to demonstrate possession of the token and to indicate the intention to apply the claims from the token to that message. An example is an X.509 certificate: the message must be signed with the private key of the certificate in order for a receiving principal to accept the message as carrying the claims present in the certificate.

properties

An array of WS_XML_SECURITY_TOKEN_PROPERTY structures containing optional properties for the XML security token.

The value of this parameter may be NULL, in which case, the propertyCount parameter must be 0 (zero).

[in] propertyCount

The number of properties in the properties array.

token

On success, a pointer that receives the address of the WS_SECURITY_TOKEN structure representing the created XML security token.

When you no longer need this structure, you must free it by calling WsFreeSecurityToken.

The returned security token may be used with WS_XML_TOKEN_MESSAGE_SECURITY_BINDING if it is to be

presented to a service.

[in, optional] error

Pointer to a WS_ERROR structure that receives additional error information if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.

Requirements