1 /*
2 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.util.Arrays;
29 import java.util.Enumeration;
30 import java.util.NoSuchElementException;
31 import java.util.Spliterator;
32 import java.util.Spliterators;
33 import java.util.stream.Stream;
34 import java.util.stream.StreamSupport;
35
36 /**
37 * This class represents a Network Interface made up of a name,
38 * and a list of IP addresses assigned to this interface.
39 * It is used to identify the local interface on which a multicast group
40 * is joined.
41 *
42 * Interfaces are normally known by names such as "le0".
43 *
44 * @since 1.4
45 */
46 public final class NetworkInterface {
47 private String name;
48 private String displayName;
49 private int index;
50 private InetAddress addrs[];
51 private InterfaceAddress bindings[];
52 private NetworkInterface childs[];
53 private NetworkInterface parent = null;
54 private boolean virtual = false;
55 private static final NetworkInterface defaultInterface;
56 private static final int defaultIndex; /* index of defaultInterface */
57
58 static {
59 sun.security.action.LoadLibraryAction.privilegedLoadLibrary("net");
60
61 init();
62 defaultInterface = DefaultInterface.getDefault();
63 if (defaultInterface != null) {
64 defaultIndex = defaultInterface.getIndex();
65 } else {
66 defaultIndex = 0;
67 }
68 }
69
70 /**
71 * Returns an NetworkInterface object with index set to 0 and name to null.
72 * Setting such an interface on a MulticastSocket will cause the
73 * kernel to choose one interface for sending multicast packets.
74 *
75 */
76 NetworkInterface() {
77 }
78
79 NetworkInterface(String name, int index, InetAddress[] addrs) {
80 this.name = name;
81 this.index = index;
82 this.addrs = addrs;
83 }
84
85 /**
86 * Get the name of this network interface.
87 *
88 * @return the name of this network interface
89 */
90 public String getName() {
91 return name;
92 }
93
94 /**
95 * Get an Enumeration with all or a subset of the InetAddresses bound to
96 * this network interface.
97 * <p>
98 * If there is a security manager, its {@code checkConnect}
99 * method is called for each InetAddress. Only InetAddresses where
100 * the {@code checkConnect} doesn't throw a SecurityException
101 * will be returned in the Enumeration. However, if the caller has the
102 * {@link NetPermission}("getNetworkInformation") permission, then all
103 * InetAddresses are returned.
104 *
105 * @return an Enumeration object with all or a subset of the InetAddresses
106 * bound to this network interface
107 * @see #inetAddresses()
108 */
109 public Enumeration<InetAddress> getInetAddresses() {
110 return enumerationFromArray(getCheckedInetAddresses());
111 }
112
113 /**
114 * Get a Stream of all or a subset of the InetAddresses bound to this
115 * network interface.
116 * <p>
117 * If there is a security manager, its {@code checkConnect}
118 * method is called for each InetAddress. Only InetAddresses where
119 * the {@code checkConnect} doesn't throw a SecurityException will be
120 * returned in the Stream. However, if the caller has the
121 * {@link NetPermission}("getNetworkInformation") permission, then all
122 * InetAddresses are returned.
123 *
124 * @return a Stream object with all or a subset of the InetAddresses
125 * bound to this network interface
126 * @since 9
127 */
128 public Stream<InetAddress> inetAddresses() {
129 return streamFromArray(getCheckedInetAddresses());
130 }
131
132 private InetAddress[] getCheckedInetAddresses() {
133 InetAddress[] local_addrs = new InetAddress[addrs.length];
134 boolean trusted = true;
135
136 SecurityManager sec = System.getSecurityManager();
137 if (sec != null) {
138 try {
139 sec.checkPermission(new NetPermission("getNetworkInformation"));
140 } catch (SecurityException e) {
141 trusted = false;
142 }
143 }
144 int i = 0;
145 for (int j = 0; j < addrs.length; j++) {
146 try {
147 if (!trusted) {
148 sec.checkConnect(addrs[j].getHostAddress(), -1);
149 }
150 local_addrs[i++] = addrs[j];
151 } catch (SecurityException e) { }
152 }
153 return Arrays.copyOf(local_addrs, i);
154 }
155
156 /**
157 * Get a List of all or a subset of the {@code InterfaceAddresses}
158 * of this network interface.
159 * <p>
160 * If there is a security manager, its {@code checkConnect}
161 * method is called with the InetAddress for each InterfaceAddress.
162 * Only InterfaceAddresses where the {@code checkConnect} doesn't throw
163 * a SecurityException will be returned in the List.
164 *
165 * @return a {@code List} object with all or a subset of the
166 * InterfaceAddress of this network interface
167 * @since 1.6
168 */
169 public java.util.List<InterfaceAddress> getInterfaceAddresses() {
170 java.util.List<InterfaceAddress> lst = new java.util.ArrayList<>(1);
171 if (bindings != null) {
172 SecurityManager sec = System.getSecurityManager();
173 for (int j=0; j<bindings.length; j++) {
174 try {
175 if (sec != null) {
176 sec.checkConnect(bindings[j].getAddress().getHostAddress(), -1);
177 }
178 lst.add(bindings[j]);
179 } catch (SecurityException e) { }
180 }
181 }
182 return lst;
183 }
184
185 /**
186 * Get an Enumeration with all the subinterfaces (also known as virtual
187 * interfaces) attached to this network interface.
188 * <p>
189 * For instance eth0:1 will be a subinterface to eth0.
190 *
191 * @return an Enumeration object with all of the subinterfaces
192 * of this network interface
193 * @see #subInterfaces()
194 * @since 1.6
195 */
196 public Enumeration<NetworkInterface> getSubInterfaces() {
197 return enumerationFromArray(childs);
198 }
199
200 /**
201 * Get a Stream of all subinterfaces (also known as virtual
202 * interfaces) attached to this network interface.
203 *
204 * @return a Stream object with all of the subinterfaces
205 * of this network interface
206 * @since 9
207 */
208 public Stream<NetworkInterface> subInterfaces() {
209 return streamFromArray(childs);
210 }
211
212 /**
213 * Returns the parent NetworkInterface of this interface if this is
214 * a subinterface, or {@code null} if it is a physical
215 * (non virtual) interface or has no parent.
216 *
217 * @return The {@code NetworkInterface} this interface is attached to.
218 * @since 1.6
219 */
220 public NetworkInterface getParent() {
221 return parent;
222 }
223
224 /**
225 * Returns the index of this network interface. The index is an integer greater
226 * or equal to zero, or {@code -1} for unknown. This is a system specific value
227 * and interfaces with the same name can have different indexes on different
228 * machines.
229 *
230 * @return the index of this network interface or {@code -1} if the index is
231 * unknown
232 * @see #getByIndex(int)
233 * @since 1.7
234 */
235 public int getIndex() {
236 return index;
237 }
238
239 /**
240 * Get the display name of this network interface.
241 * A display name is a human readable String describing the network
242 * device.
243 *
244 * @return a non-empty string representing the display name of this network
245 * interface, or null if no display name is available.
246 */
247 public String getDisplayName() {
248 /* strict TCK conformance */
249 return "".equals(displayName) ? null : displayName;
250 }
251
252 /**
253 * Searches for the network interface with the specified name.
254 *
255 * @param name
256 * The name of the network interface.
257 *
258 * @return A {@code NetworkInterface} with the specified name,
259 * or {@code null} if there is no network interface
260 * with the specified name.
261 *
262 * @throws SocketException
263 * If an I/O error occurs.
264 *
265 * @throws NullPointerException
266 * If the specified name is {@code null}.
267 */
268 public static NetworkInterface getByName(String name) throws SocketException {
269 if (name == null)
270 throw new NullPointerException();
271 return getByName0(name);
272 }
273
274 /**
275 * Get a network interface given its index.
276 *
277 * @param index an integer, the index of the interface
278 * @return the NetworkInterface obtained from its index, or {@code null} if
279 * there is no interface with such an index on the system
280 * @throws SocketException if an I/O error occurs.
281 * @throws IllegalArgumentException if index has a negative value
282 * @see #getIndex()
283 * @since 1.7
284 */
285 public static NetworkInterface getByIndex(int index) throws SocketException {
286 if (index < 0)
287 throw new IllegalArgumentException("Interface index can't be negative");
288 return getByIndex0(index);
289 }
290
291 /**
292 * Convenience method to search for a network interface that
293 * has the specified Internet Protocol (IP) address bound to
294 * it.
295 * <p>
296 * If the specified IP address is bound to multiple network
297 * interfaces it is not defined which network interface is
298 * returned.
299 *
300 * @param addr
301 * The {@code InetAddress} to search with.
302 *
303 * @return A {@code NetworkInterface}
304 * or {@code null} if there is no network interface
305 * with the specified IP address.
306 *
307 * @throws SocketException
308 * If an I/O error occurs.
309 *
310 * @throws NullPointerException
311 * If the specified address is {@code null}.
312 */
313 public static NetworkInterface getByInetAddress(InetAddress addr) throws SocketException {
314 if (addr == null) {
315 throw new NullPointerException();
316 }
317
318 if (addr.holder.family == InetAddress.IPv4) {
319 if (!(addr instanceof Inet4Address)) {
320 throw new IllegalArgumentException("invalid family type: "
321 + addr.holder.family);
322 }
323 } else if (addr.holder.family == InetAddress.IPv6) {
324 if (!(addr instanceof Inet6Address)) {
325 throw new IllegalArgumentException("invalid family type: "
326 + addr.holder.family);
327 }
328 } else {
329 throw new IllegalArgumentException("invalid address type: " + addr);
330 }
331 return getByInetAddress0(addr);
332 }
333
334 /**
335 * Returns an {@code Enumeration} of all the interfaces on this machine. The
336 * {@code Enumeration} contains at least one element, possibly representing
337 * a loopback interface that only supports communication between entities on
338 * this machine.
339 *
340 * @apiNote this method can be used in combination with
341 * {@link #getInetAddresses()} to obtain all IP addresses for this node
342 *
343 * @return an Enumeration of NetworkInterfaces found on this machine
344 * @throws SocketException if an I/O error occurs,
345 * or if the platform does not have at least one configured
346 * network interface.
347 * @see #networkInterfaces()
348 */
349 public static Enumeration<NetworkInterface> getNetworkInterfaces()
350 throws SocketException {
351 NetworkInterface[] netifs = getAll();
352 if (netifs != null && netifs.length > 0) {
353 return enumerationFromArray(netifs);
354 } else {
355 throw new SocketException("No network interfaces configured");
356 }
357 }
358
359 /**
360 * Returns a {@code Stream} of all the interfaces on this machine. The
361 * {@code Stream} contains at least one interface, possibly representing a
362 * loopback interface that only supports communication between entities on
363 * this machine.
364 *
365 * @apiNote this method can be used in combination with
366 * {@link #inetAddresses()}} to obtain a stream of all IP addresses for
367 * this node, for example:
368 * <pre> {@code
369 * Stream<InetAddress> addrs = NetworkInterface.networkInterfaces()
370 * .flatMap(NetworkInterface::inetAddresses);
371 * }</pre>
372 *
373 * @return a Stream of NetworkInterfaces found on this machine
374 * @throws SocketException if an I/O error occurs,
375 * or if the platform does not have at least one configured
376 * network interface.
377 * @since 9
378 */
379 public static Stream<NetworkInterface> networkInterfaces()
380 throws SocketException {
381 NetworkInterface[] netifs = getAll();
382 if (netifs != null && netifs.length > 0) {
383 return streamFromArray(netifs);
384 } else {
385 throw new SocketException("No network interfaces configured");
386 }
387 }
388
389 /**
390 * Checks if the given address is bound to any of the interfaces on this
391 * machine.
392 *
393 * @param addr
394 * The {@code InetAddress} to search with.
395 * @return true iff the addr parameter is currently bound to one of
396 * the interfaces on this machine.
397 *
398 * @throws SocketException
399 * If an I/O error occurs.
400 */
401 /* package-private */ static boolean isBoundInetAddress(InetAddress addr)
402 throws SocketException {
403 return boundInetAddress0(addr);
404 }
405
406 private static <T> Enumeration<T> enumerationFromArray(T[] a) {
407 return new Enumeration<>() {
408 int i = 0;
409
410 @Override
411 public T nextElement() {
412 if (i < a.length) {
413 return a[i++];
414 } else {
415 throw new NoSuchElementException();
416 }
417 }
418
419 @Override
420 public boolean hasMoreElements() {
421 return i < a.length;
422 }
423 };
424 }
425
426 private static <T> Stream<T> streamFromArray(T[] a) {
427 return StreamSupport.stream(
428 Spliterators.spliterator(
429 a,
430 Spliterator.DISTINCT | Spliterator.IMMUTABLE | Spliterator.NONNULL),
431 false);
432 }
433
434 private static native NetworkInterface[] getAll()
435 throws SocketException;
436
437 private static native NetworkInterface getByName0(String name)
438 throws SocketException;
439
440 private static native NetworkInterface getByIndex0(int index)
441 throws SocketException;
442
443 private static native boolean boundInetAddress0(InetAddress addr)
444 throws SocketException;
445
446 private static native NetworkInterface getByInetAddress0(InetAddress addr)
447 throws SocketException;
448
449 /**
450 * Returns whether a network interface is up and running.
451 *
452 * @return {@code true} if the interface is up and running.
453 * @throws SocketException if an I/O error occurs.
454 * @since 1.6
455 */
456
457 public boolean isUp() throws SocketException {
458 return isUp0(name, index);
459 }
460
461 /**
462 * Returns whether a network interface is a loopback interface.
463 *
464 * @return {@code true} if the interface is a loopback interface.
465 * @throws SocketException if an I/O error occurs.
466 * @since 1.6
467 */
468
469 public boolean isLoopback() throws SocketException {
470 return isLoopback0(name, index);
471 }
472
473 /**
474 * Returns whether a network interface is a point to point interface.
475 * A typical point to point interface would be a PPP connection through
476 * a modem.
477 *
478 * @return {@code true} if the interface is a point to point
479 * interface.
480 * @throws SocketException if an I/O error occurs.
481 * @since 1.6
482 */
483
484 public boolean isPointToPoint() throws SocketException {
485 return isP2P0(name, index);
486 }
487
488 /**
489 * Returns whether a network interface supports multicasting or not.
490 *
491 * @return {@code true} if the interface supports Multicasting.
492 * @throws SocketException if an I/O error occurs.
493 * @since 1.6
494 */
495
496 public boolean supportsMulticast() throws SocketException {
497 return supportsMulticast0(name, index);
498 }
499
500 /**
501 * Returns the hardware address (usually MAC) of the interface if it
502 * has one and if it can be accessed given the current privileges.
503 * If a security manager is set, then the caller must have
504 * the permission {@link NetPermission}("getNetworkInformation").
505 *
506 * @return a byte array containing the address, or {@code null} if
507 * the address doesn't exist, is not accessible or a security
508 * manager is set and the caller does not have the permission
509 * NetPermission("getNetworkInformation")
510 *
511 * @throws SocketException if an I/O error occurs.
512 * @since 1.6
513 */
514 public byte[] getHardwareAddress() throws SocketException {
515 SecurityManager sec = System.getSecurityManager();
516 if (sec != null) {
517 try {
518 sec.checkPermission(new NetPermission("getNetworkInformation"));
519 } catch (SecurityException e) {
520 if (!getInetAddresses().hasMoreElements()) {
521 // don't have connect permission to any local address
522 return null;
523 }
524 }
525 }
526 for (InetAddress addr : addrs) {
527 if (addr instanceof Inet4Address) {
528 return getMacAddr0(((Inet4Address)addr).getAddress(), name, index);
529 }
530 }
531 return getMacAddr0(null, name, index);
532 }
533
534 /**
535 * Returns the Maximum Transmission Unit (MTU) of this interface.
536 *
537 * @return the value of the MTU for that interface.
538 * @throws SocketException if an I/O error occurs.
539 * @since 1.6
540 */
541 public int getMTU() throws SocketException {
542 return getMTU0(name, index);
543 }
544
545 /**
546 * Returns whether this interface is a virtual interface (also called
547 * subinterface).
548 * Virtual interfaces are, on some systems, interfaces created as a child
549 * of a physical interface and given different settings (like address or
550 * MTU). Usually the name of the interface will the name of the parent
551 * followed by a colon (:) and a number identifying the child since there
552 * can be several virtual interfaces attached to a single physical
553 * interface.
554 *
555 * @return {@code true} if this interface is a virtual interface.
556 * @since 1.6
557 */
558 public boolean isVirtual() {
559 return virtual;
560 }
561
562 private static native boolean isUp0(String name, int ind) throws SocketException;
563 private static native boolean isLoopback0(String name, int ind) throws SocketException;
564 private static native boolean supportsMulticast0(String name, int ind) throws SocketException;
565 private static native boolean isP2P0(String name, int ind) throws SocketException;
566 private static native byte[] getMacAddr0(byte[] inAddr, String name, int ind) throws SocketException;
567 private static native int getMTU0(String name, int ind) throws SocketException;
568
569 /**
570 * Compares this object against the specified object.
571 * The result is {@code true} if and only if the argument is
572 * not {@code null} and it represents the same NetworkInterface
573 * as this object.
574 * <p>
575 * Two instances of {@code NetworkInterface} represent the same
576 * NetworkInterface if both name and addrs are the same for both.
577 *
578 * @param obj the object to compare against.
579 * @return {@code true} if the objects are the same;
580 * {@code false} otherwise.
581 * @see java.net.InetAddress#getAddress()
582 */
583 public boolean equals(Object obj) {
584 if (!(obj instanceof NetworkInterface)) {
585 return false;
586 }
587 NetworkInterface that = (NetworkInterface)obj;
588 if (this.name != null ) {
589 if (!this.name.equals(that.name)) {
590 return false;
591 }
592 } else {
593 if (that.name != null) {
594 return false;
595 }
596 }
597
598 if (this.addrs == null) {
599 return that.addrs == null;
600 } else if (that.addrs == null) {
601 return false;
602 }
603
604 /* Both addrs not null. Compare number of addresses */
605
606 if (this.addrs.length != that.addrs.length) {
607 return false;
608 }
609
610 InetAddress[] thatAddrs = that.addrs;
611 int count = thatAddrs.length;
612
613 for (int i=0; i<count; i++) {
614 boolean found = false;
615 for (int j=0; j<count; j++) {
616 if (addrs[i].equals(thatAddrs[j])) {
617 found = true;
618 break;
619 }
620 }
621 if (!found) {
622 return false;
623 }
624 }
625 return true;
626 }
627
628 public int hashCode() {
629 return name == null? 0: name.hashCode();
630 }
631
632 public String toString() {
633 String result = "name:";
634 result += name == null? "null": name;
635 if (displayName != null) {
636 result += " (" + displayName + ")";
637 }
638 return result;
639 }
640
641 private static native void init();
642
643 /**
644 * Returns the default network interface of this system
645 *
646 * @return the default interface
647 */
648 static NetworkInterface getDefault() {
649 return defaultInterface;
650 }
651 }