ntlm/NtlmGenerator.h

   1 /*
   2  * Copyright (c) 2000-2004,2006-2007 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _NTLM_GENERATOR_H_
  25 #define _NTLM_GENERATOR_H_
  26
  27 #include <CoreFoundation/CFData.h>
  28 #include <CoreFoundation/CFString.h>
  29
  30 #ifdef  __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /*
  35  * This interface provides the capability to generate and parse the authentication
  36  * blobs which pass back and forth between a client and a server during NTLM
  37  * authentication. Only the client side is implemented.
  38  *
  39  * All three variants of NTLM authentication are performed: NTLM1, NTLM2, and
  40  * NTLMv2.
  41  *
  42  * In general, to use this stuff for HTTP authentication:
  43  *
  44  * 1. Determine that NTLM authentication is possible. Drop the connection
  45  *    to the server if you have a persistent connection open; MS servers
  46  *    require a clean unused connection for this negotiation to occur.
  47  *
  48  * 2. Create a NtlmGeneratorRef object, specifying possible restrictions
  49  *    on negotiation version.
  50  *
  51  * 3. Create the client authentication blob using NtlmCreateClientRequest()
  52  *    and send it to the server, base64 encoded, in a "Authorization: NTLM"
  53  *    header line.
  54  *
  55  * 4. The server should send back another 401 status, with its own blob in
  56  *    a "WWW-Authenticate: NTLM" header.
  57  *
  58  * 5. Base64 decode that blob and feed it into NtlmCreateClientResponse(), the
  59  *    output of which is another blob which you send to the server again in
  60  *    a "WWW-Authenticate: NTLM" header.
  61  *
  62  * 6. If you're lucky the server will give a 200 status (or something else useful
  63  *    other than 401) and you're done.
  64  *
  65  * 7. Free the NtlmGeneratorRef object with NtlmGeneratorRelease().
  66  */
  67
  68 /*
  69  * Opaque reference to an NTLM blob generator object.
  70  */
  71 typedef struct NtlmGenerator *NtlmGeneratorRef;
  72
  73 /*
  74  * Which versions of the protocol are acceptable?
  75  */
  76 enum {
  77         NW_NTLM1   = 0x00000001,
  78         NW_NTLM2   = 0x00000002,
  79         NW_NTLMv2  = 0x00000004,
  80
  81         // all variants enabled, preferring NTLMv2, then NTLM2
  82         NW_Any     = NW_NTLM2 | NW_NTLMv2
  83 };
  84 typedef uint32_t NLTM_Which;
  85
  86
  87 /* Create/release NtlmGenerator objects.*/
  88 OSStatus NtlmGeneratorCreate(
  89         NLTM_Which                      which,
  90         NtlmGeneratorRef        *ntlmGen);                      /* RETURNED */
  91
  92 void NtlmGeneratorRelease(
  93         NtlmGeneratorRef        ntlmGen);
  94
  95 /* create the initial client request */
  96 OSStatus NtlmCreateClientRequest(
  97         NtlmGeneratorRef        ntlmGen,
  98         CFDataRef                       *clientRequest);        /* RETURNED */
  99
 100 /* parse server challenge and respond to it */
 101 OSStatus NtlmCreateClientResponse(
 102         NtlmGeneratorRef        ntlmGen,
 103         CFDataRef                       serverBlob,                     /* obtained from the server */
 104         CFStringRef                     domain,                         /* server domain, appears to be optional */
 105         CFStringRef                     userName,
 106         CFStringRef                     password,
 107         CFDataRef                       *clientResponse);   /* RETURNED */
 108
 109 /* which version did we negotiate? */
 110 NLTM_Which NtlmGetNegotiatedVersion(
 111         NtlmGeneratorRef        ntlmGen);
 112
 113 OSStatus NtlmGeneratePasswordHashes(
 114         CFAllocatorRef alloc,
 115         CFStringRef password,
 116         CFDataRef* ntlmHash,
 117         CFDataRef* lmHash);
 118
 119 OSStatus _NtlmCreateClientResponse(
 120         NtlmGeneratorRef        ntlmGen,
 121         CFDataRef                       serverBlob,
 122         CFStringRef                     domain,                         /* optional */
 123         CFStringRef                     userName,
 124         CFDataRef                       ntlmHash,
 125         CFDataRef                       lmHash,
 126         CFDataRef                       *clientResponse);       /* RETURNED */
 127
 128 #ifdef  __cplusplus
 129 }
 130 #endif
 131
 132 #endif  /* _NTLM_GENERATOR_H_ */