Keypad Events Ever use events to create a password for a puzzle or secure door, only for some scoundrel to just save the build, read the events on their own server, and come back ready to dig through all your secret rooms? Most of you probably haven't even done that, because just rigging up the keypad with default events is a pain. Well, here to solve all your problems* is Event_Keypad!
Events:This add-on provides two input and two output events, intended to all be used in building a keypad:
- fxDTSBrick::keypadInputChar - Output - Takes a single character, and adds it to the client's input text. Works with any Torque supported character, and is case sensitive.
- fxDTSBrick::keypadTest - Output - Checks the client's input against a hash and calls the appropriate input event on this brick. See below for more details. Leaving the hash blank will instead clear the client's input text.
- fxDTSBrick::onKeypadCorrect and fxDTSBrick::onKeypadIncorrect - Inputs - Called by keypadTest depending on whether or not the client's input was correct.
About Hashes and Salts:To keep passwords secret, the actual passwords are not kept by the events. Otherwise, someone could just load the build on their own server, wrench the brick, and read the password. However, you still want to be able to save and load the bricks yourself without losing all your passwords. Hashing provides the solution. A hash function takes some text, and converts it into different text in a way that cannot be reversed, and that the same input will always produce the same output. So we choose a password for our keypad, hash it, and what comes out is some unholy combination of numbers and letters. We make that the parameter for our keypadTest event. Then when someone enters their code and hits the test button, we use the same hash function on their input. If the resulting string of numbers and letters is the same, then the event knows that they have the right password, even though the event never actually knows what the password is.
But there's still a problem. If someone wrenches your brick and finds out your password's hash, and they know what hash function the add-on uses, they can run a script to quickly make thousands of guesses, hashing them, and checking them against your hash. A 4 digit numerical code can be broken in an instant. This is resolved by introducing a salt string. A salt string is a bit of secret text gets added to the input when the hash function is run. The salt is unique for each server, and can be viewed and set by super admins. By keeping the salt secret from regular users, the only way they'll be able to make guesses is by using the events on the server. It acts as a sort of master password, keeping the individual event passwords secure. It also means that by using the same salt, a save with keypad events can be transferred to other trusted users. As a consequence however, if you change a server's salt string, all existing keypad events set using the old salt will be invalidated.
There's a lot to the subject of securely storing passwords, and this is by no means a comprehensive summary. Fortunately, there are a bunch of commands that simplify this process for the scope of this add-on.
Server Commands:- /setBrickPassword [password] - Sets the value of the keypadTest event on the brick you're looking at. Must be holding a wrench, must have access to the brick's wrench events, and the brick must have exactly one keypadTest output event enabled.
- /setKeypadSalt [salt] - Super Admin only. Sets the server's salt string, which is used in the hash function for every brick password.
- /keypadSaltHelp - Displays a summary of how salt strings work, similar to the above paragraph. Super Admins should educate themselves with this before meddling with the server's salt string.
Using Keypad Events:Didn't read any of the above and have no idea what you're doing? We got you covered! Here's the fast version.
For server hosts:First, install and enable the mod. When you start the server, type "/setKeypadSalt abc123", substituting in a unique password. This password will be visible to your super admins. If you ever load your keypads on a different server, or if your server preferences ever get cleared, you will have to use the same keypad salt when you enter the command again. If you lose your keypad salt, all keypad test events in your build will have to be manually reset.
To build a keypad:To build your keypad, you can start by creating a bunch of buttons with prints on them, using "onActivate->Self->keypadInputChar->X" where X is the brick's letter or number. You can also add events for any effects or sounds you want the button to have when you press it. Optionally, add a clear button that has the event "onActivate->Self->keypadTest->[empty string]". Then, set up an enter button with "onActivate->Self->keypadTest->[hash]", plus further onKeypadCorrect and onKeypadIncorrect events. Finally, fill in the "hash" portion of the keypadTest event by looking at the enter button, equipping a wrench, and typing in "/setBrickPassword 321password", substituting in your brick's password. You can then test your keypad by typing in the password on it, and pressing the enter button.
Example Save:Included here is a save file with a simple keypad built on it. As you'll recall from above, the only way to use keypad events from a save is to have the same salt string as the server it was created with. In this case, you'll need to use "/setKeypadSalt cat" for the example to work. Setting the salt to anything else will invalidate the events, and if you did not know that "cat" was the salt I used to create this keypad, you would not be able to use this keypad on your own server. Once you've set the salt correctly, the code to the keypad is "1234".
Download Example SaveIn Conclusion:I believe that covers everything important. If you forget anything, the error messages should be detailed enough to explain what you did wrong. Special thanks goes to Ipquarx, for providing security advice. Additional thanks goes to Pecon, for hosting the test server for these events over the last 4 years.
*Will not actually solve all your problems, only the two described here.