<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="WSSUsernameToken">
  <head>
    <title>WSSUsernameToken class documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>25485</version>
    <date>2007-09-14 13:54:55 +0100 (Fri, 14 Sep 2007)</date>
    <copy>2009 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the WSSUsernameToken class
      </heading>
      <class name="WSSUsernameToken" super="NSObject">
        <declared>WSSUsernameToken.h</declared>
        <desc>
          <p>
            Supports the Web Services Security Username Token
            capability. <br /> The initial implementation
            only supports plaintext password client use
          </p>
          <p>
            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:
          </p>
<example>
 - (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;
 }
 </example>
        </desc>
        <method type="NSString*" factory="yes">
          <sel>digestHashForPassword:</sel>
          <arg type="NSString*">password</arg>
          <sel>andTimestamp:</sel>
          <arg type="NSCalendarDate**">date</arg>
          <sel>withNonce:</sel>
          <arg type="NSString**">nonce</arg>
          <desc>
            Takes a plaintext <var>password</var>, timestamp, and
            a base64 encoded <var>nonce</var>, and generates and
            returns a base64 encoded hash digest. <br /> If the
            supplied <var>date</var> is <code>nil</code> 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. <br /> If
            the supplied <var>nonce</var> is <code>nil</code> then
            a new one is generated and returned. <br /> If the
            supplied <var>date</var> is actually a string, it
            is parsed to form a <var>date</var> and replaced by the
            resulting calendar <var>date</var> object.
          </desc>
        </method>
        <method type="NSString*" factory="yes">
          <sel>digestHashForPassword:</sel>
          <arg type="NSString*">password</arg>
          <sel>andTimestamp:</sel>
          <arg type="NSCalendarDate**">date</arg>
          <sel>withNonce:</sel>
          <arg type="NSString**">nonce</arg>
          <sel>algorithm:</sel>
          <arg type="GWSDigestAlgorithm">algorithm</arg>
          <desc>
            Takes a plaintext <var>password</var>, timestamp, and
            a base64 encoded <var>nonce</var>, and generates and
            returns a base64 encoded hash digest. <br /> If the
            supplied <var>date</var> is <code>nil</code> 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. <br /> If
            the supplied <var>nonce</var> is <code>nil</code> then
            a new one is generated and returned. <br /> If the
            supplied <var>date</var> is actually a string, it
            is parsed to form a <var>date</var> and replaced by the
            resulting calendar <var>date</var> object. <br />
            The <var>algorithm</var> argument overrides the default
            behavior of producing the digest using SHA1 (the
            standard).
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>addToHeader:</sel>
          <arg type="GWSElement*">header</arg>
          <desc>
            Adds a representation of the receiver to the specified
            SOAP <var>header</var> and returns the modified
            <var>header</var>. If the <var>header</var> is
            <code>nil</code>, this simply returns a
            representation of the receiver which can
            then be added to a SOAP <var>header</var>.
          </desc>
        </method>
        <method type="GWSDigestAlgorithm">
          <sel>algorithm</sel>
          <desc>
            Returns the encryption algorithm used for the
            digest.
          </desc>
        </method>
        <method type="id">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>password:</sel>
          <arg type="NSString*">password</arg>
          <desc>
            Initialise the receiver with a <var>name</var>
            and <var>password</var> used to authenticate with a
            remote server.
          </desc>
        </method>
        <method type="id" init="yes">
          <sel>initWithName:</sel>
          <arg type="NSString*">name</arg>
          <sel>password:</sel>
          <arg type="NSString*">password</arg>
          <sel>timeToLive:</sel>
          <arg type="unsigned">ttl</arg>
          <desc>
            Initialise the receiver with a <var>name</var>
            and <var>password</var> used to authenticate with a
            remote server. <br /> If <var>ttl</var> is non-zero,
            then a hash of the token is used along with a creation
            date and nonce. The actual <var>ttl</var> 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.
          </desc>
        </method>
        <method type="void">
          <sel>setAlgorithm:</sel>
          <arg type="GWSDigestAlgorithm">algorithm</arg>
          <desc>
            Sets the <var>algorithm</var> used for digests.
          </desc>
        </method>
        <method type="GWSElement*">
          <sel>tree</sel>
          <desc>
            Return a tree representation of the WSS Username
            Token for inclusion in the header of a SOAP request.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSData(GWSDigest)
        category
      </heading>
      <category name="GWSDigest" class="NSData">
        <declared>WSSUsernameToken.h</declared>
        <desc>
          Produce a digest of an NSData object. <br /> Used
          internally by
          <ref type="class" id="WSSUsernameToken">WSSUsernameToken</ref>
            when hash based authentication is in use.
        </desc>
        <method type="NSData*">
          <sel>SHA1</sel>
          <desc>
            This method produces an SHA1 digest of the receiver
            and returns the resulting value as an autoreleased
            NSData object. <br /> NB SHA1 is considered
            insecure.
          </desc>
        </method>
        <method type="NSData*">
          <sel>SHA2_256</sel>
          <desc>
            This method produces an SHA2_256 digest of the
            receiver and returns the resulting value as an
            autoreleased NSData object.
          </desc>
        </method>
        <method type="NSData*">
          <sel>SHA2_512</sel>
          <desc>
            This method produces an SHA2_512 digest of the
            receiver and returns the resulting value as an
            autoreleased NSData object.
          </desc>
        </method>
        <method type="NSData*">
          <sel>SHA3_256</sel>
          <desc>
            This method produces an SHA3_256 digest of the
            receiver and returns the resulting value as an
            autoreleased NSData object.
          </desc>
        </method>
        <method type="NSData*">
          <sel>SHA3_512</sel>
          <desc>
            This method produces an SHA3_512 digest of the
            receiver and returns the resulting value as an
            autoreleased NSData object.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>WSSUsernameToken types</heading>
      <p></p>
      <type type="enum ..." name="GWSDigestAlgorithm">
        <desc>
          The GWSDigestAlgorithm enumeration is used to specify
          what algorithm is to be used for working with digests.
          <deflist>
            <term><em>GWSDigestSHA1</em></term> <desc></desc>
            <term><em>GWSDigestSHA2_256</em></term>
            <desc></desc>
            <term><em>GWSDigestSHA2_512</em></term>
            <desc></desc>
            <term><em>GWSDigestSHA3_256</em></term>
            <desc></desc>
            <term><em>GWSDigestSHA3_512</em></term>
            <desc></desc>
          </deflist>
        </desc>
      </type>
    </chapter>
  </body>
</gsdoc>
