Επαλήθευση Ταυτότητας

Το Kora υποστηρίζει δύο προαιρετικές μεθόδους επαλήθευσης ταυτότητας για την ασφάλεια του τελικού σημείου RPC σας: Επαλήθευση με API Key και επαλήθευση HMAC. Αυτός ο οδηγός καλύπτει τη ρύθμιση, την υλοποίηση και τις βέλτιστες πρακτικές ασφαλείας.

Η επαλήθευση ταυτότητας είναι προαιρετική αλλά συνιστάται ιδιαίτερα για παραγωγικές αναπτύξεις. Χωρίς επαλήθευση ταυτότητας, οποιοσδήποτε ανακαλύψει το τελικό σημείο Kora σας μπορεί να υποβάλει συναλλαγές και να καταναλώσει το υπόλοιπο SOL σας.

Η επαλήθευση ταυτότητας Kora ρυθμίζεται στο αρχείο kora.toml στην ενότητα [kora.auth].

Σε αυτό το έγγραφο:

• Επαλήθευση με API Key
• Επαλήθευση HMAC
• Συνδυασμένη Επαλήθευση
• Βέλτιστες Πρακτικές Ασφαλείας
• Εξαιρούμενα Τελικά Σημεία
• Αντιμετώπιση Προβλημάτων

Επαλήθευση με API Key

Απλή επαλήθευση με κοινό μυστικό χρησιμοποιώντας κεφαλίδες HTTP. Μπορείτε να δημιουργήσετε ένα νέο API key χρησιμοποιώντας την εντολή openssl (ή παρόμοια εντολή) στο τερματικό σας:

openssl rand -hex 32

Ρύθμιση Διακομιστή

• Προσθέστε ένα KORA_API_KEY στο .env (μεταβλητές περιβάλλοντος) (έχει προτεραιότητα) ή
• Προσθέστε ένα api_key στο kora.toml:

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"  # Use a strong, unique key

Αυτό το κλειδί θα απαιτείται καθολικά για όλα τα αιτήματα στο τελικό σημείο RPC του Kora.

Υλοποίηση Πελάτη

Συμπεριλάβετε το API key στην κεφαλίδα x-api-key με κάθε αίτημα:

Παράδειγμα cURL:

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -H "x-api-key: kora_live_sk_1234567890abcdef" \
  -d '{"jsonrpc": "2.0", "method": "getConfig", "id": 1}'

Παράδειγμα JavaScript χρησιμοποιώντας το Kora SDK:

const { KoraClient } = require("@solana/kora");

const kora = new KoraClient({
  rpcUrl: "http://localhost:8080",
  apiKey: process.env.KORA_API_KEY
});

const config = await kora.getConfig();
console.log(config);

Παράδειγμα JavaScript χρησιμοποιώντας fetch:

async function callKora(method, params = []) {
  const response = await fetch("http://localhost:8080", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.KORA_API_KEY //'kora_live_sk_1234567890abcdef'
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method,
      params,
      id: 1
    })
  });

  return response.json();
}

const config = await callKora("getConfig");
console.log(config);

Έλεγχος Ταυτότητας HMAC

Αντί να αποστέλλεται ένα κλειδί API με κάθε αίτημα, το HMAC δημιουργεί μια μοναδική κρυπτογραφική υπογραφή που αποδεικνύει ότι γνωρίζετε ένα μυστικό χωρίς να το αποκαλύπτει. Κάθε υπογραφή περιλαμβάνει μια χρονική σήμανση και λήγει μετά από 5 λεπτά, έτσι ώστε τα υποκλαπέντα αιτήματα να μην μπορούν να επαναληφθούν. Οι εισβολείς δεν μπορούν να δημιουργήσουν νέα αιτήματα επειδή δεν διαθέτουν το μυστικό σας κλειδί.

Διαμόρφωση Διακομιστή

• Προσθέστε το KORA_HMAC_SECRET στο αρχείο .env (μεταβλητές περιβάλλοντος) (έχει προτεραιότητα) ή
• Προσθέστε ένα καθολικό hmac_secret στο kora.toml σας (τουλάχιστον 32 χαρακτήρες--μπορείτε να δημιουργήσετε ένα με το openssl rand -hex 32 ή παρόμοιο):

[kora.auth]
hmac_secret = "kora_hmac_your-strong-hmac-secret-key"

Πώς Λειτουργεί το HMAC

1. Ο πελάτης δημιουργεί ένα μήνυμα συνενώνοντας: {timestamp}{request_body}
2. Ο πελάτης υπογράφει το μήνυμα χρησιμοποιώντας HMAC-SHA256 με το κοινό μυστικό
3. Ο πελάτης στέλνει το αίτημα με κεφαλίδες χρονικής σήμανσης και υπογραφής
4. Ο διακομιστής επικυρώνει την υπογραφή και τη χρονική σήμανση (πρέπει να είναι εντός 5 λεπτών)

Υλοποίηση στον Πελάτη

Για να χρησιμοποιήσετε το HMAC από την πλευρά του πελάτη, μπορείτε να χρησιμοποιήσετε το Kora SDK ή τη βιβλιοθήκη crypto σε JavaScript:

1. Δημιουργήστε μια χρονική σήμανση
2. Δημιουργήστε το σώμα του αιτήματος
3. Δημιουργήστε ένα μήνυμα συνενώνοντας τη χρονική σήμανση και το σώμα (π.χ., message = timestamp + body)
4. Δημιουργήστε μια υπογραφή υπογράφοντας το μήνυμα με το μυστικό HMAC (χρησιμοποιώντας τη μέθοδο crypto.createHmac)
5. Στείλτε το αίτημα με τις κεφαλίδες χρονικής σήμανσης (x-timestamp) και υπογραφής (x-hmac-signature)

Παράδειγμα JavaScript με χρήση Kora SDK:

Το Kora SDK αφαιρεί την πολυπλοκότητα της διαδικασίας ελέγχου ταυτότητας HMAC, ώστε να μπορείτε απλώς να καλέσετε τη μέθοδο που θέλετε και το SDK θα χειριστεί τον έλεγχο ταυτότητας για εσάς.

const { KoraClient } = require("@solana/kora");

const kora = new KoraClient({
  rpcUrl: "http://localhost:8080",
  hmacSecret: process.env.KORA_HMAC_SECRET
});

const config = await kora.getConfig();
console.log(config);

Παράδειγμα JavaScript με χρήση βιβλιοθήκης crypto:

async function callKoraHMAC(method, params = []) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const body = JSON.stringify({
    jsonrpc: "2.0",
    method,
    params,
    id: 1
  });

  // Create HMAC signature
  const message = timestamp + body;
  const signature = crypto
    .createHmac("sha256", process.env.KORA_HMAC_SECRET) // kora_hmac_your-strong-hmac-secret-key
    .update(message)
    .digest("hex");

  const response = await fetch("http://localhost:8080", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-timestamp": timestamp,
      "x-hmac-signature": signature
    },
    body: body
  });

  return response.json();
}

const config = await callKoraHMAC("getConfig");
console.log(config);

Συνδυασμένος Έλεγχος Ταυτότητας

Μπορείτε να ενεργοποιήσετε και τις δύο μεθόδους ελέγχου ταυτότητας ταυτόχρονα για μέγιστη ασφάλεια:

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"
hmac_secret = "kora_hmac_your-strong-hmac-secret-key"

Όταν και τα δύο είναι διαμορφωμένα, οι πελάτες πρέπει να στέλνουν τις κεφαλίδες x-api-key, x-timestamp και x-hmac-signature.

Βέλτιστες Πρακτικές Ασφάλειας

• Χρησιμοποιήστε ισχυρά, τυχαία κλειδιά: Ελάχιστο 32 χαρακτήρες με υψηλή εντροπία
• Εναλλάσσετε τακτικά: Αλλάζετε τα κλειδιά περιοδικά (μηνιαία/τριμηνιαία)
• Ασφαλής αποθήκευση: Χρησιμοποιήστε μεταβλητές περιβάλλοντος ή διαχείριση μυστικών (Railway secrets, AWS Secrets Manager, κ.λπ.)
• Ποτέ σκληροκωδικοποίηση: Κρατήστε τα κλειδιά εκτός του πηγαίου κώδικα και των αρχείων καταγραφής
• Χρησιμοποιήστε HTTPS: Χρησιμοποιείτε πάντα TLS σε παραγωγή για να προστατεύσετε τα κλειδιά κατά τη μεταφορά
• Παρακολουθήστε την πρόσβαση: Προσέχετε για ασυνήθιστα μοτίβα ελέγχου ταυτότητας ή επαναλαμβανόμενες αποτυχίες

Εξαιρούμενα Σημεία Πρόσβασης

Το σημείο πρόσβασης /liveness είναι πάντα εξαιρούμενο από τον έλεγχο ταυτότητας για να επιτρέπει ελέγχους υγείας:

# This works even with authentication enabled
curl http://localhost:8080/liveness

Αντιμετώπιση Προβλημάτων

401 Unauthorized με API Key:

• Επαληθεύστε ότι το κλειδί API είναι σωστό και ταιριάζει με τη διαμόρφωση του διακομιστή
• Ελέγξτε ότι η κεφαλίδα x-api-key αποστέλλεται
• Βεβαιωθείτε ότι δεν υπάρχει επιπλέον κενό διάστημα στο κλειδί

401 Unauthorized με HMAC:

• Επαληθεύστε ότι η χρονική σήμανση είναι τρέχουσα (εντός 5 λεπτών)
• Ελέγξτε ότι η κατασκευή του μηνύματος ταιριάζει: {timestamp}{body}
• Βεβαιωθείτε ότι το μυστικό HMAC ταιριάζει με τη διαμόρφωση του διακομιστή
• Επαληθεύστε ότι η υπογραφή είναι σε πεζά δεκαεξαδικά