Macaroons LND 認證機制

LND Default Macaroons:

Location: ~/.lnd/data/chain/bitcoin/mainnet/

admin.macaroon
  • Full permissions
  • Can execute all operations
  • Most sensitive, must be kept secure

readonly.macaroon
  • Read-only permissions
  • Can query balances, invoices, channel status
  • Cannot send payments or modify settings

invoice.macaroon
  • Invoice-related permissions
  • Create and query invoices
  • Cannot send payments

invoices.macaroon (plural)
  • Enhanced invoice permissions
  • Includes invoice subscriptions

chainnotifier.macaroon
  • On-chain notification permissions
  • Subscribe to blocks and transaction confirmations

signer.macaroon
  • Signing permissions
  • Used for remote signers

walletkit.macaroon
  • Wallet operation permissions
  • Address generation, PSBT, etc.

router.macaroon
  • Routing permissions
  • Send payments
  • Route queries

Macaroon Internal Structure:

Components:

1. Identifier
   Unique identifier for tracking

2. Location (optional)
   Issuer location (e.g., "lnd")

3. Caveats (conditions/restrictions)
   • caveat 1: "entity=info"
   • caveat 2: "entity=invoices"
   • caveat 3: "action=read"
   • ...

4. Signature
   HMAC signature for integrity verification

Caveat Types:

First-party caveats:
  • Embedded directly in macaroon
  • Checked by verifier
  • Examples: time limits, IP restrictions

Third-party caveats:
  • Requires third-party verification
  • Enables multi-party authorization
  • LND primarily uses first-party

Creating Custom Macaroons with lncli:

Basic Syntax:

lncli bakemacaroon <permissions...> [flags]

Permission Format: entity:action
  entities: info, offchain, onchain, address, message,
            peers, invoices, macaroon, signer
  actions:  read, write, generate

Examples:

# Read-only macaroon
lncli bakemacaroon info:read offchain:read onchain:read

# Invoice creation only
lncli bakemacaroon invoices:read invoices:write

# Can send payments, but cannot modify channels
lncli bakemacaroon offchain:read offchain:write \
  --save_to=./payment.macaroon

# With time limit
lncli bakemacaroon info:read \
  --timeout 3600 \
  --save_to=./temp.macaroon

# With IP restriction
lncli bakemacaroon info:read \
  --allow_external_permissions \
  --custom_caveat "ipaddr 192.168.1.0/24"

Common Permission Combinations:

Monitoring (e.g., RTL, Thunderhub):
  info:read offchain:read onchain:read peers:read

Payments (e.g., BTCPay Server):
  invoices:read invoices:write offchain:read offchain:write

Full access (equivalent to admin):
  Not recommended, use admin.macaroon

Deriving Restricted Macaroons:

Key Characteristics:

Macaroon's Unique Ability:
  • Can add caveats (restrictions)
  • Cannot remove existing caveats
  • No need to contact original issuer

This means:
  You can turn admin macaroon into restricted version
  But cannot turn readonly into admin

Adding Restrictions:

# Add time limit
lncli constrainmacaroon \
  --macaroon_file=./admin.macaroon \
  --timeout=3600 \
  --output=./temp_admin.macaroon

# Add IP restriction
lncli constrainmacaroon \
  --macaroon_file=./admin.macaroon \
  --ip_address=192.168.1.100 \
  --output=./restricted.macaroon

Now restricted.macaroon:
  • Retains all original permissions
  • But can only be used from 192.168.1.100
  • Other IPs will be rejected

Delegation Scenario:

Scenario: Give third-party service limited access

1. Create restricted version from admin.macaroon
2. Add time limit (1 day)
3. Add IP restriction (service's IP)
4. Grant only necessary permissions

lncli bakemacaroon invoices:read invoices:write \
  --timeout 86400 \
  --ip_address <service_ip> \
  --save_to ./service.macaroon

Macaroon Security Guide:

Protecting admin.macaroon:

WARNING: admin.macaroon = Full node control

Should:
  • Store encrypted
  • Limit file permissions (chmod 600)
  • Never transmit or share
  • Consider using Hardware Security Module (HSM)

Should NOT:
  • Place in publicly accessible location
  • Transmit through insecure channels
  • Give to third-party services
  • Commit to version control

Principle of Least Privilege:

Create dedicated macaroon for each use case:

BTCPay Server:
  invoices:read invoices:write

Monitoring Dashboard:
  info:read peers:read offchain:read onchain:read

Auto-payment Script:
  offchain:write + amount limit

Development Testing:
  Short time limit + IP restriction

Regular Rotation:

1. Periodically generate new macaroons
2. Update services using old macaroon
3. Delete old macaroon (though cannot revoke)

Note: Macaroons cannot be "revoked"
The only way is to change LND's root key
This invalidates all existing macaroons