Skip to content

Commit 1c244f6

Browse files
ibauersachsibauersachs
committed
Reorganize the readme
- Serializable updates for #242 - History on GitHub is not so important anymore, move it down - Update links to RFCs - Improve doc about the SPI
1 parent f4f563b commit 1c244f6

File tree

1 file changed

+40
-26
lines changed

1 file changed

+40
-26
lines changed

‎README.adoc‎

Lines changed: 40 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -5,28 +5,16 @@ image:https://codecov.io/gh/dnsjava/dnsjava/branch/master/graph/badge.svg?token=
55
image:https://maven-badges.herokuapp.com/maven-central/dnsjava/dnsjava/badge.svg["Maven Central",link="https://search.maven.org/artifact/dnsjava/dnsjava"]
66
image:https://javadoc.io/badge/dnsjava/dnsjava.svg["Javadocs",link="https://javadoc.io/doc/dnsjava/dnsjava"]
77

8-
98
== Overview
109

1110
dnsjava is an implementation of DNS in Java.
12-
It supports almost all defined record types (including the DNSSEC types), and unknown types.
13-
It can be used for queries, zone transfers, and dynamic updates.
14-
It includes a cache which can be used by clients, and an authoritative only server.
15-
It supports TSIG authenticated messages, partial DNSSEC verification, and EDNS0. It is fully thread safe.
16-
17-
dnsjava was started as an excuse to learn Java.
18-
It was useful for testing new features in BIND without rewriting the C resolver.
19-
It was then cleaned up and extended in order to be used as a testing framework for DNS interoperability testing.
20-
The high level API and caching resolver were added to make it useful to a wider audience.
21-
The authoritative only server was added as proof of concept.
22-
23-
== dnsjava on Github
11+
It
2412

25-
This repository has been a mirror of the dnsjava project at Sourceforge since 2014 to maintain the Maven build for publishing to https://search.maven.org/artifact/dnsjava/dnsjava[Maven Central].
26-
As of 2019-05-15, GitHub is https://sourceforge.net/p/dnsjava/mailman/message/36666800/[officially] the new home of dnsjava.
27-
28-
Please use the GitHub https://github.com/dnsjava/dnsjava/issues[issue tracker] and send - well tested - pull requests.
29-
The mailto:dnsjava-users@lists.sourceforge.net[dnsjava-users] mailing list still exists.
13+
* supports almost all defined record types (including the DNSSEC types), and unknown types.
14+
* can be used for queries, zone transfers, and dynamic updates.
15+
* includes a cache which can be used by clients, and an authoritative only server.
16+
* supports TSIG authenticated messages, DNSSEC verification, and EDNS0.
17+
* is fully thread safe.
3018

3119
== Getting started
3220

@@ -127,7 +115,7 @@ Do NOT use it.
127115
|5000
128116

129117
.2+|org.jitsi.dnssec.nsec3.iterations.N
130-
3+a|Maximum iteration count for the NSEC3 hashing function depending on the key size N. The defaults are from https://tools.ietf.org/html/rfc5155#section-10.3[RFC5155].
118+
3+a|Maximum iteration count for the NSEC3 hashing function depending on the key size N. The defaults are from https://www.rfc-editor.org/rfc/rfc5155.html#section-10.3[RFC5155].
131119
|Integer
132120
2+a|- 1024 bit keys: 150 iterations
133121
- 2048 bit keys: 500 iterations
@@ -166,15 +154,15 @@ If `false`, allows any algorithm to validate the zone.
166154
.2+|dnsjava.dnssec.algorithm_enabled.ID
167155
3+|Enable or disable a DS/DNSKEY algorithm.
168156
See
169-
https://tools.ietf.org/html/rfc8624#section-3.1[RFC8624] for recommended values.
157+
https://www.rfc-editor.org/rfc/rfc8624.html#section-3.1[RFC8624] for recommended values.
170158
|Boolean
171159
2+|Disable ED448:
172160
`dnsjava.dnssec.algorithm_enabled.16=false`
173161

174162
.2+|dnsjava.dnssec.digest_enabled.ID
175163
3+|Enable or disable a DS record digest algorithm.
176164
See
177-
https://tools.ietf.org/html/rfc8624#section-3.3[RFC8624] for recommended values.
165+
https://www.rfc-editor.org/rfc/rfc8624.html#section-3.3[RFC8624] for recommended values.
178166
|Boolean
179167
2+|Disable SHA.1:
180168
`dnsjava.dnssec.digest_enabled.1=false`
@@ -224,6 +212,7 @@ To migrate from dnssecjava, replace `org.jitsi` with `org.xbill.DNS` in Java pac
224212
Validated, secure responses contain the DNS `AD`-flag, while responses that failed validation return the `SERVFAIL`-RCode.
225213
Insecure responses return the actual return code without the `AD`-flag set.
226214
The reason why the validation failed or is insecure is provided as a localized string in the additional section under the record ./65280/TXT (a TXT record for the owner name of the root zone in the private query class `ValidatingResolver.VALIDATION_REASON_QCLASS`).
215+
The Extended DNS Errors (EDE, https://www.rfc-editor.org/rfc/rfc8914.html[RFC8914]) also provides the failure reason, although in less detail.
227216

228217
The link:EXAMPLES.md[examples] contain a small demo.
229218

@@ -269,27 +258,36 @@ Use the new versions with
269258
* The type hierarchy of `SMIMEARecord` changed, it now inherits from
270259
`TLSARecord` and constants are shared
271260

272-
* ``Record``s are no longer marked as `Serializable`.
273-
Use the RFC defined serialization formats:
261+
* ``Record``s are no longer marked as `Serializable` after 3.0.
262+
While 3.5 reintroduced `Serializable`, it is preferred to use the RFC defined serialization formats directly:
274263
** `toString()`, `rrToString()` ↔ `fromString()`
275264
** `toWire()` ↔ `fromWire()`, `newRecord()`
276265

277266
* `Message` and `Header` properly support `clone()`
278267

279268
=== Replacing the standard Java DNS functionality
280269

281-
Java versions from 1.4 to 8 can load DNS service providers at runtime.
282-
The functionality was https://bugs.openjdk.java.net/browse/JDK-8134577[removed in JDK 9], a replacement is https://bugs.openjdk.java.net/browse/JDK-8192780[requested], but so far only a https://bugs.openjdk.java.net/browse/JDK-8263693[proposal]
283-
has been defined.
270+
==== Java 1.4 to 8
284271

272+
Java versions from 1.4 to 8 can load DNS service providers at runtime.
285273
To load the dnsjava service provider, build dnsjava on JDK 8 and set the system property:
286274

287275
sun.net.spi.nameservice.provider.1=dns,dnsjava
288276

289277
This instructs the JVM to use the dnsjava service provide for DNS at the highest priority.
290278

279+
==== Java 9 to 17
280+
281+
The functionality to load a DNS SPI was https://bugs.openjdk.java.net/browse/JDK-8134577[removed in JDK 9] and a replacement API was https://bugs.openjdk.java.net/browse/JDK-8192780[requested].
282+
283+
==== Java 18+
284+
285+
https://bugs.openjdk.java.net/browse/JDK-8263693[JEP 418: Internet-Address Resolution SPI] reintroduces a DNS SPI.
286+
See https://github.com/dnsjava/dnsjava/issues/245[#245] for the support status in dnsjava.
287+
291288
=== Build
292289

290+
dnsjava uses https://maven.apache.org/[Maven] as the build system.
293291
Run `mvn package` from the toplevel directory to build dnsjava.
294292
JDK 8 or higher is required.
295293

@@ -327,6 +325,22 @@ See the link:EXAMPLES.md[examples] for some basic usage information.
327325

328326
dnsjava is placed under the link:LICENSE[BSD-3-Clause license].
329327

328+
== History
329+
330+
dnsjava was started as an excuse to learn Java.
331+
It was useful for testing new features in BIND without rewriting the C resolver.
332+
It was then cleaned up and extended in order to be used as a testing framework for DNS interoperability testing.
333+
The high level API and caching resolver were added to make it useful to a wider audience.
334+
The authoritative only server was added as proof of concept.
335+
336+
=== dnsjava on GitHub
337+
338+
This repository has been a mirror of the dnsjava project at Sourceforge since 2014 to maintain the Maven build for publishing to https://search.maven.org/artifact/dnsjava/dnsjava[Maven Central].
339+
As of 2019-05-15, GitHub is https://sourceforge.net/p/dnsjava/mailman/message/36666800/[officially] the new home of dnsjava.
340+
The mailto:dnsjava-users@lists.sourceforge.net[dnsjava-users] mailing list (https://sourceforge.net/p/dnsjava/mailman/dnsjava-users/[archive]) still exists but is mostly inactive.
341+
342+
Please use the GitHub https://github.com/dnsjava/dnsjava/issues[issue tracker] and send - well tested - pull requests.
343+
330344
== Authors
331345

332346
- Brian Wellington (@bwelling), March 12, 2004

0 commit comments

Comments
 (0)