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 #

// Local variables
n_pbt_crypto lnv_crypto
string ls_hash, ls_cipher

// Create the object once, free it when done
lnv_crypto = create n_pbt_crypto

// The fingerprint of a text, in hexadecimal
ls_hash = lnv_crypto.of_sha256(/*text*/ "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(/*password*/ "s3cret", /*text*/ "The safe code is 4152.")
MessageBox("Back", lnv_crypto.of_decrypt(/*password*/ "s3cret", /*cipher*/ ls_cipher))

// Free the object
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, die in dieser Reihenfolge trägt: PBK2 (4 Bytes), die Anzahl der PBKDF2-Runden (4 Bytes, Big-Endian), das Salz (16), die Nonce (12), das AES-256-GCM-Chiffrat, dann sein Tag (16 Bytes, am Ende). Der Schlüssel wird aus dem Passwort (UTF-8) per PBKDF2-HMAC-SHA-256 mit DIESEN Runden abgeleitet — il_pbkdf2_rounds zum Zeitpunkt der Verschlüsselung. of_decrypt mit demselben Passwort genügt, auf jedem Arbeitsplatz; of_encrypt_file schreibt genau denselben Container, als Bytes.
• of_password_hash: pbkdf2-sha256$Runden$Salz$Hash, Salz und Hash in Standard-Base64. Dieses Format ist PBToolboxAI-EIGEN: weder passlib ($pbkdf2-sha256$…) noch Django (pbkdf2_sha256$…) lesen es unverändert.
• Schlüssel und Signaturen: PEM, öffentlich als SPKI (BEGIN PUBLIC KEY), privat als PKCS#8 (BEGIN PRIVATE KEY); Signaturen in Base64, je nach Familie des Schlüssels — RSA: RSASSA-PKCS1-v1_5 mit SHA-256; ECDSA P-256: SHA-256, in DER (openssl dgst -sha256 -verify, Java SHA256withECDSA); Ed25519: 64 Bytes. of_verify liest eine ECDSA-Signatur in DER oder in P1363 (r | s); das ES256-JWT bleibt in P1363, wie RFC 7518 es verlangt.
• RSA-OAEP (of_rsa_encrypt): SHA-256, MGF1 mit SHA-256, ohne Label. In Java: OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT); mit openssl: -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256. Ein PKCS#1-Schlüssel (BEGIN RSA PRIVATE KEY) wird mit openssl pkcs8 -topk8 -nocrypt umgewandelt.
• MD5 wird NATIV angeboten (HASH_MD5) für alte Austausche, die es verlangen — nie für ein Passwort oder für Integrität gegenüber einem Angreifer.
• JWK (of_jwk_to_pem, of_pem_to_jwk, of_jwt_verify_jwks): das JSON der RFC 7517 — kty RSA, EC (P-256, P-384) oder OKP (Ed25519); ein Schlüsselsatz (JWKS) ist {"keys":[…]}, jeder Schlüssel durch seine kid benannt.
• Blobs: die Methoden of_*_blob arbeiten nativ auf den BYTES — dieselben Werte wie für eine Datei mit diesen Bytes; of_encrypt_blob schreibt den Container von of_encrypt.

Einen Wert von of_encrypt serverseitig in Python entschlüsseln (Bibliothek cryptography):

import base64, struct
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

raw = base64.b64decode(value)
assert raw[:4] == b"PBK2"
rounds = struct.unpack(">I", raw[4:8])[0]
salt, nonce, data = raw[8:24], raw[24:36], raw[36:]   # data = ciphertext + 16-byte tag
key = PBKDF2HMAC(hashes.SHA256(), 32, salt, rounds).derive(password.encode("utf-8"))
text = AESGCM(key).decrypt(nonce, data, None).decode("utf-8")

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_RSA_3072, KEY_RSA_4096, KEY_EC_P256, KEY_EC_P384, KEY_ED25519 für die Art eines Paars; JWT_HS256, JWT_HS384, JWT_HS512, JWT_RS256, JWT_RS384, JWT_RS512, JWT_PS256, JWT_PS384, JWT_PS512, JWT_ES256, JWT_ES384, JWT_EDDSA; SIGN_PKCS1, SIGN_PSS für das Schema einer RSA-Signatur; CHARSET_ALL, CHARSET_ALPHANUM, CHARSET_LETTERS, CHARSET_DIGITS, CHARSET_HEX; KEYFORMAT_TEXT, KEYFORMAT_HEX, KEYFORMAT_BASE64 für die Form eines HMAC-Schlüssels.

Methoden #

Beispiele #

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

// Local variables
string ls_expected, ls_actual

// The fingerprint recorded at deploy time, and the one of the file on this workstation
ls_expected = ProfileString("deploy.ini", "files", "orders.pbd", "")
ls_actual = lnv_crypto.of_hash_file(/*algorithm*/ n_pbt_crypto.HASH_SHA256, /*path*/ "C:\MyApp\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 #

// Local variables
n_pbt_json lnv_j
n_pbt_restclient lnv_rest

// The REST client of the window
lnv_rest = create n_pbt_restclient

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

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

// Free the client
destroy lnv_rest

Ein Geheimnis in einer INI aufbewahren #

// Local variables
string ls_master, ls_db_password

// At setup : encrypt once, store the string
SetProfileString("app.ini", "db", "password", lnv_crypto.of_encrypt(/*password*/ ls_master, /*text*/ 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(/*password*/ ls_master, /*cipher*/ ProfileString("app.ini", "db", "password", ""))
if ls_db_password = "" then MessageBox("Login", lnv_crypto.of_get_last_error())

Eine Bestellung signieren, anderswo prüfen #

// Local variables
string ls_public, ls_private, ls_signature, ls_order_json

// The order to sign, as the application writes it
ls_order_json = '{"order":4152,"amount":690.00}'

// Sign the order with the private key
lnv_crypto.of_generate_keypair(/*bits*/ n_pbt_crypto.KEY_2048, /*public_pem*/ ls_public, /*private_pem*/ ls_private)   // once ; keep ls_private
ls_signature = lnv_crypto.of_sign(/*private_pem*/ ls_private, /*text*/ ls_order_json)

// The public key and the signature travel with the order ; anyone can check :
if not lnv_crypto.of_verify(/*public_pem*/ ls_public, /*text*/ ls_order_json, /*signature*/ ls_signature) then MessageBox("Order", "This order was altered.")

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

// Local variables
string ls_api_secret, ls_token, ls_claims, ls_role
n_pbt_restclient lnv_rest
n_pbt_json lnv_json

// The REST client of the window, and the secret the API shares with you
lnv_rest = create n_pbt_restclient
ls_api_secret = ProfileString("app.ini", "api", "secret", "")

// The client : a token valid one hour, in the Authorization header
ls_token = lnv_crypto.of_jwt_sign(/*algorithm*/ n_pbt_crypto.JWT_HS256, /*key*/ ls_api_secret, /*claims_json*/ '{"sub":"jdoe","role":"admin"}', /*expires_seconds*/ 3600)
lnv_rest.of_set_bearer(/*token*/ 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(/*algorithm*/ n_pbt_crypto.JWT_HS256, /*key*/ ls_api_secret, /*token*/ ls_token)
if ls_claims = "" then MessageBox("API", lnv_crypto.of_get_last_error())

// One claim, read with n_pbt_json
lnv_json.of_load(/*json*/ ls_claims)
ls_role = lnv_json.of_get_string(/*path*/ "role")
destroy lnv_rest

Die Signatur eines Webhooks prüfen #

// Local variables
string ls_header, ls_signature, ls_raw_body, ls_webhook_secret

// ls_raw_body and ls_header : the body and the signature header your web service received ;
// the secret, the one the service shares with you
ls_webhook_secret = ProfileString("app.ini", "webhook", "secret", "")

// The service signs the raw body with the shared secret and sends the HMAC in a header
// (GitHub : "sha256=<hex>", Stripe : hex, Shopify : base64). Compare in CONSTANT time.
ls_signature = ls_header
if Left(ls_signature, 7) = "sha256=" then ls_signature = Mid(ls_signature, 8)
if not lnv_crypto.of_hmac_verify(/*algorithm*/ n_pbt_crypto.HASH_SHA256, /*key*/ ls_webhook_secret, /*text*/ ls_raw_body, /*expected*/ ls_signature) then
	MessageBox("Webhook", "This call was not sent by the service.")
	return
end if

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

// Local variables
string ls_db_password, ls_secret, ls_login, ls_typed, ls_stored_hash, ls_six_digits
long ll_step, ll_last_step

// ls_login, ls_typed and ls_six_digits come from the login window ; ls_secret,
// ls_stored_hash and ll_last_step from the record of the user. At setup : the INI holds a value Windows protects for this account, never the password ;
// the entropy, a secret of the application, keeps other programs of the same user out
SetProfileString("app.ini", "db", "password", lnv_crypto.of_protect(/*text*/ ls_db_password, /*machine*/ false, /*entropy*/ "MyApp-7f3a"))

// At run time : the same entropy
ls_db_password = lnv_crypto.of_unprotect(/*protected*/ ProfileString("app.ini", "db", "password", ""), /*entropy*/ "MyApp-7f3a")

// 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(/*secret*/ ls_secret, /*account*/ ls_login, /*issuer*/ "MyApp")

// Logging in : the stored hash, then the six digits - and never the same code twice (RFC 6238)
if lnv_crypto.of_password_verify(/*password*/ ls_typed, /*stored*/ ls_stored_hash) and lnv_crypto.of_totp_verify(/*secret*/ ls_secret, /*code*/ ls_six_digits, /*step*/ ll_step) then
	if ll_step > ll_last_step then ll_last_step = ll_step   // store it with the user ; accept the login
end if

Ein Token von Azure AD, Google oder Auth0 prüfen (JWKS) #

// Local variables
n_pbt_restclient lnv_rest
string ls_jwks, ls_token, ls_claims

// ls_token : the token the user brought (the Authorization header). The key set of the identity provider : fetched once, kept a few hours
lnv_rest = create n_pbt_restclient
if lnv_rest.of_get(/*url*/ "https://login.microsoftonline.com/common/discovery/v2.0/keys") = 200 then ls_jwks = lnv_rest.of_response_text()
destroy lnv_rest

// The kid of the token picks the key ; the issuer and the audience must be yours
ls_claims = lnv_crypto.of_jwt_verify_jwks(/*algorithm*/ n_pbt_crypto.JWT_RS256, /*jwks_json*/ ls_jwks, /*token*/ ls_token, /*expected_claims_json*/ '{"iss":"https://login.microsoftonline.com/my-tenant-id/v2.0","aud":"api://orders"}')
if ls_claims = "" then MessageBox("Login", lnv_crypto.of_get_last_error())

Ein Foto aus der Datenbank, in Base64 (Blob) #

// Local variables
blob lb_photo
string ls_answer
n_pbt_json lnv_j

// ls_answer : the base64 an API answered. The photo of the employee, read from the database
SELECTBLOB photo INTO :lb_photo FROM employee WHERE emp_id = 4152 USING SQLCA;

// Its bytes in base64 in the JSON body of a call, with its fingerprint
lnv_j.of_set_string(/*path*/ "photo", /*value*/ lnv_crypto.of_base64_encode_blob(/*data*/ lb_photo))
lnv_j.of_set_string(/*path*/ "sha256", /*value*/ lnv_crypto.of_hash_blob(/*algorithm*/ n_pbt_crypto.HASH_SHA256, /*data*/ lb_photo))

// The other way : the bytes an API answered, back into the database
if lnv_crypto.of_base64_decode_blob(/*base64*/ ls_answer, /*data*/ lb_photo) = 0 then
	UPDATEBLOB employee SET photo = :lb_photo WHERE emp_id = 4152 USING SQLCA;
end if

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.
• of_get_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.
• DPAPI schützt vor einem ANDEREN KONTO, nicht vor einem anderen Programm: alles, was derselbe Benutzer startet, liest ein of_protect zurück (jedes Konto des Arbeitsplatzes mit ab_machine). Übergeben Sie eine anwendungseigene Entropie, um diesen Kreis zu verkleinern.
• Ein JWT wird mit SEINEM Algorithmus geprüft, fest im Code (n_pbt_crypto.JWT_RS256), nie aus dem Token oder einer INI gelesen, der er fehlen kann: ein leerer Algorithmus wird abgelehnt, aber erst diese Wahl schließt die Tür zur HS/RS-Verwechslung. Nennen Sie dann den erwarteten Aussteller und die Zielgruppe (as_expected_claims_json): die Prüfung lehnt ab, wenn sie fehlen.

← Komponentenreferenz · Inhalt des Handbuchs