Skip to content

Security API

Jump to bottom
Cade edited this page Jul 24, 2022 · 7 revisions

What is the security api?

The security API is a link to the security system so you can make your own programs that run with credentials from the server (If someone has pass, then the code runs etc.) It adds a lot more variability to your creations if you want to add something unique. Want a program that lets you control your robots that only lets you use it if you have a pass? This is the way. On top of that, it allows custom usage of the security system with the hidden strings! For example: want someone to only be able to open a door 5 times? Count down the uses every time they swipe their card using the security api to grab the variables. You can also crypt and decrypt strings and send messages easily through the API. (crypt and send in 2.4.0 only)

How to setup the regular program

check basic example program to show how to set it up

  1. Download the program using the wget program on the raw data. Save as securityAPI.lua
  2. In your program, include the library using require("securityAPI.lua")
  3. Also include the event library with require("event")
  4. Have it run the setup method in the security API
  5. Make sure a magSwipe event is checked and the 4th variable pulled from it is saved.
  6. Have it run the checkPass method passing the 4th variable from step 5 and have 2 variables pulled from that method.
  7. Have it check the 1st variable if it's true, then use the second variable as the true false whether you have access or not

that's it. I know it probably doesn't makes sense, so check the basic example program to understand what I'm saying.

Basic example program

local api = require("securityAPI")
local event = require("event")
local computer = require("computer")

--[[This sets up the program with the server. If this
is the first time setting up the server, it asks you to
set up the cryptKey and the passes it will check for. Then
it sends the info to the server]]
api.setup()

while true do
  --Check for card swipes
  ev, address, user, str, uuid, data = event.pull("magData") --str is the crypted user information.
  --[[Check the credentials of the user. received checks if it was successful in sending the message.
  If received = true, check will be true or false depending if user has access; If received = false, check is error message]]
  local received, check = api.checkPass(str)
  if received then
    print("User has access: " .. tostring(check))
    computer.beep()
    if check then
      computer.beep()
    end
  else
    print("Error: " .. tostring(check))
  end
end

Setting up a custom hidden string program (Coming soon 2.3.0)

Setup is kind of similar to that previously. However, logic is handled on your end instead of simply sending the card data straight to the server and having it tell you true or false. All instructions are subject to change.

There are two ways you can set it up: the easy (using the pass set up with the setup function) or the more advanced, hard coded way (give it the var string) These 2 can "technically be used interchangeably", however if you use the easy way, you won't be able to use normal pass checking.

Easy way:

  1. Download the program using the wget program on the raw data. Save as securityAPI.lua
  2. In your program, include the library using require("securityAPI.lua")
  3. Also include the event library with require("event")
  4. Have it run the setup method in the security API (For the pass setup, ensure you use the simple pass setup and that the pass you setup is a string. The string you would like to read does not matter and is not used, so set it to whatever you want)
  5. Make sure a magSwipe event is checked and the 4th variable pulled from it is saved.
  6. Run the getVar method, passing the 4th variable from step 5 and then true. Pull 2 variables from the method.
  7. Have it check the 1st variable if it's true. If true, the second variable should include the data that was in that variable for the user.
  8. Perform whatever logic you want, whether it's lowering or increasing a number, linking it to another program by uuid, etc.
  9. Run the setVar method, passing the 4th variable from step 5 and then true as the second variable, and lastly the new string value. Pull 2 variables (1 is fine) from the method.
  10. Have it check the 1st variable if it's true. If true, it received it. If false, there was an error, which is listed in the second variable.

Advanced way:

  1. Download the program using the wget program on the raw data. Save as securityAPI.lua
  2. In your program, include the library using require("securityAPI.lua")
  3. Also include the event library with require("event")
  4. Have it run the setup method in the security API (Cryptkey setup is important, but the pass setup doesn't matter unless you plan on also checking a user's pass.)
  5. Make sure a magSwipe event is checked and the 4th variable pulled from it is saved.
  6. Run the getVar method, passing the 4th variable from step 5 and then the name of the key for the variable you want to grab (var name. Must be a hidden string or regular string). Pull 2 variables from the method.
  7. Have it check the 1st variable if it's true. If true, the second variable should include the data that was in that variable for the user.
  8. Perform whatever logic you want, whether it's lowering or increasing a number, linking it to another program by uuid, etc.
  9. Run the setVar method, passing the 4th variable from step 5 and then the name of the key for the variable you want to edit (var name. Must be a hidden or regular string), and lastly the new string value. Pull 2 variables (1 is fine) from the method.
  10. Have it check the 1st variable if it's true. If true, it received it. If false, there was an error, which is listed in the second variable.

Example program using this (Coming soon 2.3.0)

In this example, the hidden string's var key is "accessnum". All code is subject to change. This is the advanced method. If you change "accessnum" to true without the quotation marks, it will use whatever pass you setup in the api.setup area.

local api = require("securityAPI")
local event = require("event")

local varString = "accessnum"

--[[This sets up the program with the server. If this
is the first time setting up the server, it asks you to
set up the cryptKey and the passes it will check for. Then
it sends the info to the server]]
api.setup()

while true do
  --Check for card swipes
  print("waiting for ze swoipe")
  ev, address, user, str, uuid, data = event.pull("magData") --str is the crypted user information.
  --[[Check the credentials of the user. received checks if it was successful in sending the message.
  If received = true, check will be true or false depending if user has access; If received = false, check is error message]]
  local received, check = api.getVar(str,varString)
  if received then
    local num = 0
    if check ~= "none" then
      num = tonumber(check)
      if num >= 1 then
        num = num - 1
        print("User has " .. num .. " uses left")
        num = tostring(num)
      else
        print("User ran out. Resetting to 3")
        num = "3"
      end
    else
      num = "3"
      print("user's string not setup. Setting to 3.")
    end
    api.setVar(str,varString,num)
  else
    print("Error: " .. check)
  end
end

Crypting and Decrypting strings

This is a function only available to versions 2.4.0 and up, which is being released soon. There isn't much you need to know as it's fairly simple. Just make sure the program runs the setup() function, then run the crypt(str,reverse), setting str to the crypted or uncrypted string and reverse to true or false: false if you want to crypt a string, and true if you want to decrypt a string. crypt will return 2 values: true if it succeeds first, and the crypted/decrypted string second if it succeeds.

Sending messages through the API

With the introduction of modules through the 2.4.0 update, you may want to create a program to interface with a new module you made for the server, but how do you send messages to the server? With this new method, you can! Make sure the program runs the setup() function, then run send(wait,...), replacing wait with true and false, depending on if you want to wait for a return from the server. The ... is just the data you want to send through the server, although the server only will receive 2 data (send(wait,data1,data2)) If you don't wait for a return, it will return true as well as "no return requested. If you do wait, it will return three values: true if it succeeds, and the 2 values received from the modem (only pulls 2 values from modem, as that's also the max the server can send anyway)

Clone this wiki locally