Re-wrap markdown files

Signed-off-by: Graham <gpe@openrs2.org>
Graham 4 years ago
parent 2549c84028
commit ef152afab4
  1. 20
      CONTRIBUTING.md
  2. 16
      README.md
  3. 4
      share/doc/client-parameters.md
  4. 22
      share/doc/cryptography.md
  5. 21
      share/doc/faq.md
  6. 47
      share/doc/protocol/login.md
  7. 20
      share/doc/protocol/overview.md
  8. 10
      share/doc/reference-counting.md

@ -3,16 +3,16 @@
## Introduction
OpenRS2 is still in the early stages of development. The current focus is on
building underlying infrastructure, such as the deobfuscator, rather than
game content. This approach will make it much quicker to build game content in
the long run, but it does mean OpenRS2 won't be particularly useful in the short
building underlying infrastructure, such as the deobfuscator, rather than game
content. This approach will make it much quicker to build game content in the
long run, but it does mean OpenRS2 won't be particularly useful in the short
term.
If you're interested in contributing new features, you should discuss your
plans in our [Discord][discord] server first. I have rough plans in my head for
the future development direction. Communicating beforehand will avoid the need
for significant changes to be made at the code review stage and make it less
likely for your contribution to be dropped entirely.
If you're interested in contributing new features, you should discuss your plans
in our [Discord][discord] server first. I have rough plans in my head for the
future development direction. Communicating beforehand will avoid the need for
significant changes to be made at the code review stage and make it less likely
for your contribution to be dropped entirely.
## Code style
@ -43,8 +43,8 @@ commit history is tidy.
OpenRS2 uses version 1.1 of the [Developer Certificate of Origin][dco] (DCO) to
certify that contributors agree to license their code under OpenRS2's license
(see the License section below). To confirm that a contribution meets the
requirements of the DCO, a `Signed-off-by:` line must be added to the Git
commit message by passing `--signoff` to the `git commit` invocation.
requirements of the DCO, a `Signed-off-by:` line must be added to the Git commit
message by passing `--signoff` to the `git commit` invocation.
If you intend to make a large number of contributions, run the following
commands from the repository root to add `Signed-off-by:` line to all your

@ -4,9 +4,9 @@
## Introduction
OpenRS2 is an open-source multiplayer game server and suite of associated
tools. It is compatible with build 550 of the RuneScape client, which was
released in late 2009.
OpenRS2 is an open-source multiplayer game server and suite of associated tools.
It is compatible with build 550 of the RuneScape client, which was released in
late 2009.
## Prerequisites
@ -20,8 +20,8 @@ on JDK-only tools, such as `jarsigner`, at runtime.
OpenRS2 requires the original RuneScape client code, data and location file
encryption keys, which we cannot legally distribute.
These files must be manually placed in the `nonfree` directory (directly
beneath the root of the repository), in the following structure:
These files must be manually placed in the `nonfree` directory (directly beneath
the root of the repository), in the following structure:
```
nonfree
@ -69,9 +69,9 @@ File -> Settings -> Build, Execution and Deployment -> Compiler. See
## License
OpenRS2 is available under the terms of the [ISC license][isc], which is
similar to the 2-clause BSD license. The full copyright notice and terms are
available in the `LICENSE` file.
OpenRS2 is available under the terms of the [ISC license][isc], which is similar
to the 2-clause BSD license. The full copyright notice and terms are available
in the `LICENSE` file.
[discord-badge]: https://img.shields.io/discord/684495254145335298
[discord]: https://chat.openrs2.org/

@ -63,8 +63,8 @@ applet. All other parameters are optional.
| 0 | RuneScape | `game0` |
| 1 | MechScape/Stellar Dawn | `game1` |
At the time 550 was released, MechScape used the same engine as RuneScape.
While changing the parameter affects the client in a small number of ways, the
At the time 550 was released, MechScape used the same engine as RuneScape. While
changing the parameter affects the client in a small number of ways, the
majority of differences between the two games is in the cache.
When `game1` is used, the following changes are made in the client:

@ -6,13 +6,13 @@
combining its output with addition/subtraction, the client uses it as a stream
cipher to encrypt the opcodes of packets.
It was implemented to break packet injection bots, such as AutoRune. While
using ISAAC in this manner only provides confidentiality, and not authenticity
or integrity, if the opcodes are tampered with the packet lengths will no
longer be in sync between the client and server. This causes one or both of the
endpoints to read garbage opcodes, though the garbage opcodes may happen to
match valid packets for a while. Eventually, one or both endpoints will detect
an invalid packet and close the connection.
It was implemented to break packet injection bots, such as AutoRune. While using
ISAAC in this manner only provides confidentiality, and not authenticity or
integrity, if the opcodes are tampered with the packet lengths will no longer be
in sync between the client and server. This causes one or both of the endpoints
to read garbage opcodes, though the garbage opcodes may happen to match valid
packets for a while. Eventually, one or both endpoints will detect an invalid
packet and close the connection.
## RSA
@ -26,8 +26,8 @@ cache, ensuring that Jagex's code-signed applet could not be used to run
arbitrary native code if an attacker tampers with the JS5 connection. This
change was probably required by Jagex's certificate authority.
Jagex used a 512-bit RSA key when build 550 was released, and due to the size
of the output buffer in the client, the maximum key size is 1,008 bits. Both of
Jagex used a 512-bit RSA key when build 550 was released, and due to the size of
the output buffer in the client, the maximum key size is 1,008 bits. Both of
these sizes are considered insecure by modern standards, and Jagex's 512-bit
private key was factored in 2016.
@ -61,8 +61,8 @@ directly by Jagex's 512-bit RSA key.
## Whirlpool
[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in
build 550, however, it is included here for completeness as it is supported by
[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in build
550, however, it is included here for completeness as it is supported by
OpenRS2's cache library. It is used to verify the integrity of native libraries
stored in the cache.

@ -24,11 +24,11 @@ There are a mixture of reasons:
* Availability of the original native libraries. I struggled to find the
original native libraries for 550, except for 32-bit Windows. While Linux and
macOS natives are available for nearby revisions, they are not compatible
with the 550 client.
* The original native libraries were not built for 64-bit Linux and macOS.
While this was probably not a major problem in 2009, 64-bit architectures are
now the norm.
macOS natives are available for nearby revisions, they are not compatible with
the 550 client.
* The original native libraries were not built for 64-bit Linux and macOS. While
this was probably not a major problem in 2009, 64-bit architectures are now
the norm.
* Non-x86 architectures like ARM and RISC-V are becoming more popular. If we
start seeing a shift away from x86 on desktop machines, the native libraries
will need to be built for those architectures.
@ -38,9 +38,9 @@ There are a mixture of reasons:
* I anticipate that at some point in the future the Linux AWT implementation
will be ported from X11 to Wayland, which will require porting the jaggl
native library from GLX to EGL.
* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan
might eventually necessitate the inclusion of OpenGL to Metal/Vulkan
translation layers.
* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan might
eventually necessitate the inclusion of OpenGL to Metal/Vulkan translation
layers.
* I'm concerned about backwards compatibility and bit rot. The original native
libraries were compiled 10 years ago, and at some point one of their
dependencies might drop backwards binary compatibility.
@ -50,8 +50,7 @@ There are a mixture of reasons:
Even though OpenRS2 does not distribute Jagex's intellectual property, there is
a risk that it could be taken down from a service like GitHub by mistake,
causing disruption. Running our own infrastructure allows us to keep backups of
data not held in the Git repository, such as issues. If necessary, we can
switch to a different hosting provider at short notice while retaining such
data.
data not held in the Git repository, such as issues. If necessary, we can switch
to a different hosting provider at short notice while retaining such data.
[nar-maven-plugin]: https://maven-nar.github.io/

@ -20,10 +20,10 @@ packets in a loop, rather than only permitting a single login packet to be sent
during the handshake process, which is how most current private servers are
currently implemented.
For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed
by an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully
switch to JS5 mode, even though this is not the normal sequence of packets sent
by the client.
For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed by
an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully switch
to JS5 mode, even though this is not the normal sequence of packets sent by the
client.
### 14 (`INIT_GAME_CONNECTION`)
@ -68,9 +68,9 @@ hash to load balance between login servers, but this has not been confirmed.
| Byte\[n\] | RSA-encrypted payload |
The unknown byte hard-coded to `0` in a client script might represent the
language. It is consistent with the ID for English. We can infer that there
were language-specific versions of the cache, as the surviving copy does not
contain translations.
language. It is consistent with the ID for English. We can infer that there were
language-specific versions of the cache, as the surviving copy does not contain
translations.
The structure of the plaintext payload is described below:
@ -255,8 +255,8 @@ your Message Centre for details.
### 5 (`DUPLICATE`)
**Message:** Your account has not logged out from its last session. Try again
in a few minutes.
**Message:** Your account has not logged out from its last session. Try again in
a few minutes.
### 6 (`CLIENT_OUT_OF_DATE`)
@ -294,29 +294,30 @@ subscribe or use a different world.
### 14 (`UPDATE_IN_PROGRESS`)
**Message:** The server is being updated. Please wait a few minutes and try again.
**Message:** The server is being updated. Please wait a few minutes and try
again.
### 15 (`RECONNECT_OK`)
### 16 (`TOO_MANY_ATTEMPTS`)
**Message:** Too many incorrect logins from your address. Please wait 5 minutes before
trying again.
**Message:** Too many incorrect logins from your address. Please wait 5 minutes
before trying again.
### 17 (Account in members-only area)
**Message:** You are standing in a members-only area. To play on this world, move to a free
area first.
**Message:** You are standing in a members-only area. To play on this world,
move to a free area first.
### 18 (`LOCKED`)
**Message:** Your account has been locked as we suspect it has been stolen. Click here to
recover your account.
**Message:** Your account has been locked as we suspect it has been stolen.
Click here to recover your account.
### 19 (Fullscreen is members-only)
**Message:** Fullscreen is currently a members-only feature. To log in, either return to the
main menu and exit fullscreen or use a members' account.
**Message:** Fullscreen is currently a members-only feature. To log in, either
return to the main menu and exit fullscreen or use a members' account.
### 20 (Invalid login server requested)
@ -328,8 +329,8 @@ main menu and exit fullscreen or use a members' account.
|--------------|-------------------------|
| UnsignedByte | Hop time |
**Message:** You have only just left another world. Your profile will be transferred in <n>
seconds.
**Message:** You have only just left another world. Your profile will be
transferred in <n> seconds.
The number of remaining seconds is calculated using the following formula:
(hopTime * 60 + 180) / 50
@ -348,11 +349,13 @@ The number of remaining seconds is calculated using the following formula:
### 25 (`UNKNOWN_REPLY_FROM_LOGINSERVER`)
**Message:** Unexpected loginserver response. Please try using a different world.
**Message:** Unexpected loginserver response. Please try using a different
world.
### 26 (`IP_BLOCKED`)
**Message:** This comptuer's address has been blocked as it was used to break our rules.
**Message:** This comptuer's address has been blocked as it was used to break
our rules.
### 27 (Service unavailable)

@ -3,14 +3,14 @@
The RuneScape protocol runs on top of the [Transmission Control Protocol
(TCP)][tcp]. As TCP is stream-oriented, a framing scheme is required to
determine where one packet ends and where the next begins. RuneScape primarily
uses a [type-length-value (TLV)][tlv] scheme for framing, though some
exceptions do exist - for example, the JAGGRAB and JS5 protocols use different
framing schemes.
uses a [type-length-value (TLV)][tlv] scheme for framing, though some exceptions
do exist - for example, the JAGGRAB and JS5 protocols use different framing
schemes.
A RuneScape connection may be in several states, each of which has a different
set of opcodes (types in TLV parlance). Opcodes may have different meanings in
different states. Opcodes may be optionally encrypted with the [ISAAC stream
cipher][isaac].
different states. Opcodes may be optionally encrypted with
the [ISAAC stream cipher][isaac].
All connections start in the [login](login.md) state.
@ -52,13 +52,13 @@ They are structured as follows:
## Opcode encryption
Opcodes are encrypted by adding the opcode to the next 32-bit output from the
ISAAC random number generator and truncating the result to 8 bits. Decryption
is the same process in reverse: the 32-bit output is subtracted from the
encrypted opcode, and then the result is truncated to 8 bits.
ISAAC random number generator and truncating the result to 8 bits. Decryption is
the same process in reverse: the 32-bit output is subtracted from the encrypted
opcode, and then the result is truncated to 8 bits.
There are two ISAAC random number generators: one used for upstream (client ->
server) traffic and one used for downstream (server -> client) traffic. Both
are initialised with a seed consisting of four 32-bit integers.
server) traffic and one used for downstream (server -> client) traffic. Both are
initialised with a seed consisting of four 32-bit integers.
The upstream seed is the same as the downstream seed, except each integer
component is incremented by 50.

@ -1,7 +1,7 @@
# Reference counting
[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s.
The Netty documentation explains its
[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. The
Netty documentation explains its
[use of reference counting][netty-ref-counting] in more detail.
OpenRS2 has an extension method that automatically wraps a block of code in a
@ -39,9 +39,9 @@ alloc.buffer().use { buf ->
If any of the code prior to the `return` fails, the buffer is released.
If the `return` is reached, no more exceptions can occur. The reference count
is increased to counteract the `finally` block decreasing it, such that by the
time the buffer reaches the caller its reference count is 1.
If the `return` is reached, no more exceptions can occur. The reference count is
increased to counteract the `finally` block decreasing it, such that by the time
the buffer reaches the caller its reference count is 1.
[netty]: https://netty.io/
[netty-ref-counting]: https://netty.io/wiki/reference-counted-objects.html

Loading…
Cancel
Save