The SecurityToken Class

The heart of the WSE implementation of WS-Security is the SecurityToken class. This is an abstract class that is used as the base class for all the security credentials that can be used with WSE. As you can see in Table 15-1, this base class provides the necessary infrastructure for signing and encrypting messages.

Table 15-1: Properties of the *SecurityToken* Class
Property	Description
AuthenticationKey	Gets the key that can be used to verify the signature of a message
DecryptionKey	Gets the key that will be used to decrypt a message
EncryptionKey	Gets the key that will be used to encrypt a message
Id	Gets or sets a unique identifier for the SecurityToken object
SignatureKey	Gets the key that is used to sign a message
SupportsDataEncryption	Returns true if the SecurityToken can be used for encryption
SupportsDigitalSignature	Returns true if the security token can be used for signing messages

Unless you’re creating your own custom security credentials, you’ll rarely, if ever, need to use any of the properties shown in Table 15-1. As you’ll soon see, WSE does a wonderful job of shielding you from having to interrogate the SecurityToken instances to retrieve the keys for a different task—you simply add the SecurityToken to the request SoapContext, and WSE takes care of retrieving the correct keys.

As you saw earlier, WSE supports two types of security credentials, which translate into two derived classes, UsernameToken and X509SecurityToken. However, as you’ll recall from Chapter 12, we have a <wsse:BinarySecurityToken> defined that encapsulates any security credentials that are binary in nature, and this includes the X509 certificates. The class hierarchy in WSE also follows this pattern and defines another abstract class, BinarySecurityToken, that derives from SecurityToken and is used as the base class for the X509SecurityToken class.

The relationship between the classes is shown in Figure 15-3.

click to expand
Figure 15-3: SecurityToken inheritance

The classes derived from SecurityToken become more specific as you move further down the inheritance hierarchy, and each derived class adds more specific properties to the properties provided by the SecurityToken class.

As you’d expect, the UsernameToken class has Username and Password properties that allow a username and a password to be specified as well as PasswordOption and Nonce properties that allow you to provide a very basic level of security to the password.

Although the BinarySecurityToken is abstract and you can never create an instance of the class, it does provide the basic framework for all binary tokens—it has properties for specifying the type of the token and how the token is encoded, as well as properties for setting the raw binary for the token.

On top of the methods provided by BinarySecurityToken, the X509SecurityToken class provides only one other property of its own—the Certificate property, which allows the certificate that the security token is based on to be retrieved or specified.

We briefly talked about the individual properties and derived classes of the SecurityToken class. You’ll rarely need to deal with them directly. Both the UsernameToken and X509SecurityToken classes provide constructors that configure the required properties correctly; you can simply create the correct SecurityToken derived class and allow WSE to handle all the low-level details.