When receiving a BOLT 12 invoice originating from either an invoice
request or a refund, the invoice should only be paid once. To accomplish
this, require that the invoice includes an encrypted payment id in the
payer metadata. This allows ChannelManager to track a payment when
requesting but prior to receiving the invoice. Thus, it can determine if
the invoice has already been paid.
InvoiceRequest::verify_and_respond_using_derived_keys takes a payment
hash. To avoid generating one for invoice requests that ultimately
cannot be verified, split the method into one for verifying and another
for responding.
BOLT 12 messages need to be signed in the following scenarios:
- constructing an InvoiceRequest after scanning an Offer,
- constructing an Invoice after scanning a Refund, and
- constructing an Invoice when handling an InvoiceRequest.
Extend the NodeSigner trait to support signing BOLT 12 invoices such
that it can be used in the latter contexts. The method could be used
in an OffersMessageHandler.
Bolt12Invoice can either be for an Offer (via an InvoiceRequest) or a
Refund. It wraps those types, so expose their methods on both
Bolt12Invoice and UnsignedBolt12Invoice.
Since Refund does not have all the Offer/InvoiceRequest methods, use an
Option return type such that None can returned for refund-based
invoices.
For methods that are duplicated between Offer/InvoiceRequest and
Bolt12Invoice, prefer the (non-Option, if applicable) method from
Bolt12Invoice (e.g., amount_msats, signing_pubkey).
Various messages wrap InvoiceRequestContents, which shouldn't be exposed
as it is an implementation detail. Define a macro for InvoiceRequest
accessor methods so that these messages can also define them.
InvoiceRequest wraps OfferContents, which shouldn't be exposed as it is
an implementation detail. Define a macro for Offer accessor methods so
that InvoiceRequest and UnsignedInvoiceRequest can also define them.
InvoiceBuilder is parameterized by a SigningPubkeyStrategy, either
ExplicitSigningPubkey and DerivedSigningPubkey. It also holds an
Option<KeyPair>, which may be None and Some for those strategies,
respectively. This leads to methods for InvoiceBuilder parameterized by
DerivedSigningPubkey needing to blindly unwrap the Option<KeyPair>.
Instead, have DerivedSigningPubkey wrap KeyPair.
The function used to sign BOLT 12 messages only takes a message digest.
This doesn't allow signers to independently verify the message before
signing nor does it allow them to derive the necessary signing keys, if
needed.
Introduce a TaggedHash wrapper for a message digest, which each unsigned
BOLT 12 message type constructs upon initialization. Change the signing
function to take AsRef<TaggedHash>, which each unsigned type implements.
This allows the signing function to take any unsigned message and obtain
its tagged hash.
We missed one method that now cannot be bindings exported - the
`payment_paths` method, as it returns a slice of objects, which
cannot be supported in bindings.
If an InvoiceRequest or an Invoice delivered via an onion message cannot
be handled, the recipient should reply with an InvoiceError if a reply
path was given. Define the message and conversion from SemanticError.
The BOLT 12 test vectors had inadvertently left out a signature, but it
has since been added. Include a signature check in the corresponding
test for completeness.
The previous test vectors contained recurrences and older TLV types, and
therefore couldn't be parsed. Update the tests with the latest test
vectors from the spec and stop ignoring the tests.
These were added to help debug an encoding issue. However, the encoding
code was moved to the blinded_path module. Additionally, the test vector
used an old TLV encoding.
For offers where the signing pubkey is derived, the keys need to be
extracted from the Offer::metadata in order to sign an invoice.
Parameterize InvoiceBuilder such that a build_and_sign method is
available for this situation.
Stateless verification of Invoice for Offer
Verify that an Invoice was produced from a Refund constructed by the
payer using the payer metadata reflected in the Invoice. The payer
metadata consists of a 128-bit encrypted nonce and possibly a 256-bit
HMAC over the nonce and Refund TLV records (excluding the payer id)
using an ExpandedKey.
Thus, the HMAC can be reproduced from the refund bytes using the nonce
and the original ExpandedKey, and then checked against the metadata. If
metadata does not contain an HMAC, then the reproduced HMAC was used to
form the signing keys, and thus can be checked against the payer id.
Add support for deriving a transient payer id for each Refund from an
ExpandedKey and a nonce. This facilitates payer privacy by not tying any
Refund to any other nor to the payer's node id.
Additionally, support stateless Invoice verification by setting payer
metadata using an HMAC over the nonce and the remaining TLV records,
which will be later verified when receiving an Invoice response.
Verify that an Invoice was produced from an InvoiceRequest constructed
by the payer using the payer metadata reflected in the Invoice. The
payer metadata consists of a 128-bit encrypted nonce and possibly a
256-bit HMAC over the nonce and InvoiceRequest TLV records (excluding
the payer id) using an ExpandedKey.
Thus, the HMAC can be reproduced from the invoice request bytes using
the nonce and the original ExpandedKey, and then checked against the
metadata. If metadata does not contain an HMAC, then the reproduced HMAC
was used to form the signing keys, and thus can be checked against the
payer id.
Add support for deriving a transient payer id for each InvoiceRequest
from an ExpandedKey and a nonce. This facilitates payer privacy by not
tying any InvoiceRequest to any other nor to the payer's node id.
Additionally, support stateless Invoice verification by setting payer
metadata using an HMAC over the nonce and the remaining TLV records,
which will be later verified when receiving an Invoice response.
