Working on disconnected networks

On a network with no route to the internet, the things a connected machine does quietly in the background stop working. Package managers cannot fetch, certificate checks cannot reach a revocation server, and nothing updates itself. The work moves to people, and it comes down to answering three questions about every file that crosses the boundary: is it the file I meant to bring, is it intact, and what is inside it?

This guide covers the basic techniques. It is not a transfer policy. The rules for what may cross, and how, belong to the organization that owns the network.

Checksums#

A checksum, or hash, is a short fingerprint computed from the contents of a file. Change one byte and the fingerprint changes completely. Two files with the same SHA-256 checksum are, for practical purposes, the same file.

Compute one:

Save one alongside the file, and check it later:

sha256sum file.tar.gz > file.tar.gz.sha256
sha256sum -c file.tar.gz.sha256

The second command prints file.tar.gz: OK when the file is unchanged.

Use SHA-256 or stronger. MD5 and SHA-1 still appear on old download pages, but both can be deliberately fooled and should not be relied on to detect tampering.

A transfer manifest#

When you move a folder instead of one file, make a manifest: a list of every file with its checksum. On the sending side:

( cd payload && find . -type f -print0 | sort -z | xargs -0 sha256sum ) > payload.sha256

On the receiving side, with the folder and the manifest both carried across:

( cd payload && sha256sum -c ../payload.sha256 )

Every line should end in OK. A line ending in FAILED is a file that changed. A “No such file” message is a file that went missing.

The manifest catches changed and missing files. To catch extra files that were not in the original, count them on both sides:

find payload -type f | wc -l
wc -l < payload.sha256

The two numbers should match.

A useful manifest for a transfer record also notes who prepared it, when, from what source and for what purpose. Keep it with the approval paperwork.

1. OutsideGenerate manifestCompute sorted list of SHA-256 checksums for all files in payload folder.
2. OutsideCount source filesRecord total file count alongside payload.sha256 manifest.
3. TransferCarry across boundaryMove payload and manifest across according to network transfer rules.
4. InsideVerify checksumsRun sha256sum -c to ensure all files are unchanged (OK) with no FAILED lines.
5. InsideVerify file countConfirm file count matches manifest lines to ensure no extra files were introduced.

Reading a certificate#

A certificate binds a name to a public key and is signed by an authority that vouches for it. On a disconnected network you often have to inspect one by hand, because the browser’s usual machinery cannot reach outside.

Print the fields that matter:

openssl x509 -in server.pem -noout -subject -issuer -dates -ext subjectAltName

Print everything, including key size, permitted uses and the signature algorithm:

openssl x509 -in server.pem -noout -text

See the certificates a running server presents:

openssl s_client -connect server.internal.example:443 -showcerts

Checking a chain#

A server certificate is trusted because of a chain: it is signed by an intermediate authority, which is signed by a root authority your machine already trusts. To verify a certificate against a file holding the authorities you trust:

openssl verify -CAfile ca-chain.pem server.pem

It prints server.pem: OK when the chain is complete and every signature checks. The usual failures are:

Two things are particular to closed networks:

• Private authorities. Internal networks, including government ones, run their own certificate authorities. Their root certificates are not built into ordinary browsers and operating systems. They have to be installed, from a source you trust, before anything they signed will verify.
• Clocks. A machine with no time source drifts. A wrong clock makes good certificates look expired or not yet valid. Check the date before you blame the certificate.

DecisionWhat result does openssl verify return?

• server.pem: OK
  Certificate trustedChain is complete, signatures are valid, and dates are currently valid.
• unable to get local issuer certificate
  Missing authorityAn intermediate or root CA certificate is missing from the CAfile.
• certificate has expired / not yet valid
  Time error or driftCurrent date is outside validity window, or the disconnected machine’s clock drifted.
• self-signed certificate
  Untrusted originThe certificate vouches for itself and has not been added to your trusted CA bundle.

Expiry and revocation#

To find certificates about to expire, ask whether one will still be valid a set number of seconds from now. Thirty days is 2,592,000 seconds:

openssl x509 -in server.pem -noout -checkend 2592000

The command says whether the certificate will expire in that time, and sets its exit status to match, so it can be used in a script.

Revocation is harder. A certificate can be cancelled before it expires, and the normal ways of finding out need a network connection to the issuing authority. On a disconnected network the lists of revoked certificates have to be brought in on a schedule, like any other update. A certificate that verifies against a stale list may have been revoked since.

Lockfiles#

A lockfile records the exact version of every package a project depends on, usually with a checksum for each. For this site, that file is package-lock.json. An entry looks like this:

"node_modules/react": {
  "version": "19.3.0",
  "resolved": "https://registry.npmjs.org/react/-/react-19.3.0.tgz",
  "integrity": "sha512-..."
}

On a closed network a lockfile is three things at once: the list of what to bring in, the means of checking each item, and a record of what a build contained. Install from it with a command that refuses to deviate, such as npm ci, so that the build inside matches the build that was reviewed outside.

Read the resolved lines. Every one that points at a public registry is a package that must be mirrored inside before the build can run.

Container images#

A container image is identified two ways. A tag, such as clearedstack:1, is a label that can be moved to point at different contents. A digest, a long string starting with sha256:, is computed from the contents and cannot.

When an image crosses a boundary as a file, compare its digest on both sides. On a host that runs containers with containerd, its own command-line tool, ctr, lists and exports images:

ctr -n k8s.io images ls | grep clearedstack
ctr -n k8s.io images export clearedstack.tar registry.example.com/clearedstack@sha256:<digest>

Check the exported file in transit with an ordinary sha256sum, then import it on the inside:

ctr -n k8s.io images import clearedstack.tar

Inside the network, refer to images by digest in anything that matters:

image: registry.internal.example/clearedstack@sha256:<digest>

A tag tells you what someone called an image. A digest tells you what it is.

OutsideTransitInside

1. 1 · OutsideRecord image digestNote the exact sha256 digest shown by ctr images ls.
2. 2 · OutsideExport OCI archiveExport with ctr images export and generate sha256sum.
3. 3 · TransitMedia transferCarry file across network boundary per transfer rules.
4. 4 · InsideVerify checksumCheck file integrity using sha256sum -c before importing.
5. 5 · InsideImport & check digestctr images import and verify digest matches outside digest exactly.

Keep a record#

For everything that crosses, write down enough to answer questions a year later:

• what it is, and which version
• where it came from: the address, the commit or the release
• its checksum or digest
• who reviewed it and what they checked
• the date it was brought in
• what it replaced

Then set a date to look again. Software on a closed network does not learn about its own vulnerabilities. Someone has to bring that news in.

Sources#

• NIST, FIPS 180-4, “Secure Hash Standard”, for SHA-256, at csrc.nist.gov.
• RFC 5280, “Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile”.
• The OpenSSL manual pages for x509, verify and s_client.
• The npm documentation for package-lock.json and npm ci.
• The Open Container Initiative image specification, for image digests.