1 ;;; url-http-ntlm.el --- NTLM authentication for the url library
3 ;; Copyright (C) 2008, 2015 Free Software Foundation, Inc.
5 ;; Author: Tom Schutzer-Weissmann <tom.weissmann@gmail.com>
6 ;; Maintainer: Thomas Fitzsimmons <fitzsim@fitzsim.org>
7 ;; Keywords: comm, data, processes, hypermedia
9 ;; This program is free software; you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; This program is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
24 ;; This package provides a NTLM handler for the URL package.
25 ;; It supports one username and password per server.
29 ;; M-x package-install RET url-http-ntlm RET
33 ;; Taro Kawagishi <tarok@transpulse.org> wrote ntlm.el and md4.el,
34 ;; which are parts of FLIM (Faithful Library about Internet Message).
36 ;; http://stuff.mit.edu/afs/sipb/contrib/emacs/packages/flim-1.14.7/ntlm.el
37 ;; http://stuff.mit.edu/afs/sipb/contrib/emacs/packages/flim-1.14.7/md4.el
46 ;; Remove authorization after redirect.
47 (when (and (boundp 'emacs-major-version)
48 (< emacs-major-version 25))
49 (require (intern (format "url-http-ntlm-parse-headers-%d.%d"
51 emacs-minor-version))))
54 ;;; Private variables.
55 (defvar url-http-ntlm--auth-storage nil
56 "Authentication storage.
57 An alist that maps a server name to a pair of \(<username> <ntlm
60 The hashes are built using `ntlm-get-password-hashes'.
61 The username can contain the domain name, in the form \"user@domain\".
63 Note that for any server, only one user and password is ever stored.")
65 (defvar url-http-ntlm--last-args nil
66 "Stores the last `url-http-ntlm--get-stage' arguments and return value.
67 This is used to detect multiple calls.")
68 (make-variable-buffer-local 'url-http-ntlm--last-args)
71 ;;; Private functions.
72 (defun url-http-ntlm--ensure-keepalive ()
73 "Report an error if `url-http-attempt-keepalives' is not set."
74 (cl-assert url-http-attempt-keepalives
76 (concat "NTLM authentication won't work unless"
77 " `url-http-attempt-keepalives' is set!")))
79 (defun url-http-ntlm--clean-headers ()
80 "Remove Authorization element from `url-http-extra-headers' alist."
81 (setq url-http-extra-headers
82 (url-http-ntlm--rmssoc "Authorization" url-http-extra-headers)))
84 (defun url-http-ntlm--get-stage (args)
85 "Determine what stage of the NTLM handshake we are at.
86 PROMPT and ARGS come from `url-ntlm-auth''s caller,
87 `url-get-authentication'. Their meaning depends on the current
88 implementation - this function is well and truly coupled.
90 url-get-authentication' calls `url-ntlm-auth' once when checking
91 what authentication schemes are supported (PROMPT and ARGS are
92 nil), and then twice for every stage of the handshake: the first
93 time PROMPT is nil, the second, t; ARGS contains the server
94 response's \"WWW-Authenticate\" header, munged by
96 (let* ((response-rxp "^NTLM TlRMTVNTUAADAAA")
97 (challenge-rxp "^TLRMTVNTUAACAAA")
98 (auth-header (assoc "Authorization" url-http-extra-headers))
101 (if (eq args (car url-http-ntlm--last-args))
102 ;; multiple calls, return the same argument we returned last time
103 (cdr url-http-ntlm--last-args)
105 (cond ((and auth-header (string-match response-rxp
108 ((and (= (length args) 2)
109 (cl-destructuring-bind (challenge ntlm) args
110 (and (string-equal "ntlm" (car ntlm))
111 (string-match challenge-rxp
116 (url-http-ntlm--clean-headers)
117 (setq url-http-ntlm--last-args (cons args stage))
120 (defun url-http-ntlm--authorisation (url &optional clear)
121 "Get or clear NTLM authentication details for URL.
122 If CLEAR is non-nil, clear any saved credentials for server.
123 Otherwise, return the credentials, prompting the user if
126 If URL contains a username and a password, they are used and
127 stored credentials are not affected.
129 Note that for any server, only one user and password is ever
131 (let* ((href (if (stringp url)
132 (url-generic-parse-url url)
134 (server (url-host href))
135 (user (url-user href))
136 (pass (url-password href))
137 (stored (assoc server url-http-ntlm--auth-storage))
138 (both (and user pass)))
142 (setq url-http-ntlm--auth-storage
143 (url-http-ntlm--rmssoc server url-http-ntlm--auth-storage))
147 (and stored user (not (equal user (cl-second stored))))
149 (let* ((user* (if both
151 (read-string (url-auth-user-prompt url realm)
152 (or user (user-real-login-name)))))
155 (read-passwd "Password: ")))
156 (entry `(,server . (,user*
157 ,(ntlm-get-password-hashes pass*)))))
159 (setq url-http-ntlm--auth-storage
161 (url-http-ntlm--rmssoc server
162 url-http-ntlm--auth-storage))))
166 (defun url-http-ntlm--get-challenge ()
167 "Return the NTLM Type-2 message in the WWW-Authenticate header, if present."
169 (mail-narrow-to-head)
170 (let ((www-authenticate (mail-fetch-field "www-authenticate")))
171 (when (string-match "NTLM\\s-+\\(\\S-+\\)"
173 (base64-decode-string (match-string 1 www-authenticate))))))
175 (defun url-http-ntlm--rmssoc (key alist)
176 "Remove all elements whose `car' match KEY from ALIST."
177 (cl-remove key alist :key 'car :test 'equal))
179 (defun url-http-ntlm--string (data)
180 "Return DATA encoded as an NTLM string."
181 (concat "NTLM " (base64-encode-string data :nobreak)))
184 ;;; Public function called by `url-get-authentication'.
185 (defun url-ntlm-auth (url &optional prompt overwrite realm args)
186 "Return an NTLM HTTP authorization header.
187 Get the contents of the Authorization header for a HTTP response
188 using NTLM authentication, to access URL. Because NTLM is a
189 two-step process, this function expects to be called twice, first
190 to generate the NTLM type 1 message (request), then to respond to
191 the server's type 2 message (challenge) with a suitable response.
193 PROMPT, OVERWRITE, and REALM are ignored.
195 ARGS is expected to contain the WWW-Authentication header from
196 the server's last response. These are used by
197 `url-http-get-stage' to determine what stage we are at."
198 (url-http-ntlm--ensure-keepalive)
199 (let ((stage (url-http-ntlm--get-stage args)))
201 ;; NTLM Type 1 message: the request
203 (cl-destructuring-bind (&optional server user hash)
204 (url-http-ntlm--authorisation url)
206 (url-http-ntlm--string
207 (ntlm-build-auth-request user server)))))
208 ;; NTLM Type 3 message: the response
210 (let ((challenge (url-http-ntlm--get-challenge)))
211 (cl-destructuring-bind (server user hash)
212 (url-http-ntlm--authorisation url)
213 (url-http-ntlm--string
214 (ntlm-build-auth-response challenge
218 (url-http-ntlm--authorisation url :clear)))))
221 ;;; Register `url-ntlm-auth' HTTP authentication method.
222 (url-register-auth-scheme "ntlm" nil 8)
224 (provide 'url-http-ntlm)
226 ;;; url-http-ntlm.el ends here