File: docs/01-Protocol-Versions/README.md

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

Contents

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.

Versions

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.