Milestone 7: Release readiness

CONTRIBUTING.md

@@ -0,0 +1,4 @@
+# Contribution Guide
+
+The Contribution Guide for the SCION project can be found
+[here](https://docs.scion.org/en/latest/dev/contribute.html).

README.md

@@ -1,17 +1,42 @@
 
 
-***Under construction. Do not use.***
-
-***Under construction. Do not use.***
-
-***Under construction. Do not use.***
+***Not officially released yet***
 
 # SCION Java client
 
-A Java client for [SCION](https://scion.org).
-
+This library is pure Java network stack for using [SCION](https://scion.org). More information about SCION can be found [here](https://docs.scion.org).
+It provides functionality similar to 
+[snet (golang)](https://pkg.go.dev/github.com/scionproto/scion/pkg/snet),
+[PAN (golang)](https://pkg.go.dev/github.com/netsec-ethz/scion-apps/pkg/pan) and 
+[scion-rs (Rust)](https://github.com/MystenLabs/scion-rs). 
+
+### Planned features
+- `DatagramSocket` and `DatagramPacket`
+- `Selector` for `DatagramChannel`
+- Path creation with short-cuts, on-path and peering routes
+- `/etc/scion/hosts` and `/etc/hosts`, see https://github.com/netsec-ethz/scion-apps
+- Improve docs, demos and testing
+- EPIC, path authentication and other SCION features
+- TCP
+- Many more
+
+### WARNING
 This client can directly connect to SCION **without dispatcher**.
 
+Currently (January 2024), the SCION system uses a "dispatcher" (a process that runs on endhosts,
+listens on a fixed port (30041) and forwards any incoming SCION packets, after stripping the SCION 
+header, to local application).
+
+This Java client cannot be used with a dispatcher.
+The Java client can be used in one of the following ways:
+- You can use the client stand-alone (without local SCION installation),
+  however it must listen on port 30041 for incoming SCION packets because
+  SCION routers currently will forward data only to that port. 
+- If you need a local SCION installation (Go implementation),
+  consider using the dispatch-off branch/PR.
+- When you need to run a local system with dispatcher, you can try to use port forwarding
+  to forward incoming data your Java application port. The application port must not be 30041.
+
 ## API
 
 The central classes of the API are:
@@ -75,8 +100,89 @@ try (DatagramChannel channel = DatagramChannel.open()) {
 }
 ```
 
+### Demos
+
+Some demos can be found in [src/test/java/org/scion/demo](src/test/java/org/scion/demo).
+
+- `DatagramChannel` ping pong [client](src/test/java/org/scion/demo/ScionPingPongChannelClient.java) 
+  and [server](src/test/java/org/scion/demo/ScionPingPongChannelServer.java)
+- [SCMP echo](src/test/java/org/scion/demo/ScmpEchoDemo.java)
+- [SCMP traceroute](src/test/java/org/scion/demo/ScmpTracerouteDemo.java)
+
+
+### General documentation
+
+
+- Reference manual: https://docs.scion.org
+- Reference implementation of SCION: https://github.com/scionproto/scion
+- SCIONLab, a global testbed for SCION applications: https://www.scionlab.org/
+- Awesome SCION, a collection of SCION projects: https://github.com/scionproto/awesome-scion 
+
+### Real world testing and evaluation
+
+The JUnit tests in this Java project use a very rudimentary simulated network.
+For proper testing it is recommended to use one of the following:
+
+- [scionproto](https://github.com/scionproto/scion), the reference implementation of SCION, comes 
+  with a framework that allows defining a topology and running a local network with daemons, control 
+  servers, border routers and more, see [docs](https://docs.scion.org/en/latest/dev/run.html).
+- [SCIONlab](https://www.scionlab.org/) is a world wide testing framework for SCION. You can define your own AS
+  and use the whole network. It runs as overlay over normal internet so it has limited 
+  security guarantees and possibly reduced performance compared to native SCION.
+- [SCIERA](https://sciera.readthedocs.io/) is a network of Universities with SCION connection. It is part
+  part of the global SCION  network
+- [EDGE](https://docs.anapaya.net/en/latest/getting-started/aws/) on [AWS](https://aws.amazon.com/de/blogs/alps/connecting-scion-networks-to-aws-environments/) offers SCION node in some countries. 
+  These are also connected to the global SCION network.
+
+
+
 ## DatagramChannel
 
+### Destinations
+In order to find a path to a destination IP, a `DatagramChannel` or `DatagramSocket` must know the 
+ISD/AS numbers of the destination.
+
+
+If the destination host has a DNS TXT entry for SCION then this be used to determine the 
+destination ISD/AS.
+Alternatively, the ISD/AS can be specified explicitly.
+
+#### DNS lookup
+```
+$ dig TXT ethz.ch
+...
+ethz.ch.		610	IN	TXT	"scion=64-2:0:9,129.132.230.98"
+...
+```
+
+```
+InetSocketAddress serverAddress = new InetSocketAddress("ethz.ch", 80);​
+channel.connect(serverAddress);
+```
+
+
+#### Explicit ISD/AS specification
+
+We can use the ISD/AS directly to request a path:
+```
+long isdAs = ScionUtil.parseIA("64-2:0:9");
+InetSocketAddress serverAddress = new InetSocketAddress("129.132.19.216", 80);​
+Path path = Scion.defaultService().getPaths(isdAs, serverAddress).get(0);
+channel.connect(path);
+```
+
+
+### Demo application - ping pong
+
+There is a simple ping pong client-server application in `src/test/demo`.
+
+It has some hardcoded ports/IP so it works only with the scionLab tiny.topo and only with the dispatcher-free
+version of scionLab: https://github.com/scionproto/scion/pull/4344
+
+The client and server connects directly to the border router (without dispatcher).
+
+The server is located in `1-ff00:0:112` (IP `[::1]:44444`). The client is located in `1-ff00:0:110`.
+
 ### Options
 
 Options are defined in `ScionSocketOptions`, see javadoc for details.
@@ -97,23 +203,7 @@ Options are defined in `ScionSocketOptions`, see javadoc for details.
   Solution: always use the latest path returned by send, e.g. `path = send(buffer, path)`.
 
 - **Using expired path (server).** When using `send(buffer, path)` with an expired `ResponsePath`, the channel will
-  simple send it anyway (could just drop it) TODO
-  -> Callback?
-  - TODO request new path a few seconds in advance on client side?    
-
-
-
-## Demo application - ping pong
-
-There is a simple ping pong client-server application in `src/test/demo`.
-
-It has some hardcoded ports/IP so it works only with the scionlab tiny.topo and only with the dispatcher-free
-version of scionlab: https://github.com/scionproto/scion/pull/4344
-
-The client and server connects directly to the border router (without dispatcher).
-
-The server is located in `1-ff00:0:112` (IP [::1]:44444). The client is located in `1-ff00:0:110`.
-
+  simple send it anyway.
 
 ## Configuration
 
@@ -132,13 +222,13 @@ attempt to get network information in the following order until it succeeds:
 The reason that the daemon is checked last is that it has a default setting (localhost:30255) while
 the other options are skipped if no property or environment variable is defined. 
 
-| Option                              | Java property                     | Environment variable         | Default value |
-|-------------------------------------|-----------------------------------|------------------------------|---------------|
-| Daemon host                         | `org.scion.daemon.host`           | `SCION_DAEMON_HOST`          | localhost     |
-| Daemon port                         | `org.scion.daemon.port`           | `SCION_DAEMON_PORT`          | 30255         | 
-| Bootstrap topology file path        | `org.scion.bootstrap.topoFile`    | `SCION_BOOTSTRAP_TOPO_FILE`  |               | 
-| Bootstrap server host               | `org.scion.bootstrap.host`        | `SCION_BOOTSTRAP_HOST`       |               |
-| Bootstrap DNS NAPTR entry host name | `org.scion.bootstrap.naptr.name ` | `SCION_BOOTSTRAP_NAPTR_NAME` |               | 
+| Option                              | Java property                    | Environment variable         | Default value |
+|-------------------------------------|----------------------------------|------------------------------|---------------|
+| Daemon host                         | `org.scion.daemon.host`          | `SCION_DAEMON_HOST`          | localhost     |
+| Daemon port                         | `org.scion.daemon.port`          | `SCION_DAEMON_PORT`          | 30255         | 
+| Bootstrap topology file path        | `org.scion.bootstrap.topoFile`   | `SCION_BOOTSTRAP_TOPO_FILE`  |               | 
+| Bootstrap server host               | `org.scion.bootstrap.host`       | `SCION_BOOTSTRAP_HOST`       |               |
+| Bootstrap DNS NAPTR entry host name | `org.scion.bootstrap.naptr.name` | `SCION_BOOTSTRAP_NAPTR_NAME` |               | 
 
 ### Other
 
@@ -148,6 +238,16 @@ the other options are skipped if no property or environment variable is defined.
 
 ## FAQ / trouble shooting
 
+### Local testbed (scionproto) does not contain any path
+
+A common problem is that the certificates of the testbed have expired (default validity: 3 days).
+The certificates can be renewed by recreating the network with 
+`./scion.sh topology -c <your_topology_here.topo>`.
+
+### ERROR: "TRC NOT FOUND"
+This error occurs when requesting a path with an ISD/AS code that is not
+known in the network.
+
 ### Cannot find symbol javax.annotation.Generated
 
 ```
@@ -160,3 +260,7 @@ Compilation failure: Compilation failure:
 This can be fixed by building with Java JDK 1.8.
 
 
+## License
+
+This project is licensed under the Apache License, Version 2.0 
+(see [LICENSE](LICENSE) or https://www.apache.org/licenses/LICENSE-2.0).

TODO.md

@@ -77,6 +77,14 @@
   - E.g. MTU exceeded, path expired, checksum problem, "destination unreachable"
   - Handle Scion's "no path found" with NoRouteToHost?.>!?!?
   - Test!
+  - BUG: Ping to iaOVGU causes 3 CS requests that have type UP,CORE,CORE....?
+  - FIX: Ask why requesting an UP segment effectively returns a DOWN segment
+    (it needs to be reversed + the SegID needs to be XORed)
+- FIX: Document or improve ERROR: "TRC NOT FOUND" when requesting path to non-existing AS (down segment?) 
+- Document:local scionproto-network returns no path -> recreate with -c topology!
+- Docs:
+  https://github.com/marcfrei/scion-time#setting-up-a-scion-test-environment
+  https://github.com/netsec-ethz/lightning-filter#develop
 Discuss required for 0.1.0:
 - SCMP errors handling (above)
   - Especially for expired paths / revoked paths / broken paths?  
@@ -91,7 +99,7 @@ Discuss required for 0.1.0:
 - Selector support
   - Implement interfaces from nio.DatagramChannel
   - Look into Selectors:  https://www.baeldung.com/java-nio-selector
-- Consider SHIM support. SHIM is a compatbility component that supports
+- Consider SHIM support. SHIM is a compatibility component that supports
   old border-router software (requiring a fixed port on the client, unless
   the client is listening on this very port).  When SHIM is used, we cannot 
   get the return address (server mode) from the received packet because we receive it 
@@ -112,8 +120,13 @@ Discuss required for 0.1.0:
 - Make ScionService AutoCloseable? -> Avoid separate CloseableService class and it's usage in try().
 - Convenience: Implement Transparent service that tries SCION and, if not available,
   returns a normal Java UDP DatagramChannel? Which Interface?
+- Transparent fallback to plain IP if target is in same AS?
 - https for topology server?
 - Secure DNS requests?
+- Reconsider handling of expired path on server side. Try requesting a new path?
+  Throw exception? Callback?
+- Make multi-module project for demos & inspector (also channel vs socket?)
+  -> see JDO for releasing only some modules for a release.
 
 ### 0.3.0
 - SCMP info handling: ping, traceroute, ...

doc/Design.md

@@ -8,6 +8,11 @@ We should look at other custom Java protocol implementations, e.g. for QUIC:
 ## Daemon
 The implementation can use the daemon. Alternatively, since daemon installation may
 be cumbersome on platforms such as Android, we can directly connect to a control service.
+An alternative for mobile devices could be a non-local daemon that is hosted by the mobile provider.
+This may work but may open opportunities for sid-channel attacks on the daemon.
+Also, when roaming, the provider may not actually support SCION. In this case the
+device would need to connect to some kind of gateway to connect to either a daemon or
+at least a topology server + control server.
 
 ## Library dependencies etc