# AmiSSL Requirements for HamConnect-Amiga

Audited upstream release: **AmiSSL 5.27**, published 2026-04-08.

Product status: **optional add-on; not required or installed by default.**

HamConnect-Amiga, HamTCP, HamNet, HamNet+, and HamChat use the socket API and
do not require AmiSSL. HamNet+ uses ordinary HTTP transport with its own
authenticated and encrypted application payload. The core installer therefore
leaves an existing AmiSSL installation untouched and excludes AmiSSL from the
minimum-RAM and minimum-storage claims.

This document is retained for a later Advanced/Optional Tools profile and for
customers who run third-party HTTPS/TLS applications. None of the requirements
below is a release gate for the core HamConnect bundle unless that optional
profile is selected.

Primary upstream references:

- <https://github.com/jens-maus/amissl/releases/tag/5.27>
- <https://github.com/jens-maus/amissl/tree/5.27>
- <https://github.com/jens-maus/amissl/blob/5.27/dist/Install-AmiSSL>

## 1. Platform gate

The OS3 payload requires AmigaOS 3.0+, a 68020+ CPU, and exec.library v38+
compatibility. These are AmiSSL's optional-profile requirements, not proof that
the complete HamConnect bundle fits in 4 MB.

The upstream OS3 archive contains two mutually exclusive runtime builds:

1. `68020-40` for 68020, 68030, 68040, 68080, and MorphOS.
2. `68060` for 68060 and Amithlon.

HamConnect must select exactly one runtime library and must never infer 68060
from a model name alone. CPU flags, `68060.library`, and the user's confirmed
choice are the supported evidence.

## 2. Verified payload and storage

Pinned archive:

- Name: `AmiSSL-5.27-OS3.lha`
- Compressed bytes: 4,294,781
- SHA-256:
  `722476cfbf21c0caf6ff4a77e32ee8baf67d3045db0e9ff2ccce6c782bed5847`
- Unpacked archive bytes with both CPU libraries: 9,181,812
- Installed 68020-class bytes before filesystem overhead: 5,564,096
- Installed 68060-class bytes before filesystem overhead: 5,568,664
- Managed root-certificate files: 290
- Managed root-certificate bytes: 434,226

Small certificate files consume additional FFS block and file-header space.
An optional AmiSSL installation must reserve at least 12 MiB for installation
plus rollback. This storage is not charged to the default Networking Package.

## 3. Runtime-memory gate

Upstream specifies CPU and OS requirements but does not publish a minimum RAM
figure for a TLS session. HamConnect must not convert the product's 4 MB goal
into an unproven AmiSSL claim.

The `0.3.0-dev` installer, inventory, and dry-run planner have been launched
successfully in WinUAE with a 68020, 2 MB Chip RAM, and 2 MB Fast RAM. Exec
reports 4092 KB rather than the nominal 4096 KB because allocator metadata is
not counted. HamConnect accepts 4000 KB reported memory as the nominal 4 MB
hardware gate and selects its streamed low-memory plan. This proves the
installer/planner baseline only; the AmiSSL payload is not installed in that
test image and TLS runtime memory remains unproven.

An optional AmiSSL acceptance test must measure:

1. Free memory after Workbench and HamTCP start.
2. Peak memory while the selected AmiSSL library initializes.
3. Peak memory during DNS, TCP connection, certificate-chain validation, and
   an HTTPS response.
4. Memory after the TLS client exits and AmiSSL is expunged.
5. Sequential HamNet and HamChat launches; concurrent launch is optional on
   the low-memory profile.

The low-memory profile streams archive extraction, does not preload AmiSSL,
runs one secure client at a time, and treats a clean out-of-memory result as a
diagnostic failure rather than a hang.

## 4. Installation and compatibility rules

HamConnect must mirror these upstream behaviors:

1. Install the latest `amisslmaster.library`.
2. Store implementation libraries under `AmiSSL:Libs/AmiSSL`.
3. Keep older ABI libraries needed by AmiSSL v1-v4 applications.
4. Refuse an in-place update while an AmiSSL library is resident/in use.
5. Maintain one consistent `AmiSSL:` assign and one managed installation.
6. Add `AmiSSL:Libs` to `LIBS:` without replacing existing library paths.
7. Update the managed `AmiSSL:Certs` set and remove expired managed roots.
8. Preserve `AmiSSL:UserCerts` and `AmiSSL:Private` without exception.
9. Preserve an existing `openssl.cnf`.
10. Set the system clock before the HTTPS validation test.

The OpenSSL command and documentation are bundled, but the command is not
resident and is not launched automatically on a 4 MB system.

## 5. Licence and attribution

AmiSSL and its OpenSSL base are Apache-2.0. Every HamConnect offline bundle and
update payload that carries AmiSSL must also carry the exact upstream
`LICENSE` and `NOTICE` files. The manifest pins their sizes and SHA-256 hashes.

`tools/stage_hamconnect_components.py` downloads the archive, licence, and
notice from the pinned 5.27 sources; verifies size and SHA-256; and writes a
local staging receipt. Staging does not authorize a HamConnect release until
the required licence/NOTICE payload and all install, rollback, and runtime
gates pass.

## 6. Update behavior

HamConnect checks signed Stable/Beta component metadata automatically when
network access is available. It does not silently install AmiSSL.

An AmiSSL update requires:

1. A pinned upstream release, archive size, and SHA-256.
2. Payload publication and live-byte verification before manifest publication.
3. A dry-run showing library, certificate, assign, and startup changes.
4. A backup and rollback receipt.
5. Preservation of older ABI libraries, user certificates, and private keys.
6. A post-update clock check and real HTTPS test.
7. Automatic rollback or a clear rollback offer when validation fails.
