ntlm-auth
=========
|Build Status|\ |Build status|\ |Coverage Status|
About this library
------------------
This library handles the low-level details of NTLM authentication for
use in authenticating with a service that uses NTLM. It will create and
parse the 3 different message types in the order required and produce a
base64 encoded value that can be attached to the HTTP header.
The goal of this library is to offer full NTLM support including signing
and sealing of messages as well as supporting MIC for message integrity
and the ability to customise and set limits on the messages sent. Please
see Features and Backlog for a list of what is and is not currently
supported.
Features
--------
- LM, NTLM and NTLMv2 authentication
- NTLM1 and NTLM2 extended session security
- Set the The NTLM Compatibility level when sending messages
- Channel Binding Tokens support, need to pass in the SHA256 hash of
the certificate for it to work
- Support for MIC to enhance the integrity of the messages
- Support for session security with signing and sealing messages after
authentication happens
Installation
------------
ntlm-auth supports Python 2.6, 2.7 and 3.3+
To install, use pip:
::
pip install ntlm-auth
To install from source, download the source code, then run:
::
python setup.py install
Usage
-----
Almost all users should use
`requests-ntlm <https://github.com/requests/requests-ntlm>`__ instead of
this library. The library requests-ntlm is a plugin that uses this
library under the hood and provides an easier function to use and
understand.
If you are set on using ntlm-auth directly to compute the message
structures this is a very basic outline of how it can be done. The code
examples are psuedocode and should be adapted for your purpose.
When initliasing the ntlm context you will have to supply the NTLM
compatibility level. The key difference between the different auth
levels are the ntlm_compatibility variable supplied when initialising
Ntlm. An overview of what each sets is below; \* ``0`` - LM Auth and
NTLMv1 Auth \* ``1`` - LM Auth and NTLMv1 Auth with Extended Session
Security (NTLM2) \* ``2`` - NTLMv1 Auth with Extended Session Security
(NTLM2) \* ``3`` - NTLMv2 Auth (Default Choice) \* ``4`` - NTLMv2 Auth
\* ``5`` - NTLMv2 Auth
Level 3 to 5 are the same from a client perspective but differ with how
the server handles the auth which is outside this project’s scope. This
setting is set independently on that server so choosing 3, 4 or 5 when
calling Ntlm will make no difference at all. See
`LmCompatibilityLevel <https://technet.microsoft.com/en-us/library/cc960646.aspx>`__
for more details.
Extended Session Security is a security feature designed to increase the
security of LM and NTLMv1 auth. It is no substitution for NTLMv2 but is
better than nothing and should be used if possible when you need NTLMv1
compatibility.
The variables required are outlined below; \* ``username`` - The
username to authenticate with, should not have the domain prefix,
i.e. USER not DOMAIN\USER \* ``password`` - The password of the user to
authenticate with \* ``domain`` - The domain of the user, i.e. DOMAIN.
Can be blank if not in a domain environment \* ``workstation`` - The
workstation you are running on. Can be blank if you do not wish to send
this \* ``cbt_data`` - (NTLMv2 only) The
``gss_channel_bindings.GssChannelBindingsStruct`` used to bind with the
auth response. Can be None if no binding needs to occur
LM Auth/NTLMv1 Auth
^^^^^^^^^^^^^^^^^^^
LM and NTLMv1 Auth are older authentication methods that should be
avoided where possible. Choosing between these authentication methods
are almost identical expect where you specify the ntlm_compatiblity
level.
.. code:: python
import socket
from ntlm_auth.ntlm import NtlmContext
username = 'User'
password = 'Password'
domain = 'Domain' # Can be blank if you are not in a domain
workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info
ntlm_context = NtlmContext(username, password, domain, workstation, ntlm_compatibility=0) # Put the ntlm_compatibility level here, 0-2 for LM Auth/NTLMv1 Auth
negotiate_message = ntlm_context.step()
# Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server
challenge_message = http.response.headers['HEADERFIELD']
authenticate_message = ntlm_context.step(challenge_message)
# Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1
NTLMv2
^^^^^^
NTLMv2 Auth is the newest NTLM auth method from Microsoft and should be
the option chosen by default unless you require an older auth method.
The implementation is the same as NTLMv1 but with the addition of the
optional ``server_certificate_hash`` variable and the
``ntlm_compatibility`` is not specified.
.. code:: python
import base64
import socket
from ntlm_auth.gss_channel_bindings import GssChannelBindingsStruct
from ntlm_auth.ntlm import NtlmContext
username = 'User'
password = 'Password'
domain = 'Domain' # Can be blank if you are not in a domain
workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info
# create the CBT struct if you wish to bind it with the auth response
server_certificate_hash = '96B2FC1EC30792619286A0C7FD62863E81A6564E72829CBC0A46F7B1D5D92A18'
certificate_digest = base64.b16decode(server_certificate_hash)
cbt_data = GssChannelBindingsStruct()
cbt_data[cbt_data.APPLICATION_DATA] = b'tls-server-end-point:' + certificate_digest
ntlm_context = NtlmContext(username, password, domain, workstation, cbt_data, ntlm_compatibility=3)
negotiate_message = ntlm_context.step()
# Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server
challenge_message = http.response.headers['HEADERFIELD']
authenticate_message = ntlm_context.step(challenge_message)
# Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1
Signing/Sealing
^^^^^^^^^^^^^^^
All version of NTLM supports signing (integrity) and sealing
(confidentiality) of message content. This function can add these
improvements to a message that is sent and received from the server.
While it does encrypt the data if supported by the server it is only
done with RC4 with a 128-bit key which is not very secure and on older
systems this key length could be 56 or 40 bit. This functionality while
tested and conforms with the Microsoft documentation has yet to be fully
tested in an integrated environment. Once again this has not been
thoroughly tested and has only passed unit tests and their expections.
.. code:: python
import base64
import socket
from ntlm_auth.ntlm import NtlmContext
username = 'User'
password = 'Password'
domain = 'Domain' # Can be blank if you are not in a domain
workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info
# create the CBT struct if you wish to bind it with the auth response
server_certificate_hash = '96B2FC1EC30792619286A0C7FD62863E81A6564E72829CBC0A46F7B1D5D92A18'
certificate_digest = base64.b16decode(server_certificate_hash)
cbt_data = GssChannelBindingsStruct()
cbt_data[cbt_data.APPLICATION_DATA] = b'tls-server-end-point:' + certificate_digest
ntlm_context = NtlmContext(username, password, domain, workstation, cbt_data, ntlm_compatibility=3)
negotiate_message = ntlm_context.step()
# Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server
challenge_message = http.response.headers['HEADERFIELD']
authenticate_message = ntlm_context.step(challenge_message)
# Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1
# Encrypt the message with the wrapping function and send the message
enc_message = ntlm_context.wrap("Message to send", encrypt=True)
request.body = msg_data
request.send
# Receive the response from the server and decrypt
response_msg = response.content
response = ntlm_context.unwrap(response_msg)
Backlog
-------
- Automatically get windows version if running on windows, use default
if not that case
- Add param when initialising the ntlm context to throw an exception
and cancel auth if the server doesn’t support 128-bit keys for
sealing
- Add param when initialising the ntlm context to not send the MIC
structure for older servers
- Add param to independently verify the target name returned from the
server and the value passed in
.. |Build Status| image:: https://travis-ci.org/jborean93/ntlm-auth.svg?branch=master
:target: https://travis-ci.org/jborean93/ntlm-auth
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/osvvfgmhfk4anvu0/branch/master?svg=true
:target: https://ci.appveyor.com/project/jborean93/ntlm-auth/branch/master
.. |Coverage Status| image:: https://coveralls.io/repos/github/jborean93/ntlm-auth/badge.svg?branch=master
:target: https://coveralls.io/github/jborean93/ntlm-auth?branch=master
Raw data
{
"_id": null,
"home_page": "https://github.com/jborean93/ntlm-auth",
"name": "ntlm-auth",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.6,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*",
"maintainer_email": "",
"keywords": "authentication auth microsoft ntlm lm",
"author": "Jordan Borean",
"author_email": "jborean93@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/44/a5/ab45529cc1860a1cb05129b438b189af971928d9c9c9d1990b549a6707f9/ntlm-auth-1.5.0.tar.gz",
"platform": "",
"description": "ntlm-auth\n=========\n\n|Build Status|\\ |Build status|\\ |Coverage Status|\n\nAbout this library\n------------------\n\nThis library handles the low-level details of NTLM authentication for\nuse in authenticating with a service that uses NTLM. It will create and\nparse the 3 different message types in the order required and produce a\nbase64 encoded value that can be attached to the HTTP header.\n\nThe goal of this library is to offer full NTLM support including signing\nand sealing of messages as well as supporting MIC for message integrity\nand the ability to customise and set limits on the messages sent. Please\nsee Features and Backlog for a list of what is and is not currently\nsupported.\n\nFeatures\n--------\n\n- LM, NTLM and NTLMv2 authentication\n- NTLM1 and NTLM2 extended session security\n- Set the The NTLM Compatibility level when sending messages\n- Channel Binding Tokens support, need to pass in the SHA256 hash of\n the certificate for it to work\n- Support for MIC to enhance the integrity of the messages\n- Support for session security with signing and sealing messages after\n authentication happens\n\nInstallation\n------------\n\nntlm-auth supports Python 2.6, 2.7 and 3.3+\n\nTo install, use pip:\n\n::\n\n pip install ntlm-auth\n\nTo install from source, download the source code, then run:\n\n::\n\n python setup.py install\n\nUsage\n-----\n\nAlmost all users should use\n`requests-ntlm <https://github.com/requests/requests-ntlm>`__ instead of\nthis library. The library requests-ntlm is a plugin that uses this\nlibrary under the hood and provides an easier function to use and\nunderstand.\n\nIf you are set on using ntlm-auth directly to compute the message\nstructures this is a very basic outline of how it can be done. The code\nexamples are psuedocode and should be adapted for your purpose.\n\nWhen initliasing the ntlm context you will have to supply the NTLM\ncompatibility level. The key difference between the different auth\nlevels are the ntlm_compatibility variable supplied when initialising\nNtlm. An overview of what each sets is below; \\* ``0`` - LM Auth and\nNTLMv1 Auth \\* ``1`` - LM Auth and NTLMv1 Auth with Extended Session\nSecurity (NTLM2) \\* ``2`` - NTLMv1 Auth with Extended Session Security\n(NTLM2) \\* ``3`` - NTLMv2 Auth (Default Choice) \\* ``4`` - NTLMv2 Auth\n\\* ``5`` - NTLMv2 Auth\n\nLevel 3 to 5 are the same from a client perspective but differ with how\nthe server handles the auth which is outside this project\u2019s scope. This\nsetting is set independently on that server so choosing 3, 4 or 5 when\ncalling Ntlm will make no difference at all. See\n`LmCompatibilityLevel <https://technet.microsoft.com/en-us/library/cc960646.aspx>`__\nfor more details.\n\nExtended Session Security is a security feature designed to increase the\nsecurity of LM and NTLMv1 auth. It is no substitution for NTLMv2 but is\nbetter than nothing and should be used if possible when you need NTLMv1\ncompatibility.\n\nThe variables required are outlined below; \\* ``username`` - The\nusername to authenticate with, should not have the domain prefix,\ni.e.\u00a0USER not DOMAIN\\USER \\* ``password`` - The password of the user to\nauthenticate with \\* ``domain`` - The domain of the user, i.e.\u00a0DOMAIN.\nCan be blank if not in a domain environment \\* ``workstation`` - The\nworkstation you are running on. Can be blank if you do not wish to send\nthis \\* ``cbt_data`` - (NTLMv2 only) The\n``gss_channel_bindings.GssChannelBindingsStruct`` used to bind with the\nauth response. Can be None if no binding needs to occur\n\nLM Auth/NTLMv1 Auth\n^^^^^^^^^^^^^^^^^^^\n\nLM and NTLMv1 Auth are older authentication methods that should be\navoided where possible. Choosing between these authentication methods\nare almost identical expect where you specify the ntlm_compatiblity\nlevel.\n\n.. code:: python\n\n import socket\n\n from ntlm_auth.ntlm import NtlmContext\n\n username = 'User'\n password = 'Password'\n domain = 'Domain' # Can be blank if you are not in a domain\n workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info\n\n ntlm_context = NtlmContext(username, password, domain, workstation, ntlm_compatibility=0) # Put the ntlm_compatibility level here, 0-2 for LM Auth/NTLMv1 Auth\n negotiate_message = ntlm_context.step()\n\n # Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server\n challenge_message = http.response.headers['HEADERFIELD']\n\n authenticate_message = ntlm_context.step(challenge_message)\n\n # Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1\n\nNTLMv2\n^^^^^^\n\nNTLMv2 Auth is the newest NTLM auth method from Microsoft and should be\nthe option chosen by default unless you require an older auth method.\nThe implementation is the same as NTLMv1 but with the addition of the\noptional ``server_certificate_hash`` variable and the\n``ntlm_compatibility`` is not specified.\n\n.. code:: python\n\n import base64\n import socket\n\n from ntlm_auth.gss_channel_bindings import GssChannelBindingsStruct\n from ntlm_auth.ntlm import NtlmContext\n\n username = 'User'\n password = 'Password'\n domain = 'Domain' # Can be blank if you are not in a domain\n workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info\n\n # create the CBT struct if you wish to bind it with the auth response\n server_certificate_hash = '96B2FC1EC30792619286A0C7FD62863E81A6564E72829CBC0A46F7B1D5D92A18'\n certificate_digest = base64.b16decode(server_certificate_hash)\n cbt_data = GssChannelBindingsStruct()\n cbt_data[cbt_data.APPLICATION_DATA] = b'tls-server-end-point:' + certificate_digest\n\n ntlm_context = NtlmContext(username, password, domain, workstation, cbt_data, ntlm_compatibility=3)\n negotiate_message = ntlm_context.step()\n\n # Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server\n challenge_message = http.response.headers['HEADERFIELD']\n\n authenticate_message = ntlm_context.step(challenge_message)\n\n # Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1\n\nSigning/Sealing\n^^^^^^^^^^^^^^^\n\nAll version of NTLM supports signing (integrity) and sealing\n(confidentiality) of message content. This function can add these\nimprovements to a message that is sent and received from the server.\nWhile it does encrypt the data if supported by the server it is only\ndone with RC4 with a 128-bit key which is not very secure and on older\nsystems this key length could be 56 or 40 bit. This functionality while\ntested and conforms with the Microsoft documentation has yet to be fully\ntested in an integrated environment. Once again this has not been\nthoroughly tested and has only passed unit tests and their expections.\n\n.. code:: python\n\n import base64\n import socket\n\n from ntlm_auth.ntlm import NtlmContext\n\n username = 'User'\n password = 'Password'\n domain = 'Domain' # Can be blank if you are not in a domain\n workstation = socket.gethostname().upper() # Can be blank if you wish to not send this info\n\n # create the CBT struct if you wish to bind it with the auth response\n server_certificate_hash = '96B2FC1EC30792619286A0C7FD62863E81A6564E72829CBC0A46F7B1D5D92A18'\n certificate_digest = base64.b16decode(server_certificate_hash)\n cbt_data = GssChannelBindingsStruct()\n cbt_data[cbt_data.APPLICATION_DATA] = b'tls-server-end-point:' + certificate_digest\n\n ntlm_context = NtlmContext(username, password, domain, workstation, cbt_data, ntlm_compatibility=3)\n negotiate_message = ntlm_context.step()\n\n # Attach the negotiate_message to your NTLM/NEGOTIATE HTTP header and send to the server. Get the challenge response back from the server\n challenge_message = http.response.headers['HEADERFIELD']\n\n authenticate_message = ntlm_context.step(challenge_message)\n\n # Attach the authenticate_message ot your NTLM_NEGOTIATE HTTP header and send to the server. You are now authenticated with NTLMv1\n\n # Encrypt the message with the wrapping function and send the message\n enc_message = ntlm_context.wrap(\"Message to send\", encrypt=True)\n request.body = msg_data\n request.send\n\n # Receive the response from the server and decrypt\n response_msg = response.content\n response = ntlm_context.unwrap(response_msg)\n\nBacklog\n-------\n\n- Automatically get windows version if running on windows, use default\n if not that case\n- Add param when initialising the ntlm context to throw an exception\n and cancel auth if the server doesn\u2019t support 128-bit keys for\n sealing\n- Add param when initialising the ntlm context to not send the MIC\n structure for older servers\n- Add param to independently verify the target name returned from the\n server and the value passed in\n\n.. |Build Status| image:: https://travis-ci.org/jborean93/ntlm-auth.svg?branch=master\n :target: https://travis-ci.org/jborean93/ntlm-auth\n.. |Build status| image:: https://ci.appveyor.com/api/projects/status/osvvfgmhfk4anvu0/branch/master?svg=true\n :target: https://ci.appveyor.com/project/jborean93/ntlm-auth/branch/master\n.. |Coverage Status| image:: https://coveralls.io/repos/github/jborean93/ntlm-auth/badge.svg?branch=master\n :target: https://coveralls.io/github/jborean93/ntlm-auth?branch=master\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Creates NTLM authentication structures",
"version": "1.5.0",
"split_keywords": [
"authentication",
"auth",
"microsoft",
"ntlm",
"lm"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "736b32afb87d10209c4193894f6ba616",
"sha256": "f1527c581dbf149349134fc2d789d50af2a400e193206956fa0ab456ccc5a8ba"
},
"downloads": -1,
"filename": "ntlm_auth-1.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "736b32afb87d10209c4193894f6ba616",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.6,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*",
"size": 29980,
"upload_time": "2020-06-16T06:26:31",
"upload_time_iso_8601": "2020-06-16T06:26:31.911410Z",
"url": "https://files.pythonhosted.org/packages/ff/84/97c550164b54942b0e908c31ef09d9469f3ba4cd7332a671e2125732f63b/ntlm_auth-1.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e1027e469020190555bb7d08f1bb9481",
"sha256": "c9667d361dc09f6b3750283d503c689070ff7d89f2f6ff0d38088d5436ff8543"
},
"downloads": -1,
"filename": "ntlm-auth-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "e1027e469020190555bb7d08f1bb9481",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.6,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*",
"size": 28872,
"upload_time": "2020-06-16T06:26:34",
"upload_time_iso_8601": "2020-06-16T06:26:34.051825Z",
"url": "https://files.pythonhosted.org/packages/44/a5/ab45529cc1860a1cb05129b438b189af971928d9c9c9d1990b549a6707f9/ntlm-auth-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-06-16 06:26:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jborean93",
"github_project": "ntlm-auth",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"tox": true,
"lcname": "ntlm-auth"
}
JSON
