Signed and Encrypted ZIP files

The Barracuda App Server (BAS) can protect deployed Lua ZIP applications in two different ways:

• Signing proves that the ZIP file was produced by you and has not been modified.
• Encryption hides sensitive files inside the ZIP archive.

Signing is most useful when Lua applications are deployed as external ZIP files instead of being embedded directly in firmware.

Quick Start

If you are new to this topic, start with this rule of thumb:

Goal	Use signing?	Use encryption?
Prevent unauthorized or modified Lua applications from running	Yes	Usually no
Protect passwords, private keys, or other secrets stored inside the ZIP	Yes	Yes, for the sensitive files
Deploy a normal application with no secrets in the ZIP	Yes	Optional
Build the strongest practical deployment	Yes	Yes, but encrypt only the files that need confidentiality

For most embedded products, signing is the most important feature. If you use ZIP encryption, you should also require ZIP signing. Otherwise, an attacker may be able to replace encrypted entries with spoofed plaintext files.

What Signing and Encryption Protect

Signing Protects Authenticity and Integrity

When BAS is configured with your embedded public key, it will verify the ZIP file before using it.

Signing gives you two important guarantees:

• Authenticity: the ZIP file was signed by someone who holds your private signing key.
• Integrity: the ZIP file has not been modified since it was signed.

In practice, signing is what prevents unauthorized Lua applications, modified scripts, or injected files from being mounted and executed.

Encryption Protects Confidentiality

ZIP encryption protects the content of selected files inside the archive. This is useful for files such as:

• configuration files with passwords or API credentials
• private keys
• product secrets
• other deployment data that should not be readable from the ZIP file alone

You do not need to encrypt every file in the archive. In fact, that is usually a bad idea because it increases runtime decryption work, especially for frequently accessed Lua files and Lua Server Pages. ZIP encryption is applied per file, so it is usually best to encrypt only the files that actually contain secrets.

Signing and Encryption Serve Different Purposes

These two mechanisms are independent and solve different problems:

• Embedded public key: tells BAS to verify signatures on mounted ZIP files.
• Embedded ZIP password: lets BAS automatically decrypt encrypted files inside ZIP archives.

A signed ZIP file is not automatically encrypted. An encrypted ZIP file is not automatically trusted. In practice, encrypted ZIP files must be signed. Without signing, an attacker may be able to replace encrypted files in the archive with plaintext files containing spoofed data.

If you prefer not to embed a global ZIP password in C code, or if different ZIP files use different passwords, Lua code can instead set passwords individually by using io:setpasswd().

Recommended Production Workflow

For most deployments, the easiest way to think about the process is:

1. Build your ZIP application.
2. Encrypt only the files inside the ZIP that contain secrets.
3. Sign the final ZIP file.
4. Embed the public key in your BAS startup code.
5. If you use ZIP encryption, also embed the generated ZIP password in your BAS startup code, or provide it from Lua via io:setpasswd().
6. Deploy the ZIP file with both protections enabled.

Important: If you modify the ZIP file after signing it, you must sign it again. A signature always covers the final ZIP file bytes.

How ZIP Signing Works in BAS

BAS verifies signed ZIP files by using a standard public/private key design:

• Private key: used by you during the build or release process to sign the ZIP file.
• Public key: embedded in your BAS-based application and used to verify the signature.

Only someone with the private key can produce a valid signature. BAS only needs the public key in order to verify the signature when the ZIP file is mounted.

How the ZIP Signature Is Stored

ZIP files permit extra data to be appended to the end of the file. BAS takes advantage of this by storing the digital signature after the ZIP data. This means the ZIP can still be handled as a normal ZIP file while also carrying a signature that BAS can verify.

Steps to Sign a ZIP File

1. Calculate a SHA-256 hash of the ZIP file.
2. Sign that hash with your ECC private key.
3. Append the resulting signature to the end of the ZIP file.

When BAS mounts the ZIP file, it verifies the signature with the embedded public key before allowing the ZIP to be used.

Generate an ECC Key Pair with OpenSSL

If you do not already have an ECC key pair, you can create one with OpenSSL:

# Generate a private ECC key
openssl ecparam -genkey -name prime256v1 -noout -out private_key.pem
 
# Generate the corresponding public key
openssl ec -in private_key.pem -pubout -out public_key.pem

Files:

• private_key.pem: keep this secure; it is used to sign ZIP files.
• public_key.pem: embed this key in BAS so signed ZIP files can be verified.

Example: Sign a ZIP File

The following Bash script shows the basic signing process:

#!/bin/bash
 
if [ "$#" -ne 2 ]; then
    echo "Usage: $0 <zipfile> <privatekey>"
    exit 1
fi
 
ZIP_FILE="$1"
PRIVATE_KEY="$2"
SIGNATURE_FILE="signature.bin"
 
echo "Creating SHA-256 signature for the ZIP file..."
openssl dgst -sha256 -sign "$PRIVATE_KEY" -out "$SIGNATURE_FILE" "$ZIP_FILE"
 
echo "Appending the signature to the end of the ZIP file..."
cat "$SIGNATURE_FILE" >> "$ZIP_FILE"
 
rm "$SIGNATURE_FILE"
echo "Done. The ZIP file is now signed."

Usage:

./signzip.sh your_application.zip private_key.pem

Important: Run the script only on the final ZIP file. If you sign a ZIP file twice, or edit it after signing, signature verification will fail.

Embed the Public Key in BAS

To enforce signed ZIP files, embed the public key in your BAS startup code and assign it to BaLua_param.zipPubKey.

Convert the Public Key for C Code

Use the SharkSSLParseKey command-line tool to convert the PEM public key into a C array:

SharkSSLParseKey public_key.pem

This produces C data similar to:

const U8 sharkSslPubECKey[72] = {
    /* SharkSSLParseKey output */
};

Assign the Public Key in Startup Code

const U8 sharkSslPubECKey[72] = {
    /* SharkSSLParseKey output */
};
 
BaLua_param blp;
memset(&blp, 0, sizeof(blp));
 
blp.zipPubKey = sharkSslPubECKey;

With zipPubKey configured, BAS will verify mounted ZIP files against the embedded public key.

How ZIP Encryption Works in BAS

ZIP encryption uses a symmetric password. The same password is used to encrypt and decrypt the protected files inside the ZIP archive.

In BAS deployments, this password can be embedded in the compiled code and protected with white-box cryptography. BAS can then automatically decrypt the encrypted ZIP entries when they are accessed.

When to Use ZIP Encryption

Use ZIP encryption when your deployed ZIP contains secrets that should not be visible just because someone can copy the ZIP file. This works best for secrets that are static: files that never change after deployment, or that only change when you deliver a new signed application or OTA upgrade. In practice, ZIP encryption should be combined with ZIP signing.

Examples:

• a configuration file containing passwords
• private key material stored as files
• deployment-specific secrets
• other data that is packaged once and replaced only during an upgrade

ZIP encryption is not intended for data that your application must update continuously at runtime. If you need encrypted read/write storage for files that are created or modified while the system is running, use a runtime encryption layer such as CryptoIO.

Do not treat ZIP encryption as a substitute for ZIP signing. ZIP signing controls what code BAS is willing to trust. ZIP encryption only controls who can read selected file contents. If signing is not enabled, an attacker may be able to replace encrypted files with plaintext files containing spoofed data.

Enable ZIP AES Password Protection

To prepare a ZIP password for BAS, use the binpwd2str command line tool. This tool is designed for BAS deployments and produces three forms of the same password:

• a readable password for use with your AES-capable ZIP tool
• a binary form that can be used from Lua with io:setpasswd()
• a C array for embedding the password in your BAS startup code

Typical Workflow

1. Compile binpwd2str.
2. Run it to generate the ZIP password in the forms you need.
3. Use the readable password with your ZIP tool to encrypt the sensitive files in the ZIP archive.
4. Embed the generated C array in your BAS startup code, or load the generated binary password from Lua and call io:setpasswd().

Embed the ZIP Password in Startup Code

const U8 zipBinPwd[] = {
    /* binpwd2str output */
};
 
BaLua_param blp;
memset(&blp, 0, sizeof(blp));
 
blp.zipBinPwd = zipBinPwd;
blp.zipBinPwdLen = sizeof(zipBinPwd);

With zipBinPwd configured, BAS can automatically decrypt encrypted ZIP entries that use the matching password.

Combined Startup Example

If you want both protections, embed both the public key and the ZIP password:

const U8 sharkSslPubECKey[72] = {
    /* SharkSSLParseKey output */
};
 
const U8 zipBinPwd[] = {
    /* binpwd2str output */
};
 
BaLua_param blp;
memset(&blp, 0, sizeof(blp));
 
blp.zipPubKey = sharkSslPubECKey;
blp.zipBinPwd = zipBinPwd;
blp.zipBinPwdLen = sizeof(zipBinPwd);

Secure OTA Upgrades

The Barracuda App Server can support secure OTA upgrades both manually, for example through a web interface, and automatically through IoT protocols. A practical way to deliver an upgrade is to package it as a ZIP file and then protect that ZIP with the same signing and encryption mechanisms described in this document.

An OTA ZIP package can contain the new firmware image and any additional files required by the upgrade process, such as standalone applications, configuration files, or other deployment assets. This makes the ZIP file a convenient upgrade container for both firmware and application-level updates.

When ZIP signing is enabled, opening the OTA package with ba.mkio(baseio, path) automatically triggers signature verification. If the ZIP file is unsigned or has been modified, the call fails. This gives the upgrade logic a strong integrity and authenticity check before Lua code reads any data from the package.

If ZIP encryption is also enabled, the OTA package can additionally protect the confidentiality of sensitive upgrade files (secrets) stored inside the ZIP archive. In other words, signing protects the upgrade package from tampering, while encryption keeps selected files inside the package confidential.

Lua code can then be designed to open the verified ZIP package, extract the required files, and deploy the new firmware or accompanying resources. This approach works well when you want one upgrade artifact to carry everything needed for a secure field update.

Practical Recommendations

• Sign all deployed Lua ZIP applications in production.
• Encrypt only the files that actually contain secrets.
• Keep the private signing key offline or otherwise tightly controlled.
• Treat the embedded public key as part of your runtime trust policy.
• If the ZIP changes, sign it again.
• If you are using both features, encrypt first and sign last.

Troubleshooting Checklist

If a ZIP file does not load as expected, check the following:

• Was the ZIP modified after it was signed?
• Was the ZIP accidentally signed more than once?
• Does the embedded public key match the private key that signed the ZIP?
• If files are encrypted, does BAS have the correct ZIP password?
• Are you encrypting too many frequently accessed files, causing unnecessary CPU load?