# WSSUsernameToken class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 25485

Date: 2007-09-14 13:54:55 +0100 (Fri, 14 Sep 2007)

Copyright: (C) 2009 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the WSSUsernameToken class
2. Software documentation for the NSData(GWSDigest) category
3. WSSUsernameToken types

# Software documentation for the WSSUsernameToken class

## WSSUsernameToken : NSObject

> Declared in:
>   WSSUsernameToken.h

Supports the Web Services Security Username Token capability.
The initial implementation only supports plaintext password client use

Basic usage is simple, you create an instance of this class, initialising it with the username and password to be used to authenticate requests. Then for each request you add the token to the request header. This can be done either as a delegate of a coder or the delegate of a service. The following shows the delegate method for a service:

     - (GWSElement*) webService: (GWSService*)service willEncode: (GWSElement*)e
     {
       if (e == nil || [[e name] isEqual: @"Header"] == YES)
         {
           e = [wsstoken addToHeader: e];	// May return new object.
         }
       return e;
     }

Method summary

- +digestHashForPassword:andTimestamp:withNonce:
- +digestHashForPassword:andTimestamp:withNonce:algorithm:
- -addToHeader:
- -algorithm
- -initWithName:password:
- -initWithName:password:timeToLive:
- -setAlgorithm:
- -tree

### digestHashForPassword: andTimestamp: withNonce:

+ (NSString*) digestHashForPassword: (NSString*)password andTimestamp: (NSCalendarDate**)date withNonce: (NSString**)nonce;
Takes a plaintext password, timestamp, and a base64 encoded nonce, and generates and returns a base64 encoded hash digest.
If the supplied date is `nil` then the current timestamp is used and returned, otherwise the timestamp has its timezone and format adjusted as necessary and is used for the digest.
If the supplied nonce is `nil` then a new one is generated and returned.
If the supplied date is actually a string, it is parsed to form a date and replaced by the resulting calendar date object.

### digestHashForPassword: andTimestamp: withNonce: algorithm:

+ (NSString*) digestHashForPassword: (NSString*)password andTimestamp: (NSCalendarDate**)date withNonce: (NSString**)nonce algorithm: (GWSDigestAlgorithm)algorithm;
Takes a plaintext password, timestamp, and a base64 encoded nonce, and generates and returns a base64 encoded hash digest.
If the supplied date is `nil` then the current timestamp is used and returned, otherwise the timestamp has its timezone and format adjusted as necessary and is used for the digest.
If the supplied nonce is `nil` then a new one is generated and returned.
If the supplied date is actually a string, it is parsed to form a date and replaced by the resulting calendar date object.
The algorithm argument overrides the default behavior of producing the digest using SHA1 (the standard).

### addToHeader:

- (GWSElement*) addToHeader: (GWSElement*)header;
Adds a representation of the receiver to the specified SOAP header and returns the modified header. If the header is `nil`, this simply returns a representation of the receiver which can then be added to a SOAP header.

### algorithm

- (GWSDigestAlgorithm) algorithm;
Returns the encryption algorithm used for the digest.

### initWithName: password:

- (id) initWithName: (NSString*)name password: (NSString*)password;
Initialise the receiver with a name and password used to authenticate with a remote server.

### initWithName: password: timeToLive:

- (id) initWithName: (NSString*)name password: (NSString*)password timeToLive: (unsigned)ttl;
This is a designated initialiser for the class.
Initialise the receiver with a name and password used to authenticate with a remote server.
If ttl is non-zero, then a hash of the token is used along with a creation date and nonce. The actual ttl value is only of use for server-side code, which will reject any message whose creation date is older than the number of seconds specified as the time to live.

### setAlgorithm:

- (void) setAlgorithm: (GWSDigestAlgorithm)algorithm;
Sets the algorithm used for digests.

### tree

- (GWSElement*) tree;
Return a tree representation of the WSS Username Token for inclusion in the header of a SOAP request.

# Software documentation for the NSData(GWSDigest) category

## NSData(GWSDigest)

> Declared in:
>   WSSUsernameToken.h

Produce a digest of an NSData object.
Used internally by WSSUsernameToken when hash based authentication is in use.
Method summary

- -SHA1
- -SHA2_256
- -SHA2_512
- -SHA3_256
- -SHA3_512

### SHA1

- (NSData*) SHA1;
This method produces an SHA1 digest of the receiver and returns the resulting value as an autoreleased NSData object.
NB SHA1 is considered insecure.

### SHA2_256

- (NSData*) SHA2_256;
This method produces an SHA2_256 digest of the receiver and returns the resulting value as an autoreleased NSData object.

### SHA2_512

- (NSData*) SHA2_512;
This method produces an SHA2_512 digest of the receiver and returns the resulting value as an autoreleased NSData object.

### SHA3_256

- (NSData*) SHA3_256;
This method produces an SHA3_256 digest of the receiver and returns the resulting value as an autoreleased NSData object.

### SHA3_512

- (NSData*) SHA3_512;
This method produces an SHA3_512 digest of the receiver and returns the resulting value as an autoreleased NSData object.

# WSSUsernameToken types

### GWSDigestAlgorithm

typedef enum ... GWSDigestAlgorithm;
The GWSDigestAlgorithm enumeration is used to specify what algorithm is to be used for working with digests.

GWSDigestSHA1
GWSDigestSHA2_256
GWSDigestSHA2_512
GWSDigestSHA3_256
GWSDigestSHA3_512