> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/hak5-usb-rubber-ducky/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/hak5-usb-rubber-ducky/operators-conditions-loops-and-functions/conditional-statements.md). # Conditional Statements ## Overview Previously, original DuckyScript payloads executed sequentially — line by line from start to finish. With DuckyScript 3.0, it isn't necessary for payload execution to be linear. Conditional statements, loops and functions allow for dynamic execution. ## `IF` The flow control statement `IF` will determine whether or not to execute its block of code based on the evaluation of an expression. One way to interpret an `IF` statement is to read it as "`IF` this condition is true, `THEN` do this". ### Syntax The IF statement consists of these parts * The `IF` keyword * The condition, or expression that evaluates to `TRUE` or `FALSE` * In nearly all cases, the expression should be surrounded by parenthesis `( )` * The `THEN` keyword * One or more newlines containing the block of code to execute * The `END_IF` keyword ### Example ``` REM Example IF THEN $FOO = 42 $BAR = 1337 IF ( $FOO < $BAR ) THEN STRING 42 is less than 1337 END_IF ``` #### Result * The expression "Is 42 less than 1337" is evaluated and determined to be `TRUE`. * Because the `IF` condition is `TRUE`, the code between the keywords `THEN` and `END_IF` are executed. * The string "`42 is less than 1337`" is typed. ## `ELSE` The ELSE statement is an optional component of the IF statement which will only execute when the IF statement condition is FALSE. One way to interpret an `ELSE` statement is to read it as "`IF` this condition is true, `THEN` do this thing, or `ELSE` do another thing". ### Example ``` REM Example IF THEN ELSE IF ( $_CAPSLOCK_ON == TRUE ) THEN STRING Capslock is on! ELSE IF ( $_CAPSLOCK_ON == FALSE ) THEN STRING Capslock is off! END_IF ``` #### Result * The condition of the capslock key, as determined by the target operating system, is checked. * If the capslock key state has been reported by the target as ON, the string "`Capslock is on`" will be typed. * Otherwise, if the capslock key state has not been reported by the target (or it has been reported as not being on), the string "`Capslock is off`" will be typed. ## Nested `IF` Statements A nested IF statement is quite simply an IF statement placed inside another IF statement. Nested IF statements may be used when evaluating a combination of conditions. ### Example ``` REM Example nested IF statements IF ( $_CAPSLOCK_ON == TRUE ) THEN IF ( $_NUMLOCK_ON == TRUE ) THEN STRING Both Capslock and Numlock are on! END_IF END_IF ``` #### Result * The condition of the first `IF` statement is evaluated — whether or not the target has reported that the Capslock key is on. If it is `TRUE`, then the nested `IF` statement will run. * The second `IF` statement is evaluated much like the first, only this time checking the status of the Numlock key. * If both the capslock and numlock keys have been reported by the target as being on, then the string "`Both Capslock and Numlock are on!`" will be typed. ## `IF` Statements with logical operators In some cases it may be more efficient to use logical operators within a single IF statement, rather than using a nested IF structure. ### Example ``` REM Example IF statement with logical operators IF (( $_CAPSLOCK_ON == TRUE ) && ( $_NUMLOCK_ON == TRUE )) THEN STRING Both Capslock and Numlock are on! END_IF ``` #### Result * Because the AND logical operator is in use, the whole condition will only evaluate as TRUE if both sub conditions are TRUE. * Similar to the Nested IF example, the string "`Both Capslock and Numlock are on!`" will only be typed if both capslock and numlock are reported by the target as being on. ## `IF` Statement Optimization The syntax of `IF` states that in nearly all cases the expression should be surrounded by parenthesis `( )` — however there is an exception to this rule. If the condition of only one variable is *true* or *false*, the parenthesis may be omitted. This results in a slightly smaller encoded `inject.bin` file as well as slightly faster payload execution. This is because it removes the step of first reducing the order precedence. ### Example ``` REM Example of optimized and unoptimized IF statements REM Consider VAR $FLAG = TRUE IF $FLAG THEN STRING FLAG is TRUE END_IF REM versus IF ( $FLAG == TRUE ) THEN STRING FLAG is TRUE END_IF ``` #### Result * In the first example, the `IF` statement without the parenthesis results in a 6 bytes added to the compiled `inject.bin` file. * In the second example, the `IF` statement surrounded by parenthesis results in 16 bytes added to the compiled `inject.bin` file. ### Example ``` REM Example of optimized IF statement with internal variable IF $_CAPSLOCK_ON THEN STRINGLN The caps lock key is on END_IF ``` #### Result * The internal variable `$_CAPSLOCK_ON` is checked. * If it evaluates as `TRUE`, the message "`The caps lock key is on`" is typed.