Security level compliance - TiberiumFusion/TTPlugins GitHub Wiki

This section explains plugin Security Levels and and how you can make your plugin compliant with higher Security Levels.

This information is intended for plugin authors. If you are a Terraria Tweaker 2 user and you are not sure what Security Level you should choose, please click on the What security level should I chose? link in TT2 above the Security Level slider.

What are Security Levels?

In Terraria Tweaker 2, the end user can set a Security Level for their enabled plugins. Security Levels improve user security and confidence by restricting powerful .NET features that can be exploited by malicious plugins. If your plugin includes code that violates the user's chosen Security Level, your plugin will be prohibited from executing.

  • Users will have low trust for a plugin that requires a low & permissive Security Level. If your plugin requires the user to switch to a lower Security Level, the user may simply discard your plugin.
  • Users will have more trust in a plugin that complies with a high & restrictive Security Level. If your plugin functions perfectly under the highest Security Levels, the user will be much more likely to enable your plugin.

SECURITY LEVELS ARE NOT GUARANTEES

Security Levels greatly increase the difficulty for a plugin to do something malicious. They are not a magic feather and do not guarantee complete security against malicious plugins. Given enough knowledge and time, exploits and security holes can be found in everything.

Where can I set the Security Level?

In Terraria Tweaker 2, the user can pick a Security Level for each of their Tweak Lists. You can access the Security Level options by editing a Tweak List and opening the Plugin Manager. Each Tweak List has its own Security Level.

NOTE: The default Security Level is Level 3.

What does each Security Level do?

There are 4 Security Levels available to the user. Security Levels work by restricting use of powerful .NET features that can be easily exploited by malicious plugins.

Level 1

This is the baseline Security Level that protects the plugin framework. The restrictions in this level are always in effect and cannot be disabled.

  • Disallows use of the types in the com.tiberiumfusion namespace which are external to TTPlugins. Specifically, only types in com.tiberiumfusion.ttplugins.HarmonyPlugins are allowed.
  • Disallows use of most types in the HarmonyLib namespace. CodeInstruction and CodeInstructionExtensions are the only types allowed, as required by transpiler patches.

Level 2

This level restricts the most common ways of loading and executing unauthorized code. If your plugin is not compliant with this Security Level, you should seriously question the kind of power you are giving your plugin.

  • Includes everything from Level 1
  • Disallows use of all types in the Mono.Cecil namespace
  • Disallows use of System.AppDomain, System.AppDomainSetup, System.AppDomainManager, and System.AppDomainInitializer types
  • Disallows use of the System.Reflection.Assembly Load methods, including Load, LoadFile, LoadFrom, LoadWithPartialName, ReflectionOnlyLoad, ReflectionOnlyLoadFrom, and UnsafeLoadFrom
  • Disallows use of all types in the System.CodeDom namespace

Level 3

This is the default Security Level and restricts the most common ways of read/writing files and connecting to the internet. If your plugin legitimately needs to connect to the internet or manage files on the user's drives, you should explain to the user exactly what your plugin is doing, since it will require the user to drop to Security Level 2.

  • Includes everything from Level 2
  • Disallows use of most types in the System.IO namespace. MemoryStream is the only type allowed.
  • Disallows use of all types in the System.Net namespace
  • Disallows use of all types in the System.Web namespace

Level 4

This is the maximum Security Level, which completely denies any & all use of Reflection. Users may pick this level when trying out new plugins that they do not fully trust. If your plugin is not compliant with Security Level 4, the cautious user may simply discard your plugin.

  • Includes everything from Level 3
  • Disallows use of all types in the System.Reflection namespace

Testing your plugin's Security Level compliance

Using Terraria Tweaker 2, you can test your plugin against all four Security Levels and receive a detailed report of any violations. Exact line numbers for violations will be provided in the report, if available. To get exact line numbers with a precompiled plugin assembly, first compile it without optimizations and then copy its PDB file to your Plugins folder alongside the compiled DLL.

◆ First, launch Terraria Tweaker 2 and open the Plugin Manager (click Plugins from the sidebar or the Plugin Manager button while editing a Tweak List).

◆ Highlight the plugin you want to test, then click Test

Step 1 img

◆ The test window will open, run tests, and display a report. Exact line numbers will be provided, if available, for any violations.

Step 2 img

This example plugin accesses AppDomain.CurrentDomain and thus violates Security Level 2, but is otherwise compliant with the level-specific requirements in Levels 1, 3, and 4. Even though this plugin does not violate any of the Level 3 or Level 4 specific requirements, it will not run under Level 3 and Level 4 because each level includes the security restrictions of the levels below it.

◆ If you are using Terraria Tweaker 2's included code editor, you can quickly test your plugin while you are writing code, using the Test button in the toolbar.

Step 3 img

Improving your plugin's Security Level compliance

  • If your plugin requires Reflection to work with private members in Terraria, consider using secure helper methods instead, as provided by the HHelpers class. Refer to the Top level helpers article for more information. (Improves compliance with Security Level 4)
  • Use Persistent savedata to store savedata for your plugin, instead of deploying your own files. (Improves compliance with Security Level 3)
  • If you need to load embedded resources from your precompiled plugin assembly, use GetPluginAssemblyResourceBytes instead of directly using Streams. Refer to Helpful inherited members for more information. (Improves compliance with Security Level 3)

What if my plugin absolutely needs a low Security Level?

If your plugin is advanced and legitimately requires a low Security Level, provide a full disclosure of what your plugin does and why it needs more power. Additionally, make your plugin's source code available for users to inspect. Users have no obligation to download, enable, and/or use any plugin. If you want users to trust your plugin, you should provide convenient and transparent information on how your plugin works.

Remember: Security Levels exist to provide users will additional control over partially trusted plugins. A plugin that is compliant with Security Level 4 will have better reception than a plugin that begs the user to drop to Security Level 2.

Next

Read the Diagnosing errors & debugging (pending) article to learn strategies for identifying and fixing errors in your plugin.