0
# DNS Resolution
1

2
DNS resolution utilities for service discovery in distributed environments. Provides both A record and SRV record lookups with JNDI-based implementation for resolving hostnames and discovering services.
3

4
**Deprecation Notice**: All DNS resolution APIs are deprecated as of Spring Security 5.6.0 with no replacement.
5

6
## Capabilities
7

8
### DNS Resolver Interface
9

10
Core interface defining DNS resolution operations for both standard hostname resolution and service discovery through SRV records.
11

12
```java { .api }
13
public interface DnsResolver {
14
    /**
15
     * Resolves the IP Address (A record) to the specified host name.
16
     * @param hostname The hostname for which you need the IP Address
17
     * @return IP Address as a String
18
     * @throws DnsEntryNotFoundException No record found
19
     * @throws DnsLookupException Unknown DNS error
20
     */
21
    String resolveIpAddress(String hostname) throws DnsEntryNotFoundException, DnsLookupException;
22

23
    /**
24
     * Resolves the host name for the specified service in the specified domain.
25
     * Uses SRV records to find services, returning the record with highest priority
26
     * (lowest number) and highest weight.
27
     * @param serviceType The service type (e.g. ldap, kerberos)
28
     * @param domain The domain in which to search for the service
29
     * @return The hostname of the service
30
     * @throws DnsEntryNotFoundException No record found
31
     * @throws DnsLookupException Unknown DNS error
32
     */
33
    String resolveServiceEntry(String serviceType, String domain) 
34
        throws DnsEntryNotFoundException, DnsLookupException;
35

36
    /**
37
     * Resolves the host name for the specified service and then the IP Address 
38
     * for this host in one call.
39
     * @param serviceType The service type (e.g. ldap, kerberos)
40
     * @param domain The domain in which to search for the service
41
     * @return IP Address of the service
42
     * @throws DnsEntryNotFoundException No record found
43
     * @throws DnsLookupException Unknown DNS error
44
     */
45
    String resolveServiceIpAddress(String serviceType, String domain)
46
        throws DnsEntryNotFoundException, DnsLookupException;
47
}
48
```
49

50
### JNDI DNS Resolver Implementation
51

52
JNDI-based implementation of DnsResolver using com.sun.jndi.dns.DnsContextFactory for DNS queries. Uses a default InitialContextFactory unless explicitly configured with a custom factory.
53

54
```java { .api }
55
public class JndiDnsResolver implements DnsResolver {
56
    /**
57
     * Allows injection of custom JNDI context factory.
58
     * @param ctxFactory factory to use when a DirContext is needed
59
     */
60
    public void setCtxFactory(InitialContextFactory ctxFactory);
61

62
    /**
63
     * Resolves the host name for the specified service and then the IP Address 
64
     * and port for this host in one call.
65
     * @param serviceType The service type (e.g. ldap, kerberos)
66
     * @param domain The domain in which to search for the service
67
     * @return IP address and port formatted as [ip_address]:[port]
68
     * @throws DnsEntryNotFoundException No record found
69
     * @throws DnsLookupException Unknown DNS error
70
     * @since 5.6
71
     */
72
    public String resolveServiceIpAddressAndPort(String serviceType, String domain);
73
}
74
```
75

76
### Initial Context Factory
77

78
Interface for providing JNDI DirContext instances for DNS queries, allowing custom JNDI configuration.
79

80
```java { .api }
81
public interface InitialContextFactory {
82
    /**
83
     * Must return a DirContext which can be used for DNS queries.
84
     * @return JNDI DirContext
85
     */
86
    DirContext getCtx();
87
}
88
```
89

90
## Usage Examples
91

92
### Basic Hostname Resolution
93

94
```java
95
import org.springframework.security.remoting.dns.JndiDnsResolver;
96
import org.springframework.security.remoting.dns.DnsEntryNotFoundException;
97
import org.springframework.security.remoting.dns.DnsLookupException;
98

99
JndiDnsResolver resolver = new JndiDnsResolver();
100

101
try {
102
    String ipAddress = resolver.resolveIpAddress("example.com");
103
    System.out.println("IP Address: " + ipAddress);
104
} catch (DnsEntryNotFoundException e) {
105
    System.err.println("Host not found: " + e.getMessage());
106
} catch (DnsLookupException e) {
107
    System.err.println("DNS lookup failed: " + e.getMessage());
108
}
109
```
110

111
### Service Discovery with SRV Records
112

113
```java
114
import org.springframework.security.remoting.dns.JndiDnsResolver;
115

116
JndiDnsResolver resolver = new JndiDnsResolver();
117

118
try {
119
    // Find LDAP service in domain
120
    String ldapHost = resolver.resolveServiceEntry("ldap", "example.com");
121
    System.out.println("LDAP Server: " + ldapHost);
122
    
123
    // Get both IP and port in one call (Spring Security 5.6+)
124
    String ldapEndpoint = resolver.resolveServiceIpAddressAndPort("ldap", "example.com");
125
    System.out.println("LDAP Endpoint: " + ldapEndpoint); // e.g., "192.168.1.10:389"
126
    
127
} catch (DnsEntryNotFoundException e) {
128
    System.err.println("Service not found: " + e.getMessage());
129
} catch (DnsLookupException e) {
130
    System.err.println("DNS lookup failed: " + e.getMessage());
131
}
132
```
133

134
### Custom JNDI Context Factory
135

136
```java
137
import org.springframework.security.remoting.dns.JndiDnsResolver;
138
import org.springframework.security.remoting.dns.InitialContextFactory;
139
import javax.naming.Context;
140
import javax.naming.NamingException;
141
import javax.naming.directory.DirContext;
142
import javax.naming.directory.InitialDirContext;
143
import java.util.Hashtable;
144

145
// Custom context factory with specific DNS server
146
InitialContextFactory customFactory = new InitialContextFactory() {
147
    @Override
148
    public DirContext getCtx() {
149
        Hashtable<String, String> env = new Hashtable<>();
150
        env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.dns.DnsContextFactory");
151
        env.put(Context.PROVIDER_URL, "dns://8.8.8.8"); // Use Google DNS
152
        try {
153
            return new InitialDirContext(env);
154
        } catch (NamingException ex) {
155
            throw new DnsLookupException("Cannot create InitialDirContext", ex);
156
        }
157
    }
158
};
159

160
JndiDnsResolver resolver = new JndiDnsResolver();
161
resolver.setCtxFactory(customFactory);
162

163
String ipAddress = resolver.resolveIpAddress("example.com");
164
```
165

166
## SRV Record Format
167

168
When using service discovery, DNS server must provide SRV records in the format:
169
```
170
_service._tcp.domain IN SRV priority weight port target
171
```
172

173
Example:
174
```
175
_ldap._tcp.example.com IN SRV 10 0 389 ldap.example.com.
176
```
177

178
The resolver returns the record with highest priority (lowest number) and if there are multiple records with the same priority, it returns the one with the highest weight.
179

180
## Exception Handling
181

182
```java { .api }
183
public class DnsLookupException extends RuntimeException {
184
    public DnsLookupException(String msg);
185
    public DnsLookupException(String msg, Throwable cause);
186
}
187

188
public class DnsEntryNotFoundException extends DnsLookupException {
189
    public DnsEntryNotFoundException(String msg);
190
    public DnsEntryNotFoundException(String msg, Throwable cause);
191
}
192
```
193

194
- **DnsLookupException**: Thrown for unknown DNS errors, network issues, or JNDI problems
195
- **DnsEntryNotFoundException**: Thrown when no DNS entry matches the specified query (extends DnsLookupException)