public class NtlmSecurityProvider extends SecurityProvider
SecurityProvider implementation of NTLMSSP to initiate and accept NTLMv2 authentication.
The acceptor closely mimics Windows behavior using the NETLOGON service over Secure Channel with AES signing and sealing.
acceptSecContext(byte[], int, int) method of this provider requires that a Computer account be created as described in the Installation section in the Jespa Operator's Manual.
| Name | Description | Example |
|---|---|---|
| bindstr | The servername identifying this provider's authority (such as an Active Directory server). This may also be an LDAP URL. This property is almost always required (see initSecContext for an exception). | dc1.example.com |
| service.acctname | The principal name of a Computer account (qualified with a domain separated by an @ sign) used for authenticating with the provider authority. Note that this cannot be the name of an account used by an actual computer because each computer manages it's own password. | JESPA1$@EXAMPLE.COM |
| service.password | The password corresponding to the service.acctname. This password should be long and random. | a89609c53443ce1c72e59275a8a1e1ce |
| account.canonicalForm | An integer that controls the canonical account name form returned by SecurityProvider.getIdentity(). The default value is 0 to indicate that no canonicalization is necessary.
|
3 |
| flags.integrity | Controls the NTLMSSP signing flags that indicate digital sigatures should be negotiated where possible. The default value is true to indicate that signing should be used. This property is ignored if ntlmssp.flags is set. | |
| flags.confidentiality | Controls the NTLMSSP sealing flags that indicate sealing should be negotiated where possible. The default value is true to indicate that sealing should be used. Setting this property to true will also turn on flags.integrity as sealing requires signing. This property is ignored if ntlmssp.flags is set. | |
| ntlmssp.flags | The NTLMSSP protocol flags. This value is updated with each call to initSecContext to reflect the latest value negotiated with the peer. This value should not be changed and doing so could easily result in failure or undefined behavior. If this property is set, flags.integrity and flags.confidentiality are ignored. | |
| localhost.dns.name | The DNS hostname of this SecurityProvider. The default name is the value returned by InetAddress.getHostName(). |
proton.example.com |
| netlogon.useSealing | Indicates that communication with the the NETLOGON service should be signed but not sealed. The default is true to indicate that Secure Channel sealing should be used. Except for debugging purposes, this setting should never be changed. | |
| netlogon.useSecureChannel | Indicates that communication with the the NETLOGON service should be secured with Secure Channel encryption. The default is true to indicate that Secure Channel should be used.
Note: This property will have no effect without also adding the Computer account to the "Domain controller: Allow vulnerable Netlogon secure channel connections" list.
Use netlogon.useSealing = false instead.
|
|
| The following properties are meant only to be queried. They should not be set. | ||
| domain.netbios.name | The NetBIOS domain name of this provider's authority.
If bindstr, service.acctname and service.password are supplied, this property will be determined automatically at runtime and should not be set.
Note: To retreive the domain name of the current authenticated user, see the
getAccount(java.lang.String, java.lang.String[]) method.
|
EXAMPLE |
| domain.dns.name | The fully qualified domain name (FQDN) of this provider's authority.
If bindstr, service.acctname and service.password are supplied, this property will be determined automatically at runtime and should not be set.
Note: To retreive the domain name of the current authenticated user, see the
getAccount(java.lang.String, java.lang.String[]) method.
|
example.com |
| localhost.netbios.name | DEPRECATED - After MS15-027 / KB3002657, setting this property results in errors. | |
| flags.sequenceDetection | If integrity or confidentiality is negotiated, NTLM supports out-of-sequence detection and therefore this property will almost always be true. Otherwise if integrity or confidentiality has not been negotiated, this property will be false. | |
| ntlmssp.workstation.name | The NetBIOS name of the workstation initiating authentication. This property is only set after calling acceptSecContext with the final NTLMSSP token (such as if isComplete returns true). | |
| ntlmssp.sessionKey | The NTLMSSP session key might be required for certain protocols to implement signing or sealing (using a methods other than those provided by wrap and unwrap). This value is a 16 byte byte[] array and is read-only. | |
| Name | Description | Example |
|---|---|---|
| dns.servers | A comma separated list of IP addresses for Microsoft DNS servers that are authorities for the DNS SRV lookups used to locate AD services. If the current selected server becomes unresponsive, the Jespa DNS logic will transparently fail-over to the next server. | 192.168.10.10,192.168.20.20 |
| dns.site | The Active Directory Sites & Services site that this NTLM service is in. If AD Sites & Services is used, setting this correctly can but crucial for performance.
See the Active Directory Sites & Services section in the Jespa Operator's Manual for details. | Paris |
| jespa.dns.records.path | The path to a DNS records file.
See The DNS Records File section in the Jespa Operator's Manual for details. |
file:/C:\\tomcat\\webapps\\acme\\WEB-INF\\dns.txt |
| dns.cache.ttl | The number of milliseconds that DNS responses should be cached. The default is 5000 (5 seconds). | 60000 |
| authority.dns.names.resolve | A boolean value which if set to false will disable DNS SRV lookups when trying to resolve the bindstr property. If this value is false, the bindstr property must be a fully qualified DNS hostname and not a domain name. | false |
| authority.dns.names.resolve.sld | A boolean value which if set to true will enable resolving of single-lable DNS domain names. The default value is false because single-lable domain names are deprecated. | false |
identity, isComplete| Constructor and Description |
|---|
NtlmSecurityProvider(java.util.Map properties)
See the Properties Overview section for a description of the properties
understood by this security provider.
|
NtlmSecurityProvider(java.util.Map properties,
java.lang.String[] pnames)
See the Properties Overview section for a description of the properties
understood by this security provider.
|
| Modifier and Type | Method and Description |
|---|---|
byte[] |
acceptSecContext(byte[] token,
int off,
int len)
Accept an NTLMSSP token and validate the NTLM "response" supplied by the initiator with the
authenticate(java.lang.Object) method (which by default calls the configured NETLOGON service). |
void |
authenticate(java.lang.Object credential)
Validate a
PasswordCredential or NtlmResponse object with the configured NETLOGON service. |
protected java.lang.Object |
decodeObject(ByteBuffer bb)
Used by importState to decode individual elements of this provider from a ByteBuffer
|
void |
dispose()
Destroy the server challenge and any credential acquired during authentication.
|
protected void |
encodeObject(ByteBuffer bb,
java.lang.Object obj) |
java.lang.Object |
exportState()
Returns a compact byte[] array representing the state of this
security provider.
|
Account |
getAccount(java.lang.String acctname,
java.lang.String[] attrs)
Retrieve an Account object representing the named account and populate it (an Account is also a Map) with the attributes listed in the attrs array.
|
Domain |
getDomain(java.lang.String dname,
java.lang.String[] attrs)
Retrieve a Domain object representing the named domain and populate it (a Domain is also a Map) with the attributes listed in the attrs array.
|
boolean |
getFlag(java.lang.String name)
Retrieve the named security flag as a boolean.
|
java.lang.Object |
getProperty(java.lang.String name,
java.lang.Object def)
Retrieve a property by name or return the supplied default value if the
property is not set.
|
protected byte[] |
getTargetInformation()
Return the NTLMSSP "target information" block used to compute an
NTLM response.
|
void |
importState(java.lang.Object ostate)
Initialize this security provider with a byte[] array returned in a
previous call to
exportState() with another instance of this security provider. |
byte[] |
initSecContext(byte[] token,
int off,
int len)
Initiate NTLM authentication with another peer by exchanging NTLMSSP tokens.
|
boolean |
isComplete()
Used with
SecurityProvider.initSecContext(byte[], int, int) or SecurityProvider.acceptSecContext(byte[], int, int) to determine
if more tokens need to be exchanged. |
void |
setEncryptedProperty(java.lang.String name,
java.lang.String value,
java.lang.Object salt) |
void |
setFlag(java.lang.String name,
boolean value)
Set the named security flag to the supplied value.
|
void |
unwrap(ByteBuffer incoming)
Verify the signature of and possibly decrypt the supplied buffer.
|
void |
wrap(ByteBuffer outgoing)
Sign and possibly encrypt the supplied buffer.
|
getIdentity, getName, setPropertygetEncryptedProperty, getFilteredProperties, getFilteredProperties, getProperty, getPropertyAsBoolean, getPropertyAsLongclear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, valuespublic static final java.lang.String[] KEYS_INIT
public static final java.lang.String[] KEYS_ACCEPT
public static final byte[] SIGNATURE
public static final byte[] Z8
public static final byte[] Z16
public static final byte[] Z24
public static final byte[] VERSION5
public static final byte[] VERSION10
public static final byte[] VERSION
public static final java.lang.String UNI_ENCODING
public static final int NTLMSSP_NEGOTIATE_UNICODE
public static final int NTLMSSP_NEGOTIATE_OEM
public static final int NTLMSSP_REQUEST_TARGET
public static final int NTLMSSP_NEGOTIATE_SIGN
public static final int NTLMSSP_NEGOTIATE_SEAL
public static final int NTLMSSP_NEGOTIATE_LM_KEY
public static final int NTLMSSP_NEGOTIATE_NTLM
public static final int NTLMSSP_NEGOTIATE_OEM_DOMAIN_SUPPLIED
public static final int NTLMSSP_NEGOTIATE_OEM_WORKSTATION_SUPPLIED
public static final int NTLMSSP_NEGOTIATE_ALWAYS_SIGN
public static final int NTLMSSP_TARGET_TYPE_DOMAIN
public static final int NTLMSSP_TARGET_TYPE_SERVER
public static final int NTLMSSP_TARGET_TYPE_SHARE
public static final int NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY
public static final int NTLMSSP_NEGOTIATE_TARGET_INFO
public static final int NTLMSSP_NEGOTIATE_VERSION
public static final int NTLMSSP_NEGOTIATE_128
public static final int NTLMSSP_NEGOTIATE_KEY_EXCH
public static final int NTLMSSP_NEGOTIATE_56
public NtlmSecurityProvider(java.util.Map properties)
properties - the properties that control the behavior of this providerpublic NtlmSecurityProvider(java.util.Map properties,
java.lang.String[] pnames)
throws SecurityProviderException
This constructor is used to create a provider instance from a subset of properties using a list of property names. The provider will be populated with only the properties named in the keys array.
properties - the properties that control the behavior of this providerpnames - a list of property keys used to filter the properties map.SecurityProviderExceptionpublic java.lang.Object getProperty(java.lang.String name,
java.lang.Object def)
throws SecurityProviderException
This method overrides the parent method to perform work specific to this provider including computing default values (such as the localhost.dns.name) and retrieving information from the provider authority (such as the domain.dns.name).
getProperty in class SecurityProvidername - the name of the property to retrieve.def - the default value to return of the named property is not set.SecurityProviderException - if the name is invalid or it's value cannot
be retrieved.public void setEncryptedProperty(java.lang.String name,
java.lang.String value,
java.lang.Object salt)
throws SecurityProviderException
setEncryptedProperty in class jespa.security.PropertiesSecurityProviderExceptionpublic boolean getFlag(java.lang.String name)
throws SecurityProviderException
The following table lists the flags supported by this security provider:
| Name | Description |
|---|---|
| integrity | Indicates as to whether or not wrap and unwrap will use NTLMSSP signing. |
| confidentiality | Indicates as to whether or not wrap and unwrap will use NTLMSSP sealing. |
| sequenceDetection | If integrity or confidentiality is negotiated, wrap and unwrap will use out-of-sequence detection. |
getFlag in class SecurityProvidername - the name of the flag value to retrieve.SecurityProviderExceptionpublic void setFlag(java.lang.String name,
boolean value)
throws SecurityProviderException
getFlag(java.lang.String) method for a list of security flag names recognised by this security provider.setFlag in class SecurityProvidername - the name of the flag to set.value - the new value of the flag.SecurityProviderExceptionprotected void encodeObject(ByteBuffer bb, java.lang.Object obj) throws EncodingException
encodeObject in class jespa.security.PropertiesEncodingExceptionprotected java.lang.Object decodeObject(ByteBuffer bb) throws EncodingException
decodeObject in class jespa.security.PropertiesEncodingExceptionpublic java.lang.Object exportState()
throws SecurityProviderException
This provider may be exported / imported during authentication (meaning between calls to initSecContext or acceptSecContext) but cannot (currently) be exported after calling wrap or unwrap.
exportState in class SecurityProviderSecurityProviderException - if the state could not or cannot be
exported.public void importState(java.lang.Object ostate)
throws SecurityProviderException
exportState() with another instance of this security provider.
The security provider instance must be initialized with the same properties as the exported instance.
importState in class SecurityProviderostate - the byte[] array represeting the state
to be imported.SecurityProviderException - if the state could not be imported such as
because the state being imported has been transferred beyond it's acceptable
boundries.protected byte[] getTargetInformation()
throws SecurityProviderException
authenticate(java.lang.Object) method of a subclass of this provider
that will authenticate clients against a different authority such as
a local database and not just the NETLOGON service. See the
NtlmResponse class description for details.SecurityProviderException - if the data could not be encoded.public byte[] initSecContext(byte[] token,
int off,
int len)
throws SecurityProviderException
See the parent SecurityProvider.initSecContext(byte[], int, int) method for additional instructions.
initSecContext in class SecurityProvidertoken - the buffer containing the NTLMSSP authentication token supplied by the other peer.
The initial token should be an empty byte array (new byte[0]).off - the offset within token to the NTLMSSP token.len - the length of the token within token at offset off.SecurityProviderException - if the operation failed. The exception code will be
SecurityProviderException.STATUS_INVALID_CREDENTIALS
if the other peer did not accept the supplied NTLMSSP token for any reason.public byte[] acceptSecContext(byte[] token,
int off,
int len)
throws SecurityProviderException
authenticate(java.lang.Object) method (which by default calls the configured NETLOGON service).
See the parent SecurityProvider.acceptSecContext(byte[], int, int) method for additional instructions.
acceptSecContext in class SecurityProvidertoken - the buffer containing the NTLMSSP token supplied by the other peer.off - the offset within token to the NTLMSSP token.len - the length of the token within token at offset off.SecurityProviderException - if a catostrophic error occured in processing such as a
network communication failure with the NETLOGON service.public boolean isComplete()
SecurityProviderSecurityProvider.initSecContext(byte[], int, int) or SecurityProvider.acceptSecContext(byte[], int, int) to determine
if more tokens need to be exchanged.isComplete in class SecurityProviderpublic void authenticate(java.lang.Object credential)
throws SecurityProviderException
PasswordCredential or NtlmResponse object with the configured NETLOGON service.
See the parent SecurityProvider.authenticate(java.lang.Object) method for additional instructions.
authenticate in class SecurityProvidercredential - a credential to be validated.SecurityProviderException - if the validation fails. The exception code will be
SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND
if the credential identity was not found by the NETLOGON service or
SecurityProviderException.STATUS_INVALID_CREDENTIALS
if the NETLOGON service indicated that the supplied NTLM hashes were incorrect.public void dispose()
throws SecurityProviderException
dispose in class SecurityProviderSecurityProviderExceptionpublic void wrap(ByteBuffer outgoing) throws SecurityProviderException
wrap in class SecurityProvideroutgoing - the buffer to be processed.SecurityProviderException - if a failure occurs processing the data.public void unwrap(ByteBuffer incoming) throws SecurityProviderException
unwrap in class SecurityProviderincoming - the buffer to be processed.SecurityProviderException - if a failure occurs processing the data.public Domain getDomain(java.lang.String dname, java.lang.String[] attrs) throws SecurityProviderException
If the dname parameter is null the default domain will be returned (the domain of the account identified by the service.acctname property). If the attrs parameter is null, the default attributes domain.dns.name, domain.netbios.name, objectSid and objectGUID will be assumed.
This provider supports the following Domain attributes:
| Key Name | Description | Example |
|---|---|---|
| domain.dns.name | The DNS name of the domain. | example.com |
| domain.netbios.name | The NetBIOS name of the domain | EXAMPLE |
| objectSid | A jespa.util.SID object representing the Windows SID of the domain. | S-1-5-21-2797991279-2260538212-3449501191 |
| objectGUID | A jespa.util.UUID object representing the GUID of the domain. | A66A3172-2D2F-D42C-B331-0CAEC624BBEC |
getDomain in class SecurityProviderdname - the DNS or NetBIOS name of the domain to be retrieved or null to indicate the default domain should be queried.attrs - the names of the attributes to retrieve or null to indicate that the default set of attributes should be queried.SecurityProviderException - if the named domain could not be found or a catostrophic error occured.public Account getAccount(java.lang.String acctname, java.lang.String[] attrs) throws SecurityProviderException
If the acctname parameter is null and this SecurityProvider has been successfully authenticated using either acceptSecContext or authenticate, this method will return an Account corresponding to the authenticated credentials. If the attrs parameter is null, the default attributes sAMAccountName and objectSid will be assumed.
This provider supports the following Account attributes:
| Key Name | Description | Example |
|---|---|---|
| sAMAccountName | The "User login name (pre-Windows 2000)" of the named account. | abaker |
| objectSid | A jespa.util.SID object representing the Windows SID of the account. | S-1-5-21-2797991279-2260538212-3449501191-1234 |
| domain.dns.name |
The DNS domain name of the account which is always included when the Account corresponds to the current authenticated user.
Note: This is not really an attribute (including it in the attrs list will have no effect) but rather a property that is inserted into the Account during authentication.
| busicorp.local |
| domain.netbios.name |
The NetBIOS domain name of the account which is always included when the Account corresponds to the current authenticated user.
Note: This is not really an attribute (including it in the attrs list will have no effect) but rather a property that is inserted into the Account during authentication.
| BUSICORP |
getAccount in class SecurityProvideracctname - the name of the account to retrieve or null to indicate that the account of the authenticated user should be returned (currently this parameter must be null).attrs - the names of the attributes to populate in the Account or null to indicate that the default attriubutes should be queried.SecurityProviderException - if the named account could not be found or a catostrophic error occured.