Decrypts and imports a bundle you have downloaded, and reports what
landed.
ciphertext is the file offeredHistoryBundle pointed at, exactly
as it came back. The key is not a parameter: it arrived in the
announcement, which this library recorded, so downloading bytes is all you
do and no key material passes through your product.
The announcement must already have been ingested for the same reason it
carries the key -- it is also what says who sent the bundle and which
device signed it. A download handed to this call without one is refused
with no_offer rather than trusted on its own say-so.
A sender this device cannot vouch for is refused, loudly. The
underlying library's own answer in that case is to drop the bundle and
return success, which is indistinguishable from an import that worked;
this call checks first and throws sender_not_trusted instead. The bar is
fixed by the protocol at "seen this device before, and nothing about it
has changed" or better, and a product cannot relax it -- what fixes it is
verifying the sender.
Bytes that are not the announced bundle throw bundle_unreadable. The
key and the expected hash both come from the announcement rather than from
you, so a download that fetched an error page, stopped short, or was
altered in the repository fails here instead of being imported.
Decrypts and imports a bundle you have downloaded, and reports what landed.
ciphertextis the file offeredHistoryBundle pointed at, exactly as it came back. The key is not a parameter: it arrived in the announcement, which this library recorded, so downloading bytes is all you do and no key material passes through your product.The announcement must already have been ingested for the same reason it carries the key -- it is also what says who sent the bundle and which device signed it. A download handed to this call without one is refused with
no_offerrather than trusted on its own say-so.A sender this device cannot vouch for is refused, loudly. The underlying library's own answer in that case is to drop the bundle and return success, which is indistinguishable from an import that worked; this call checks first and throws
sender_not_trustedinstead. The bar is fixed by the protocol at "seen this device before, and nothing about it has changed" or better, and a product cannot relax it -- what fixes it is verifying the sender.Bytes that are not the announced bundle throw
bundle_unreadable. The key and the expected hash both come from the announcement rather than from you, so a download that fetched an error page, stopped short, or was altered in the repository fails here instead of being imported.