crypto — n_pbt_crypto #

← Référence des composants · Sommaire du guide

Empreintes, HMAC, chiffrement par mot de passe, valeurs aléatoires et signatures RSA — la Web Crypto API du moteur WebView2, que votre PowerBuilder 10 n'a nulle part ailleurs. Aucune DLL tierce, aucun service : ce que le poste sait déjà faire, offert à PowerScript.

▶ Le voir en vrai — Application de démonstration, tuile Crypto : les résultats, le code qui les produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// 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

Chaque méthode est un appel qui rend sa valeur : pas d'événement, pas d'attente à écrire.

Les formats, lisibles par les autres outils #

• Empreintes et HMAC : hexadécimal minuscule, le texte lu en UTF-8 — Python, Java et openssl dgst donnent la même valeur.
• of_encrypt : une seule chaîne base64 qui porte, dans l'ordre, PBK2 (4 octets), le nombre de tours PBKDF2 (4 octets, gros-boutiste), le sel (16), le nonce (12), le chiffré AES-256-GCM, puis son tag (16 octets, à la fin). La clé est dérivée du mot de passe (UTF-8) par PBKDF2-HMAC-SHA-256 avec CES tours — il_pbkdf2_rounds au moment du chiffrement. of_decrypt avec le même mot de passe suffit, sur n'importe quel poste ; of_encrypt_file écrit exactement le même conteneur, en octets.
• of_password_hash : pbkdf2-sha256$tours$sel$empreinte, sel et empreinte en base64 standard. Ce format est PROPRE à PBToolboxAI : ni passlib ($pbkdf2-sha256$…) ni Django (pbkdf2_sha256$…) ne le lisent tel quel.
• Clés et signatures : PEM, publique en SPKI (BEGIN PUBLIC KEY), privée en PKCS#8 (BEGIN PRIVATE KEY) ; signatures en base64, selon la famille de la clé — RSA : RSASSA-PKCS1-v1_5 avec SHA-256 ; ECDSA P-256 : SHA-256, en DER (openssl dgst -sha256 -verify, Java SHA256withECDSA) ; Ed25519 : 64 octets. of_verify lit une signature ECDSA en DER ou en P1363 (r | s) ; le JWT ES256 reste en P1363, comme la RFC 7518 l'exige.
• RSA-OAEP (of_rsa_encrypt) : SHA-256, MGF1 en SHA-256, sans label. En Java : OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSource.PSpecified.DEFAULT) ; avec openssl : -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256. Une clé PKCS#1 (BEGIN RSA PRIVATE KEY) se convertit par openssl pkcs8 -topk8 -nocrypt.
• MD5 est offert en NATIF (HASH_MD5) pour les échanges anciens qui l'exigent — jamais pour un mot de passe ni pour une intégrité face à un adversaire.

Déchiffrer une valeur d'of_encrypt côté serveur, en Python (bibliothèque 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")

Propriétés #

Constantes : HASH_MD5, HASH_SHA1, HASH_SHA256, HASH_SHA384, HASH_SHA512 pour l'algorithme ; KEY_2048, KEY_3072, KEY_4096 pour la taille d'une clé RSA, KEY_RSA_2048, KEY_EC_P256, KEY_ED25519 pour la sorte d'une paire ; JWT_HS256, JWT_RS256, JWT_ES256, JWT_EDDSA ; CHARSET_ALL, CHARSET_ALPHANUM, CHARSET_LETTERS, CHARSET_DIGITS, CHARSET_HEX ; KEYFORMAT_TEXT, KEYFORMAT_HEX, KEYFORMAT_BASE64 pour la forme d'une clé HMAC.

Méthodes #

Exemples #

Vérifier qu'un fichier n'a pas changé #

// 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.")

Une pièce jointe en base64 pour une API #

// 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")

Garder un secret dans un INI #

// 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.is_last_error)

Signer une commande, la vérifier ailleurs #

// Local variables
string ls_public, ls_private, ls_signature

// 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.")

Un jeton pour une API, et sa vérification #

// 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.is_last_error)
ls_role = gnv_utils.of_json_get_str(/*json*/ ls_claims, /*key*/ "role")

Vérifier la signature d'un webhook #

// 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

Un mot de passe de serveur rangé par Windows, et un utilisateur à deux facteurs #

// 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

Bonnes pratiques #

• Un seul objet par fenêtre, ouvert avec elle (of_open) : la page cachée coûte quelques centaines de millisecondes la première fois, rien ensuite.
• Le mot de passe ne se stocke pas : of_encrypt rend tout ce qu'il faut pour déchiffrer, sauf lui — c'est le contrat.
• La clé privée ne voyage pas : signez chez vous, publiez la clé publique. of_verify ne demande que celle-là.
• Lisez is_last_error quand une méthode rend une chaîne vide : la raison y est, et elle dit souvent « mauvais mot de passe » ou « fichier illisible » — pas un défaut du composant.
• DPAPI protège d'un AUTRE COMPTE, pas d'un autre programme : tout ce que lance le même utilisateur relit un of_protect (tout compte du poste avec ab_machine). Passez une entropie propre à l'application pour réduire ce cercle.
• Un JWT se vérifie avec SON algorithme, écrit en dur (n_pbt_crypto.JWT_RS256), jamais lu dans le jeton ni dans un INI qui peut manquer : un algorithme vide est refusé, mais c'est ce choix qui ferme la porte à la confusion HS/RS. Vérifiez ensuite aud et iss sur les claims rendues.

← Référence des composants · Sommaire du guide