File: docs/01-Protocol-Versions/

Recommend this page to a friend!
  Classes of Scott Arciszewski  >  PHP PASeTo  >  docs/01-Protocol-Versions/  >  Download  
File: docs/01-Protocol-Versions/
Role: Documentation
Content type: text/markdown
Description: Documentation
Class: PHP PASeTo
Encrypt and decrypt data with PaSeTO protocol
Author: By
Last change:
Date: 5 months ago
Size: 4,477 bytes


Class file image Download

Protocol Versions

This document describes the cryptography and encoding rules for Paseto protocol versions, to assist in cross-platform library development.

Rules for Current and Future Protocol Versions

  1. Everything must be authenticated. Attackers should never be allowed the opportunity to alter messages freely. * If encryption is specified, unauthenticated modes (e.g. AES-CBC) are forbidden. * The nonce or initialization vector must be covered by the authentication tag, not just the ciphertext. * Some degree of nonce-misuse resistance should be provided by any future schemes.
  2. Non-deterministic, stateful, and otherwise dangerous signature schemes (e.g. ECDSA without RFC 6979, XMSS) are forbidden.
  3. Public-key cryptography must be IND-CCA2 secure to be considered for inclusion. * This means no RSA with PKCS1v1.5 padding, textbook RSA, etc.
  4. By default, libraries should only allow the two most recent versions to be used. * If there are only two versions, that means v1 and v2. * If a future post-quantum v3 is defined, v1 should no longer be accepted. * If an additional version v4 is defined, v2 should also no longer be accepted.
  5. New versions will be decided and formalized by the PASETO developers. * User-defined homemade protocols are discouraged. If implementors wish to break this rule and define their own custom protocol suite, they must NOT continue the {v1, v2, ... } series naming convention. * Any version identifiers that match the regular expression, /^v[0-9\.]+$/ are reserved by the PASETO development team.


Version 1: Compatibility Mode

See the version 1 specification for details. At a glance:

  • v1.local: Symmetric Authenticated Encryption: * AES-256-CTR + HMAC-SHA384 (Encrypt-then-MAC) * Key-splitting: HKDF-SHA384 * Info for encryption key: paseto-encryption-key * Info for authentication key: paseto-auth-key-for-aead * 32-byte nonce (first half for AES-CTR, latter half for the HKDF salt) * The nonce calculated from HMAC-SHA384(message, random_bytes(32)) truncated to 32 bytes, during encryption only * The HMAC covers the header, nonce, and ciphertext * Reference implementation in Version1.php: * See aeadEncrypt() for encryption * See aeadDncrypt() for decryption
  • v1.public: Asymmetric Authentication (Public-Key Signatures): * 2048-bit RSA keys * RSASSA-PSS with * Hash function: SHA384 as the hash function * Mask generation function: MGF1+SHA384 * Public exponent: 65537 * Reference implementation in Version1.php: * See sign() for signature generation * See verify() for signature verification

Version 1 implements the best possible RSA + AES + SHA2 ciphersuite. We only use OAEP and PSS for RSA encryption and RSA signatures (respectively), never PKCS1v1.5.

Version 1 is recommended only for legacy systems that cannot use modern cryptography.

See also: Common implementation details for all versions.

Version 2: Recommended

See the version 2 specification for details. At a glance:

  • v2.local: Symmetric Encryption: * XChaCha20-Poly1305 (192-bit nonce, 256-bit key, 128-bit authentication tag) * Encrypting: sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() * Decrypting: sodium_crypto_aead_xchacha20poly1305_ietf_decrypt() * The nonce is calculated from sodium_crypto_generichash() of the message, with a BLAKE2b key provided by random_bytes(24) and an output length of 24, during encryption only * Reference implementation in Version2.php: * See aeadEncrypt() for encryption * See aeadDecrypt() for decryption
  • v2.public: Asymmetric Authentication (Public-Key Signatures): * Ed25519 (EdDSA over Curve25519) * Signing: sodium_crypto_sign_detached() * Verifying: sodium_crypto_sign_verify_detached() * Reference implementation in Version2.php: * See sign() for signature generation * See verify() for signature verification

See also: Common implementation details for all versions.

For more information send a message to info at phpclasses dot org.