View source for ArmA: Armed Assault: Addon Signatures

{{Feature|important|Addon Signature implementation in all ArmA version before 1.08 contains serious bugs which cause even users with no modified or unsigned addons are marked as using modified data. Any newer products including Arma 2 are not affected by this bug.}}

=== Overview ===

Addon signatures are a way to reduce cheating in Armed Assault.
They are used to detect data files modified by anyone else but the addon creator. They are based on strong cryptographic principles (private/public key pairs), therefore hacking around them is very hard. 

Addon is signed by its creator using a private key, while the public key is used by the game to verify that the addon has not been modified.

=== Terminology ===

* '''Checked server:''' a server with signature verification on
* '''Unchecked server:''' a server with signature verification off
* '''Accepted signature:''' one of the signatures defined by the server as trusted

=== What is checked ===

Player connecting to a checked server is allowed to have present only addons which are signed by accepted signature. Any player not complying to this is detected, and based on server configuration a message in this sense may be displayed, or he may be kicked out, or another action defined by the server admin may be done.

Player cannot do any of the following if he wants to pass signature verification:

* modify signed addons
* use unsigned addons
* use addons which are signed, but not by an accepted signature

If player wants to use unsigned addons when playing single player or when playing on other servers not testing for this, he needs to make sure such addons are not loaded before connecting to the checked server. This can be done using [[Arma: Mod Folders]] or by using some 3rd party addon management utilities.

=== Controlling addon signature verification on the server ===

If a server admin decides addon signatures should be verified, he should add the following line to the [[Arma 3: Server Config File|server config]] file:

 verifySignatures = 1;

Server admin can decide which addon makers he considers trustworthy by placing their public keys in the "keys" directory. Usually (vanilla installation) there's only Bohemia Interactive's signature, called bi.bikey, in this directory. You can get other signatures at {{Link|http://www.ofpec.com/tags/index.php?action{{=}}list|OFPEC}}.

{{Feature|important|Use v2 signatures!}}

 verifySignatures = 2;

replaces obsolete v1 (since ARMA 2 version 1.10 and ARMA 2: OA version 1.59), v1 was deprecated as insecure

=== Community nature ===

There is no central authority deciding which signatures are trustworthy and which not. Each server admins can decide this. Of course, server admins are free to communicate their experiences with various signatures, or create a publicly accessible black lists of signatures which they think are no longer trustworthy, like when they know they were compromised because the private key has been leaked.

Many public keys of different mods are available at {{Link|http://www.ofpec.com/tags/index.php?action{{=}}list|OFPEC.com}}.

=== Signing addons ===

Signing addons is done using [[DSSignFile]] utility. A private key is needed for this, which can anyone create using [[DSCreateKey]].

==== How to sign an addon ====

===== Create your own keys =====

Use [[DSCreateKey]] to create a key, passing in a unique identifier (often your tag or project name) as the parameter, like this:

 DSCreateKey myName

This example creates 2 files: a key 'myName.bikey' and a privateKey 'myName.biprivatekey'.
====== Correct naming of the key ======

'''Correct naming is important to make the key easier to relate to an addon for server admins and mod users'''

*TAG_modName.bikey

*TAG: ''Should be the name you are using in the community or something similar''

*modName: ''This should relate to your mod in any way, preferable the name of the mod''

You can include the key with your distributed addon or separately, since it has no dependency on the actual addon. It is only used by the server and not by the client. Do not distrubute the privateKey.

You do not need a new key for each addon - in normal circumstances you should be using the same key over and over for multiple addons. (This is also important from admins point of view - installing a new addon signed with a key which is already trusted is a straightforward operation, while installing a new key is a step which should be considered much less frequent, and requires more attention from side of the admin).

===== Option 1: Sign your addons which are already packed =====

Use [[DSSignFile]] to create a signature for the addon pbo which is already in use.
 DSSignFile privateKey filename.ext

This example creates a signature file: 'filename.ext.myName.bisign'. Include this signature together with your distributed addon files.

===== Option 2: Sign your addons while packing them =====

Pass your key to [[BinPBO]] so that your addons are signed while packing.

===== Advanced usage scenario: Beta keys =====

In case you want the addon to pass some more testing before you are sure you can sign it, do not sign it with your main key. Instead, create a new key, called something like myKeyBeta15, and use this key to sign it. Distribute the addon with this key to both users and server admins. Once you are confident enough testing is performed, use Option 1 to create a new (final) signature with your main key and distribute it. In case anything goes wrong during testing and you see the addon can be used to cheat or get an unfair advantage, inform the server admins to remove the addon and the beta key. This way your older addons signed with your main key will still continue to work.

''Note: This options requires a cooperation of server admins and users using the addon, as they need to install the signature files for the addon.''

===== Advanced usage scenario: Server keys =====

One addon can be accompanied by multiple signatures, each signed with a different key. One application for this can be server admin can create his own key for his server, and can use it to sign all addons on the server he considers safe.

''Note: For this usage style, signature files for the addons need to be distributed to all users connecting to that server.''

==== Security considerations ====

The following are ways the security of this system can be compromised by the human factor:

* Private key has been leaked, meaning somebody is able to perform unauthorized modifications to addons signed by given signature

* A person holding a private key and considered trustworthy so far has intentionally created or signed an addon which can be used to cheat

* A person holding a private key has unintentionally created or signed an addon which can be used to cheat. This can be either by mistake (e.g. someone creating an interesting uniform variant reskin for default units, but not seeing this variant provides less cover) or by a fraud (addon maker signing an addon which he was passed by somebody else, but the addon contains some hidden payload, like a cheating script)

* Somebody creating cheats fools a server admin to install his signature.

===== Best practices for addon makers =====

* Never hand your private key to anyone, store it on a secure place, and if transferring it, use secure means

* Never sign any addons given to you by somebody else.

* You are the one responsible for reputation of your signature. Think about what you sign. Consider carefully if the addon or modification you have created can be used to get an unfair advantage

===== Best practices for server admins =====

* Add only keys of addon makers which you really trust. Do not add a keys only because a few users are requesting you do so.

* Beware of false keys. The fact the key is named AMG does not mean it really comes from Addon Making Group, it might be an attempt from cheaters to impersonate AMG and to let their own addons pass verification. Be sure to properly authenticate the source of the signature.

* Decide what you do when user does not pass signature verification. Use [[ArmA: Server Side Scripting|Server Side Scripting]] to configure it.

=== See Also ===

[[Arma 3: Server Config File|server config]]

[[DSCreateKey]]

[[DSCheckSignatures]]

{{GameCategory|arma1|Addon Editing}}
{{GameCategory|arma1|Multiplayer}}