Re-wrap markdown files

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

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

@ -63,8 +63,8 @@ applet. All other parameters are optional.
| 0 | RuneScape | `game0` | | 0 | RuneScape | `game0` |
| 1 | MechScape/Stellar Dawn | `game1` | | 1 | MechScape/Stellar Dawn | `game1` |
At the time 550 was released, MechScape used the same engine as RuneScape. At the time 550 was released, MechScape used the same engine as RuneScape. While
While changing the parameter affects the client in a small number of ways, the changing the parameter affects the client in a small number of ways, the
majority of differences between the two games is in the cache. majority of differences between the two games is in the cache.
When `game1` is used, the following changes are made in the client: 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 combining its output with addition/subtraction, the client uses it as a stream
cipher to encrypt the opcodes of packets. cipher to encrypt the opcodes of packets.
It was implemented to break packet injection bots, such as AutoRune. While It was implemented to break packet injection bots, such as AutoRune. While using
using ISAAC in this manner only provides confidentiality, and not authenticity ISAAC in this manner only provides confidentiality, and not authenticity or
or integrity, if the opcodes are tampered with the packet lengths will no integrity, if the opcodes are tampered with the packet lengths will no longer be
longer be in sync between the client and server. This causes one or both of the in sync between the client and server. This causes one or both of the endpoints
endpoints to read garbage opcodes, though the garbage opcodes may happen to to read garbage opcodes, though the garbage opcodes may happen to match valid
match valid packets for a while. Eventually, one or both endpoints will detect packets for a while. Eventually, one or both endpoints will detect an invalid
an invalid packet and close the connection. packet and close the connection.
## RSA ## 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 arbitrary native code if an attacker tampers with the JS5 connection. This
change was probably required by Jagex's certificate authority. 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 Jagex used a 512-bit RSA key when build 550 was released, and due to the size of
of the output buffer in the client, the maximum key size is 1,008 bits. Both 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 these sizes are considered insecure by modern standards, and Jagex's 512-bit
private key was factored in 2016. private key was factored in 2016.
@ -61,8 +61,8 @@ directly by Jagex's 512-bit RSA key.
## Whirlpool ## Whirlpool
[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in [Whirlpool][whirlpool] is a cryptographic hash function. It is not used in build
build 550, however, it is included here for completeness as it is supported by 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 OpenRS2's cache library. It is used to verify the integrity of native libraries
stored in the cache. 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 * Availability of the original native libraries. I struggled to find the
original native libraries for 550, except for 32-bit Windows. While Linux and original native libraries for 550, except for 32-bit Windows. While Linux and
macOS natives are available for nearby revisions, they are not compatible macOS natives are available for nearby revisions, they are not compatible with
with the 550 client. the 550 client.
* The original native libraries were not built for 64-bit Linux and macOS. * The original native libraries were not built for 64-bit Linux and macOS. While
While this was probably not a major problem in 2009, 64-bit architectures are this was probably not a major problem in 2009, 64-bit architectures are now
now the norm. the norm.
* Non-x86 architectures like ARM and RISC-V are becoming more popular. If we * 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 start seeing a shift away from x86 on desktop machines, the native libraries
will need to be built for those architectures. 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 * 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 will be ported from X11 to Wayland, which will require porting the jaggl
native library from GLX to EGL. native library from GLX to EGL.
* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan * The switch away from OpenGL to newer graphics APIs like Metal and Vulkan might
might eventually necessitate the inclusion of OpenGL to Metal/Vulkan eventually necessitate the inclusion of OpenGL to Metal/Vulkan translation
translation layers. layers.
* I'm concerned about backwards compatibility and bit rot. The original native * 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 libraries were compiled 10 years ago, and at some point one of their
dependencies might drop backwards binary compatibility. 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 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, 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 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 data not held in the Git repository, such as issues. If necessary, we can switch
switch to a different hosting provider at short notice while retaining such to a different hosting provider at short notice while retaining such data.
data.
[nar-maven-plugin]: https://maven-nar.github.io/ [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 during the handshake process, which is how most current private servers are
currently implemented. currently implemented.
For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed by
by an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully switch
switch to JS5 mode, even though this is not the normal sequence of packets sent to JS5 mode, even though this is not the normal sequence of packets sent by the
by the client. client.
### 14 (`INIT_GAME_CONNECTION`) ### 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 | | Byte\[n\] | RSA-encrypted payload |
The unknown byte hard-coded to `0` in a client script might represent the 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 language. It is consistent with the ID for English. We can infer that there were
were language-specific versions of the cache, as the surviving copy does not language-specific versions of the cache, as the surviving copy does not contain
contain translations. translations.
The structure of the plaintext payload is described below: The structure of the plaintext payload is described below:
@ -255,8 +255,8 @@ your Message Centre for details.
### 5 (`DUPLICATE`) ### 5 (`DUPLICATE`)
**Message:** Your account has not logged out from its last session. Try again **Message:** Your account has not logged out from its last session. Try again in
in a few minutes. a few minutes.
### 6 (`CLIENT_OUT_OF_DATE`) ### 6 (`CLIENT_OUT_OF_DATE`)
@ -294,29 +294,30 @@ subscribe or use a different world.
### 14 (`UPDATE_IN_PROGRESS`) ### 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`) ### 15 (`RECONNECT_OK`)
### 16 (`TOO_MANY_ATTEMPTS`) ### 16 (`TOO_MANY_ATTEMPTS`)
**Message:** Too many incorrect logins from your address. Please wait 5 minutes before **Message:** Too many incorrect logins from your address. Please wait 5 minutes
trying again. before trying again.
### 17 (Account in members-only area) ### 17 (Account in members-only area)
**Message:** You are standing in a members-only area. To play on this world, move to a free **Message:** You are standing in a members-only area. To play on this world,
area first. move to a free area first.
### 18 (`LOCKED`) ### 18 (`LOCKED`)
**Message:** Your account has been locked as we suspect it has been stolen. Click here to **Message:** Your account has been locked as we suspect it has been stolen.
recover your account. Click here to recover your account.
### 19 (Fullscreen is members-only) ### 19 (Fullscreen is members-only)
**Message:** Fullscreen is currently a members-only feature. To log in, either return to the **Message:** Fullscreen is currently a members-only feature. To log in, either
main menu and exit fullscreen or use a members' account. return to the main menu and exit fullscreen or use a members' account.
### 20 (Invalid login server requested) ### 20 (Invalid login server requested)
@ -328,8 +329,8 @@ main menu and exit fullscreen or use a members' account.
|--------------|-------------------------| |--------------|-------------------------|
| UnsignedByte | Hop time | | UnsignedByte | Hop time |
**Message:** You have only just left another world. Your profile will be transferred in <n> **Message:** You have only just left another world. Your profile will be
seconds. transferred in <n> seconds.
The number of remaining seconds is calculated using the following formula: The number of remaining seconds is calculated using the following formula:
(hopTime * 60 + 180) / 50 (hopTime * 60 + 180) / 50
@ -348,11 +349,13 @@ The number of remaining seconds is calculated using the following formula:
### 25 (`UNKNOWN_REPLY_FROM_LOGINSERVER`) ### 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`) ### 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) ### 27 (Service unavailable)

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

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

Loading…
Cancel
Save