API Reference

CPAttack{LMT, KT, PT, BCT, LM, LMO}

Accumulator state for a batch differential power analysis attack.

CPAttack stores the predictors, leakage models, key range, preallocated hypothetical leakage buffers, and the underlying BatchCorrelation statistics used to correlate measured samples with predicted leakages. It is the object returned by run_attack(...), accepted by the incremental run_attack(attack, data, samples; ...) overload, and reduced to key scores with getScores.

The type parameters are implementation details:

• LMT: element type used for hypothetical leakage values.
• KT: key range type.
• PT: predictor container type.
• BCT: underlying batch-correlation accumulator type.
• LM: leakage-model container type.
• LMO: leakage-model offset table type.

Most callers should construct this through CPAttack(...) or run_attack(...) rather than by calling the field constructor directly.

CPAttack(predictor, leakagemodel, nsamples; batchsize=128, keyrange=nothing)

Construct a CPAttack for one predictor and one leakage model.

This is a convenience wrapper around the tuple constructor. nsamples must match the number of rows in every sample matrix later added to the attack. When keyrange is nothing, all candidates from 0:nkeys(predictor)-1 are used.

CPAttack(predictors::Tuple, leakagemodels::Tuple, nsamples; batchsize=128, keyrange=nothing)

Construct a CPAttack for multiple compatible predictors and leakage models.

All predictors must expose the same number of key candidates and predicted value type. All leakage models must produce the same leakage element type for that predicted value type. The constructor allocates the internal BatchCorrelation object and work buffers sized for nsamples, batchsize, length(keyrange), the number of predictors, and the total number of leakage-model outputs.

add!(attack::CPAttack, samples::AbstractMatrix, input::AbstractMatrix)

Add a batch of traces to attack.

samples must be an nsamples x nbatch matrix and input must be an ndata x nbatch matrix with the same trace count. nbatch must not exceed attack.batchsize. For every trace, predictor, key candidate, leakage model, and leakage-model output, the method computes the hypothetical leakage and adds the measured/predicted batch to the internal correlation accumulator.

add!(attack::CPAttack, samples::AbstractVector, input::AbstractVector)

Add one trace to attack.

samples is reshaped as one nsamples x 1 sample column and input is reshaped as one public-input column, then forwarded to the matrix overload.

add!(attack::CPAttack, other::CPAttack) -> CPAttack

Merge accumulated statistics from other into attack.

The two attacks must have matching predictor count, leakage-output count, key count, key range, and sample count. Predictor and leakage-model identities are not currently compared, so callers are responsible for only merging attacks created from equivalent configurations.

getCorrelation(attack::CPAttack)

Return the raw correlation matrix from the underlying batch-correlation accumulator.

Rows correspond to sample indices. Columns are laid out as the flattened combination of predictors, leakage-model outputs, and key candidates used internally by CPAttack.

nobservations(attack::CPAttack)

Return the number of trace observations accumulated in attack.

getScores(attack::CPAttack; nslices=1, reductionfun=max, lmrange=1:attack.NO, lmreductionfun=+) -> AbstractArray

Reduce raw correlations from attack into key scores.

The raw correlation matrix is reshaped as (samples_per_slice, nslices, leakage_outputs, key_candidates, predictors). Absolute correlations are reduced over the sample dimension with reductionfun, optionally restricted to lmrange, and then reduced across leakage-model outputs with lmreductionfun.

Use nslices to split the sample axis into equal contiguous windows before sample reduction. nslices must exactly divide attack.nsamples.

The returned array has singleton dimensions dropped. For a single predictor and one slice, this is typically a vector indexed by key_value + 1; for multiple predictors or slices, extra dimensions are retained.

run_attack(predictors, leakagemodels, data, samples; kwargs...) -> CPAttack
run_attack(attack::CPAttack, data, samples; kwargs...) -> CPAttack

Run a batch differential power analysis attack by correlating measured samples with hypothetical leakages generated from one or more predictors and leakage models.

Inputs

• predictors: a predictor, or a tuple of compatible predictors. A predictor may be one supplied by this package or a user-defined type that implements the predictor interface. Currently available AES predictors from src/aes.jl include:
  • AesSbox{N}() predicts the first-round AES S-box output for input byte N and one 8-bit key-byte candidate.
  • AesMcol{R,C}(T) predicts the 32-bit MixColumns contribution for state row R, column C, using the lookup table matrix T = makeT().
  • AesSboxHD{R,C}(... ) predicts the Hamming-distance byte between a first-round S-box output and a second-round S-box output for row R, column C; its key candidate is the 16-bit packed value consumed by predict(::AesSboxHD, input_column, key_value).
  Custom predictors should subtype Predictor{T} for the predicted value type T, and provide predict(predictor, input_column, key_value) and nkeys(predictor). Predictors used together must have the same nkeys(...) value and the same valuetype(...); for example, do not mix AesSbox (UInt8) and AesMcol (UInt32) in one attack.
• leakagemodels: a leakage model, or a tuple of compatible leakage models. A leakage model may be one supplied by this package or a user-defined type that implements the leakage-model interface. Currently available leakage models from src/types.jl include:
  • IdentityLM() uses the predicted value directly as one leakage output.
  • HammingWeightLM() uses count_ones(prediction) as one leakage output.
  • BitsLM() emits one leakage output per prediction bit: 8 outputs for UInt8 predictors and 32 outputs for UInt32 predictors.
  Custom leakage models should subtype LeakageModel, and provide leak(model, output_index, prediction), noutputs(model, prediction_type), and leaktype(model, prediction_type). Leakage models used together must have the same leaktype(model, valuetype(first(predictors))); for example, IdentityLM() can be combined with BitsLM() for UInt8 AES predictors, but not for UInt32 predictors.
• data: an ndata x ntraces matrix. Each column is the public input for one trace and is passed to every predictor as input_column.
• samples: an nsamples x ntraces matrix. Each column contains the measured power samples for the corresponding column in data.
• attack: an existing CPAttack accumulator. The second method adds the supplied data and samples to this object and returns the same object.

data and samples must have the same number of trace columns. The sample row count defines attack.nsamples when constructing a new attack, and must match the existing accumulator when adding through BatchStats.add!.

Keyword Arguments

• keyrange = nothing: key candidates to evaluate. When nothing, the full range 0:nkeys(first(predictors))-1 is used. When continuing an existing attack, the supplied range must match attack.keyrange.
• logger = nothing: optional logger collection. Each logger is initialized with init(logger, ntraces) before processing and receives progress(...) callbacks after every processed batch.
• batchsize = 128: maximum number of trace columns processed at once. When continuing an existing attack, this must match attack.batchsize.
• reductionfun = max: reduction function used only for logger score snapshots produced through getScores.
• lmreductionfun = +: leakage-model-output reduction used only for logger score snapshots produced through getScores.

Processing Model

For each trace, predictor, key candidate, leakage model, and leakage-model output index, the attack computes leak(model, output_index, predict(predictor, data[:, trace], key_value)). Those hypothetical leakages are correlated with the measured samples through the internal BatchCorrelation accumulator.

The returned CPAttack stores accumulated statistics, not final scores. Use getScores(attack; ...) to reduce correlations into key scores. Partial attacks with compatible dimensions can be combined with add!(attack1, attack2).

Errors

The method throws if data and samples have different trace counts, if an existing attack is resumed with a different keyrange or batchsize, or if the predictor/leakage model tuple contracts are violated.

run_attack(attack::CPAttack, data, samples; kwargs...) -> CPAttack

Add data and samples to an existing CPAttack accumulator.

This overload is the incremental form used when traces are processed in multiple chunks. It validates that data and samples have the same number of trace columns, that batchsize matches attack.batchsize, and that any explicit keyrange matches attack.keyrange. It then walks through the traces in batches and calls add!(attack, samples_batch, data_batch).

logger, reductionfun, and lmreductionfun have the same meaning as in the constructor-style run_attack method: loggers are initialized for this call and receive score snapshots after each processed batch.