crypto — n_pbt_crypto #

← Komponentenreferenz · Inhalt des Handbuchs

Hashes, HMAC, Verschlüsselung per Passwort, Zufallswerte und RSA-Signaturen — die Web Crypto API der WebView2-Engine, die Ihr PowerBuilder 10 sonst nirgends hat. Keine Dritt-DLL, kein Dienst: was der Arbeitsplatz bereits kann, für PowerScript.

▶ Live ansehen — Demoanwendung, Kachel Crypto: die Ergebnisse, der zugehörige Code und diese Seite nebeneinander.

Kurzüberblick #

Schnellstart #

n_pbt_crypto lnv_crypto
string ls_hash, ls_cipher

lnv_crypto = create n_pbt_crypto

// The fingerprint of a text, in hexadecimal
ls_hash = lnv_crypto.of_sha256("Invoice 4152, 690.00 EUR")

// A secret kept with a password : one string to store, the password to keep
ls_cipher = lnv_crypto.of_encrypt("s3cret", "The safe code is 4152.")
MessageBox("Back", lnv_crypto.of_decrypt("s3cret", ls_cipher))

destroy lnv_crypto

Jede Methode ist ein Aufruf, der seinen Wert liefert: kein Ereignis, kein Warten.

Die Formate, für andere Werkzeuge lesbar #

• Hashes und HMAC: Kleinbuchstaben-Hexadezimal, der Text als UTF-8 gelesen — Python, Java und openssl dgst liefern denselben Wert.
• of_encrypt: eine einzige Base64-Zeichenkette mit Salt (16 Bytes), Nonce (12) und dem AES-256-GCM-Chiffrat; der Schlüssel wird per PBKDF2-SHA-256 mit 100 000 Runden aus dem Passwort abgeleitet. of_decrypt mit demselben Passwort genügt, auf jedem Arbeitsplatz.
• Schlüssel: PEM, öffentlich als SPKI (BEGIN PUBLIC KEY), privat als PKCS#8 (BEGIN PRIVATE KEY); Signaturen RSASSA-PKCS1-v1_5 mit SHA-256, Base64 — was openssl liest und prüft.
• Kein MD5: Web Crypto bietet es nicht an, und nichts sollte es mehr verlangen.

Eigenschaften #

Konstanten: HASH_MD5, HASH_SHA1, HASH_SHA256, HASH_SHA384, HASH_SHA512 für den Algorithmus; KEY_2048, KEY_3072, KEY_4096 für die Größe eines RSA-Schlüssels, KEY_RSA_2048, KEY_EC_P256, KEY_ED25519 für die Art eines Paars; JWT_HS256, JWT_RS256, JWT_ES256, JWT_EDDSA; CHARSET_ALL, CHARSET_ALPHANUM, CHARSET_LETTERS, CHARSET_DIGITS, CHARSET_HEX.

Methoden #

Beispiele #

Prüfen, dass eine Datei unverändert ist #

string ls_expected, ls_actual
ls_expected = ProfileString("deploy.ini", "files", "orders.pbd", "")
ls_actual = lnv_crypto.of_hash_file(n_pbt_crypto.HASH_SHA256, "orders.pbd")
if ls_actual <> ls_expected then MessageBox("Deploy", "orders.pbd is not the file that was tested.")

Ein Anhang in Base64 für eine API #

// Sending : the file's bytes in the JSON body
lnv_j.of_set_string("filename", "invoice_4152.pdf")
lnv_j.of_set_string("content", lnv_crypto.of_base64_encode_file("C:\invoices\4152.pdf"))
lnv_rest.of_post("https://api.example.com/documents", lnv_j.of_text())

// Receiving : the answer's attachment, back on disk
lnv_crypto.of_base64_decode_to_file(lnv_rest.of_json_value("content"), "C:\inbox\receipt.pdf")

Ein Geheimnis in einer INI aufbewahren #

// At setup : encrypt once, store the string
SetProfileString("app.ini", "db", "password", lnv_crypto.of_encrypt(ls_master, ls_db_password))

// At run time : the master password comes from the user, the INI gives the rest
ls_db_password = lnv_crypto.of_decrypt(ls_master, ProfileString("app.ini", "db", "password", ""))
if ls_db_password = "" then MessageBox("Login", lnv_crypto.is_last_error)

Eine Bestellung signieren, anderswo prüfen #

string ls_public, ls_private, ls_signature
lnv_crypto.of_generate_keypair(n_pbt_crypto.KEY_2048, ls_public, ls_private)   // once ; keep ls_private
ls_signature = lnv_crypto.of_sign(ls_private, ls_order_json)
// The public key and the signature travel with the order ; anyone can check :
if not lnv_crypto.of_verify(ls_public, ls_order_json, ls_signature) then MessageBox("Order", "This order was altered.")

Ein Token für eine API und seine Prüfung #

// The client : a token valid one hour, in the Authorization header
ls_token = lnv_crypto.of_jwt_sign(n_pbt_crypto.JWT_HS256, ls_api_secret, '{"sub":"guillaume","role":"admin"}', 3600)
lnv_rest.of_set_bearer(ls_token)

// The server side (or a check of what came back) : the claims, once the signature and the expiry are right
ls_claims = lnv_crypto.of_jwt_verify(n_pbt_crypto.JWT_HS256, ls_api_secret, ls_token)
if ls_claims = "" then MessageBox("API", lnv_crypto.is_last_error)
ls_role = gnv_utils.of_json_get_str(ls_claims, "role")

Ein von Windows verwahrtes Serverpasswort und ein Zwei-Faktor-Benutzer #

// At setup : the INI holds a value Windows protects for this account, never the password
SetProfileString("app.ini", "db", "password", lnv_crypto.of_protect(ls_db_password))
// At run time
ls_db_password = lnv_crypto.of_unprotect(ProfileString("app.ini", "db", "password", ""))

// Enrolling a user : a secret in the database, the QR on screen
ls_secret = lnv_crypto.of_totp_secret()
uo_qr.is_data = lnv_crypto.of_totp_uri(ls_secret, ls_login, "MyApp")
// Logging in : the stored hash, then the six digits
if lnv_crypto.of_password_verify(ls_typed, ls_stored_hash) and lnv_crypto.of_totp_verify(ls_secret, ls_six_digits) then ...

Bewährte Praxis #

• Ein Objekt pro Fenster, mit ihm geöffnet (of_open): die verborgene Seite kostet beim ersten Mal einige hundert Millisekunden, danach nichts.
• Das Passwort wird nicht gespeichert: of_encrypt liefert alles zum Entschlüsseln — außer ihm; das ist der Vertrag.
• Der private Schlüssel reist nicht: zu Hause signieren, den öffentlichen Schlüssel veröffentlichen. of_verify braucht nur diesen.
• is_last_error lesen, wenn eine Methode eine leere Zeichenkette liefert: der Grund steht dort, und oft heißt er „falsches Passwort“ oder „unlesbare Datei“ — kein Fehler der Komponente.

← Komponentenreferenz · Inhalt des Handbuchs