TOIFAS/README.md

Keyed Masking for Secure Multi-User Semantic Communication

Reproducibility package for the manuscript Mask-as-Key Secure Multiple Access for Semantic Communications: Physical-Layer Encryption and Jamming Robustness, submitted to the IEEE Transactions on Information Forensics and Security.

Every figure and table in the paper is regenerated from this repository. Experiment scripts write CSV files to data/ and never draw; replot_security.py reads only data/ and writes the figure PDFs to fig/; make_tables.py prints the LaTeX rows of the result tables.

Idea

Multi-user semantic communication superposes several users on one frame and multiplies each user embedding by a distinct pattern so that the receivers can separate them. This code treats that pattern as a secret key. One keyed operation then encrypts each user against a receiver without the key, separates the users, and spreads a jammer that does not hold the key, at no extra bandwidth, power, or rate.

Layout

code/
  sse_lib.py            transmit and receive core, channel, training, OMA reference
  exp_full.py           stages A-F and L: SNR sweep, key length, jamming across
                        schemes, key families, scheme comparison, attack difficulty
  exp_kpa.py            stage H: known-plaintext attack on the key
  exp_refresh.py        stage K: the key-refresh layer, invariance group
  exp_permkpa.py        permutation-key known-plaintext attack (Fig. 7)
  check_cov_*.py        ciphertext-only covariance-attack checks (referee M1)
  exp_real_sec.py       stage G: real BERT WordPiece token streams
  verify_math.py        closed-form checks V1-V11, PASS/FAIL and verify_math.csv
  exp_learned.py        every KM (lrn.) artifact, one function per stage
  run_learned_reg.py    runs those stages in order, sens before brute
  merge_learned_rows.py folds the learned rows into the two table sources
  report_learned.py     every learned number beside its structured one
  diag_whygap.py        why a fixed key beats a learned one here
  diag_jscc.py          where a learned mask would win instead
  replot_security.py    every result figure, from data/ to fig/
  make_tables.py        LaTeX rows of every result table, from data/
  feasibility_security.py   early CPU-sized study, kept for the record
data/                   CSV results, one file per stage
fig/                    figure PDFs, regenerated by replot_security.py

Reproducing

Requires Python 3, PyTorch, NumPy, and Matplotlib. The real-token stage additionally needs datasets and transformers. A CUDA device is recommended; the code falls back to CPU. Under Windows install PyTorch in WSL, because the native Windows build does not load the CUDA libraries.

python verify_math.py        # closed-form verification, prints PASS/FAIL
python exp_full.py           # stages A-F and L
python exp_kpa.py            # known-plaintext attack
python exp_refresh.py        # the key-refresh layer
python exp_real_sec.py       # real token streams
python exp_permkpa.py        # permutation-key known plaintext
python exp_infotheory.py     # mutual information and equivocation
python exp_semantic.py       # semantic-similarity leakage
python exp_users_csi.py      # load and channel-estimate sweeps
python check_cov_attack.py   # ciphertext-only covariance attack
python diag_maskdegen.py     # learned-key support degeneracy
python check_family_enum.py  # ciphertext-only enumeration of the key family
python run_learned_reg.py    # every KM (lrn.) artifact, regularized keys
python merge_learned_rows.py # the learned rows of the two result tables
python replot_security.py    # all figures from the CSVs
python make_tables.py        # LaTeX rows of the result tables

The learned keys are the regularized ones of Section V-C, trained under the two penalties rather than under the cross-entropy alone. Training on the cross-entropy alone drifts to disjoint sparse supports, which is an orthogonal slot allocation rather than a superposition; diag_whygap.py measures that drift and exp_learned.learned_model says why the regularized keys are the ones every figure draws.

Seeds are fixed: training 1, evaluation 777, attacker key guess 20260813, key recovery 4242, brute-force search 31, cross-scheme comparison 11, key refresh 5150. Re-running reproduces the released CSV files.

Conventions

Flat Rayleigh fading, one gain per user per frame, with unit mean power. A frame carries unit energy, so the SNR in decibels is the frame energy over the total noise across all d real dimensions, and every scheme in a comparison spends the same energy, bandwidth and rate. The jamming-to-signal ratio is the jammer energy over the same frame energy. Logarithms in an entropy or an information rate are base two.

Figure and table map

Artifact	Script	Data
Fig. 2 SER against SNR	exp_full.stage_A, stage_N	sec_snr.csv, sec_snr_learned.csv
Fig. 3 key length	exp_full.stage_B, exp_learned.keylen, .keylen_perm	sec_keylen.csv, sec_keylen_learned.csv, sec_keylen_perm.csv
Fig. 4 jamming (5 curves)	exp_full.stage_C, stage_L, exp_learned.jamming	sec_jam_cmp.csv, sec_jam.csv, sec_jam_learned.csv
Fig. 5 key sensitivity	exp_full.stage_I, exp_learned.sens	sec_sens_cmp.csv, sec_sens_learned.csv
Fig. 6 brute-force search	exp_full.stage_I, stage_F, stage_J, exp_learned.brute	sec_brute_cmp.csv, sec_brute.csv, sec_brute_learned.csv
Fig. 7 known-plaintext attack	exp_kpa, exp_permkpa, exp_learned.kpa	kpa.csv, pkpa.csv, kpa_learned.csv
Fig. 8 real token streams	exp_real_sec, exp_learned.real	real_sec_ter.csv, real_sec_ter_learned.csv
Scheme comparison table	exp_full.stage_E, exp_learned.compare, merge_learned_rows	sec_compare.csv
Key families (Sec. VI-G prose)	exp_full.stage_D	sec_maskfam.csv, sec_regjam.csv
Headline recovery (Sec. VI-H prose)	exp_real_sec	real_sec_stats.json
Key refresh table	exp_refresh, exp_learned.refresh, merge_learned_rows	refresh_summary.csv, refresh_kpa.csv
Information-theoretic leakage	exp_infotheory	infotheory.csv
Semantic similarity	exp_semantic	semantic.csv
Load and channel-estimate sweeps	exp_users_csi	users.csv, csi.csv
Permutation-variant check	exp_full.stage_M	perm_variant.csv

Run one stage on its own with python code/exp_full.py stage_B, or the whole chain with no argument. | Key-space attacks (Sec. VI-F) | check_family_enum | family_enum.csv | | Covariance attack (Sec. IV) | check_cov_attack | cov_attack.csv | | Learned-key degeneracy (Sec. VI-F) | diag_maskdegen | maskdegen.csv | | Closed-form and symbolic checks | verify_math | verify_math.csv | | Why a fixed key wins here (not in the paper) | diag_whygap | whygap.csv | | Where a learned mask would win (not in the paper) | diag_jscc | jscc.csv |

Security scope

The analysis covers an adversary that observes transmitted frames. The masking is linear, so an adversary that also learns the indices some frames carried recovers the key from a few frames, which exp_kpa.py measures. The key must therefore be refreshed per coherence block from a shared seed. exp_refresh.py implements that layer and shows why it has to draw from the transformations that leave the decision statistic invariant: a refresh that installs fresh orthogonal keys instead costs the legitimate users a factor of 2.3, while the invariant refresh costs nothing and raises the per-block key from 23.8 to 364.6 bits.

License

MIT for the code. The AG News data and the language-model tokenizer are obtained from their own sources under their own terms.