wrapAndSign method
Create a json envelope around payload in a format that can be verified
by verifyEnvelopeSignature.
payload must be a String or a json-encodable object.
toEncodable is passed directly to jsonEncode.
Read the jsonEncode docs to learn how to use it.
type says what the envelope is for, and applications leave it alone.
Its default, EnvelopeType.app, is a type no verifier inside this library
accepts, so an application signing data someone else influenced cannot be
walked into producing a chain link, a key package or an advertisement.
Implementation
Future<SignedEnvelope> wrapAndSign(
Object? payload, {
Object? Function(Object? nonEncodable)? toEncodable,
EnvelopeType type = EnvelopeType.app,
}) async {
// NOTE: resolved before the try — that catch reports a payload that could
// not be encoded, and a failed keyfile read is not one.
final keys = await signingKeys;
try {
// One signature per signing key this enrollment holds, whose public
// halves are what [ApkamSigning.publishPublicSigningKey] publishes, so a
// verifier can check against the per-enrollment `_apsk`. All of them
// rather than the strongest, because the verifier chooses: it takes the
// strongest algorithm the envelope and the `_apsk` share.
//
// NOTE: plural signatures are not a bridge across a verifier gap — an
// attacker strips the stronger and the verifier accepts the weaker,
// because nothing lets it insist on the stronger.
return signEnvelope(
payload,
keys: keys,
type: type,
enrollmentId: enrollmentId,
toEncodable: toEncodable,
);
} on Object catch (e, st) {
logger.severe(
"Failed to encode payload for signing (you may need to pass "
"toEncodable to wrapAndSign): $e, $st",
);
rethrow;
}
}