L402

ライトニング API キー（L402）は、支払いハッシュを含むマカロンである。L402が有効であるためには、支払いハッシュに対応するプリイメージとともに提示される必要がある。

ライトニングAPIキー（L402）は、マカロンの機能とライトニングネットワークのプログラム的特性を活用し、分散システムがユーザーと支払いレシートを認証できるメカニズムを構築する。この認証は、ユーザーや請求書の中央データベースにアクセスすることなく行われる。

L402は、ログイン、電子メールアドレス、パスワードを必要としない、マシン・ツー・マシン経済向けの従量制APIを構築するための基礎となる。

L402は、ライトニング・ネットワークによる支払いの前画像とマカロンである。マカロンはライトニング請求書とともにHTTP経由でユーザーに送信され、請求書の支払いハッシュが注意書きとして含まれる。

有効なL402であるためには、ユーザーは2つの情報を提示する必要がある：

支払いハッシュを含むマカロンである部分的なL402

ライトニングの請求書を支払うことで得られるプリイメージ。

支払いハッシュはプリイメージのハッシュであり、プリイメージはLightningインボイスを全額支払うことによってのみ入手できるため、ルートキーを持っていれば誰でも簡単に検証できる：

L402 が適切な機関によって発行されたものであること。

L402 が関連する機能を搭載していること

ライトニング請求書が支払われたこと

secret,id12345678id,api.domain.com,your macaroon

payment_hash=1107feb30b42fd1a1648c9862006452a8092baa3b62fc474cb43bf42066a0b06

HMAC(secret,4c4ab7a4f7a9,api.domain.com,your macaroon)

preimage=79852a0791225dee00be0a6cf31a1619782c21d35995e118bfc74ad812174035

L402仕様

有効なL402とするためには、マカロンは以下の特徴に従わなければならない：

バージョン - バージョンにより、反復的なマカロンの設計が可能になる。

識別子：

バージョン = 0

ユーザー識別子 - 一意のユーザー識別子により、サービスは、サービス・レベル・メーターのコンテキストで有用なサービスを提供する、異なるマカロン間でユーザーを追跡することができます。32バイトのランダムバイトからなるユーザー識別子は、マカルーンの識別子の代わりに使用される。

識別子 :

user_id = fed74b3ef24820f440601eff5bfb42bef4d615c4948cec8aca3cb15bd23f1013

支払いハッシュ - 支払いハッシュは、請求書の支払いリクエストをマカロンにリンクします。支払い要求が満たされると、支払い者は支払いの証明として対応する前画像を受け取ります。この証明をマカロンと一緒に提供することで、請求書が履行されたかどうかを確認することなく、L402が支払われたことを確認できる。

識別子 :

payment_hash = 163102a9c88fa4ec9ac9937b6f070bc3e27249a81ad7a05f398ac5d7d16f7bea

Caveats

サービスの注意事項に制限はありません。Lightning Labsのサービスでは、以下の3種類の注意書きを使用します。各注意事項は、キーと値のペアで構成され、イコール（=）記号で区切られています。

対象サービス

services」は、L402 がどのサービスへのアクセスを許可されているかを示す。これは、コンマで区切られた複数のサービスのリストと、その階層にすることができる。階層は、基本階層を0として、アクセスレベルを分けることができる。

この例では、L402 はティア 0 でライトニングループへのアクセスが許可されている：

注意事項

services = lightning_loop:0

サービス機能

各サービスはその能力を制限することができる。これらの注意書きは、サービス名に'_capabilities'が付加され、その後にL402の所有者がアクセスを許可されるケイパビリティのリストがカンマで区切られている。この注意書きが存在しない場合、所持者はそのサービスにフルアクセスできる。このサービス能力に関する複数の注意書きが同じL402に存在する場合、それぞれの注意書きは前のものよりも制限的でなければならない。

この例では、L402 のベアラは、Loop Out と Loop In の両方へのアクセスが許可されている：

注意事項

lightning_loop_capabilities = loop_out,loop_in

サービス制約

各サービス・ケイパビリティは、さらに制約することができます。これは、サービス・ケイパビリティで始まる別の注意事項として記録されます。ケイパビリティと同様に、複数の制約がL402に存在する可能性がありますが、各制約は前の制約よりも制限的である必要があります。

以下の例では、ユーザは月に200万サトシのLoop Outのみが許可されている：

注意

loop_out_monthly_volume_sats = 2000000

L402の検証

L402を検証する際、サーバーはオリジナルのマカロンが作成されたルート・キーを要求する。これによりサーバーは、マカロンが適切な権威によって発行されたこと、および各注意書きが適切に修正されたことを、一行ずつ、注意書きごとに検証する。

最後に、プリイメージを支払いハッシュと照合し、未払いの請求書がすべて支払われていることを確認します。

L402がどのように取得されるかをプールで学ぶ

--------------------

プロトコル仕様書

はじめに

この章では、抽象的な L402 HTTP および gRPC プロトコルの仕様について概説する。これは、もし私たちが L402 HTTP/gRPC プロトコルを標準化委員会に提出する場合に提出する文書に沿ったものである。L402 の背後にある、より高いレベルの目的と動機の詳細については、この章を参照してください。

仕様

この節では "L402" 認証方式を定義する。認証情報は <macaroon(s)>:<preimage> のペアで送信される。複数のマカロンは個別にbase64エンコードされ、コロンの前にカンマ区切りでリストされる。

このスキームは、TLSのような外部のセキュアなシステムと併用しない限り、ユーザー認証の安全な方法とはみなされない。

L402認証スキームは、クライアントがアクセスしたいバックエンド・サービスごとに、マカロンと請求書用プリイメージで自分自身を認証する必要があるというモデルに基づいている。サーバーは、リクエストされた特定のバックエンド・サービスについて、マカロンとプリイメージを検証できた場合にのみ、リクエストに対応する。

L402認証スキームは、RFC 7235で規定されているAuthentication Frameworkを以下のように利用する。

チャレンジの場合：スキーム名は「L402」。スキーム名は大文字小文字を区別しないことに注意。クレデンシャルでは、以下の構文となる：

macaroons → <base64 encoding> 、複数のmacaroonsが存在する場合はカンマ区切り。

preimage → <hex エンコーディング

トークン → マカロン ":" preimage

具体的には、上で指定した "token "の構文が使用される。これは、HTTPベーシック認証に使用される "token68 "構文と同等と考えることができる。

クレデンシャルの再利用

L402は、失効され、新たに無効となったL402を含むクライアントリクエストに応答して サーバが新しいチャレンジを発行するまで、再利用されることを意図している。想定される失効条件には、有効期限、N 回を超える使用回数、ティアのアップグレードが必要な一定期間の使用量、その他がある（上位設計文書で詳しく説明）。

L402は、バックエンドサービスごと、またはすべてのLightning Labsサービスごとに使用するように設定することができる。つまり、L402がBos score APIとループインの両方に適用されるか、どちらか一方だけに適用されるかは柔軟である。このような柔軟性があるのは、すべてのサービスが同じL402プロキシによってゲートされ、すべてのバックエンドサービスのすべてのマカロンを検証するためです。

セキュリティの考慮

もしクライアントのL402がMalloryによって傍受された場合、TLSのような暗号化された通信でなければ、L402はMalloryによって使用される可能性がある。

L402認証は、偽造サーバーによるなりすましにも脆弱である。クライアントが希望するバックエンド・サービスのURLをわずかにタイプミスした場合、そのL402を悪意を持って保存し、自分自身の目的に使用するサーバーに接続すると、なりすまし攻撃を受けやすくなる。この攻撃は、L402のユーザーに特定のIPアドレスを要求することで対処できる。ただし、この方法には欠点がある。たとえば、ユーザーがWiFiネットワークを切り替えた場合、そのクレデンシャルは使用できなくなる。

HTTP仕様

このセクションでは、L402プロキシのHTTP部分のプロトコルを指定する。

L402プロキシされたバックエンドサービスのURIに対するリクエストを受信したとき、そのURIにクレデンシャルが欠けていたり、何らかの方法で無効あるいは不十分なL402が含まれていたりする場合、サーバーは402(Payment Required)ステータスコードを使用してチャレンジで応答するべきである。公式には、HTTP RFCのドキュメントでは、ステータスコード402は「reserved for future use」である。

例えば

HTTP/1.1 402 Payment Required

日付月, 04 Feb 2014 16:50:53 GMT

WWW-Authenticate：L402 macaroon="AGIAJEemVQUTEyNCR0exk7ek90Cg=="、invoice="lnbc1500n1pw5kjhmpp5fu6xhthlt2vucmzkx6c7wtlh2r625r30cyjsfqhu8rsx4xpz5lwqdpa2fjkzep6yptksct5yp5hxgrrv96hx6twvusycn3qv9jx7ur5d9hkugr5dusx6cqzpgxqr23s79ruapxc4j5uskt4htly2salw4drq979d7rcela9wz02elhypmdzmzlnxuknpgfyfm86pntt8vvkvffma5qc9n50h4mvqhngadqy3ngqjcym5a"

ここで、"AGIAJEemVQUTEyNCR0exk7ek90Cg=="は、クライアントが認可されたリクエストごとに含めなければならないマカロンであり、"lnbc1500n1pw5kjhmpp... "は、クライアントが認可されたリクエストごとに含めなければならない前画像を明らかにするために支払わなければならない請求書である。

言い換えれば、オーソライズを受けるために、クライアントは以下のことを行う：

1.

サーバーから請求書を支払い、請求書の前画像を公開する。

2.

base64エンコードされたマカロン(複数可)、コロン(":")1つ、および16進エンコードされた 前画像を連結してL402を構築する。

マカロンと前画像はともにASCIIベースのフォーマットでエンコードされたバイナリデータであるため、以下のような処理が必要である。