Documentation

EncryptionTest extends TestCase
in package

The base of every unit test that needs more than the class under test.

A test asks for what it needs and gets it without a web server, a database or a config file:

$this->bootFramework(["rootDirectory" => "sub"]);
$request = $this->request($this->input()->withUrl("http://localhost/sub/a/b"));

Everything handed out here is taken back after the test, so no test sees the settings, the request or the cached values of another one.

Table of Contents

ERROR_KEY_LENGTH  = "The setting 'encryption_key' must be at least 32 bytes long."
ERROR_MALFORMED  = "The encrypted value is malformed."
ERROR_NOT_DECRYPTED  = "The value could not be decrypted, the key is wrong or the value was modified."
ERROR_UNKNOWN_FORMAT  = "The value is not in a known encryption format."
HEADER  = "zenc:aes-256-gcm:"
KEY  = "unit-test-encryption-key-0123456789abcdef"
SECRET  = "s3-secret-key/with+special=chars äöü"
$temporaryDirectories  : array<string|int, mixed>
malformedPayloads()  : array<string|int, mixed>
testACipherNameIsCaseSensitive()  : void
testADecryptionExceptionIsARuntimeException()  : void
testAKeyOfExactlyTheMinimumLengthIsAccepted()  : void
testAKeyOneByteBelowTheMinimumLengthIsRejected()  : void
testEncryptsToAUrlSafeValueNamingItsCipherThatDecryptsToThePlaintext()  : void
testRoundTripsAJsonEncodedArray()  : void
testRoundTripsAnEmptyString()  : void
testRoundTripsAValueOfEveryLengthUpToThreeBlocks()  : void
testRoundTripsEveryByteValueIncludingNullBytesAndInvalidUtf8()  : void
testTheGlobalHelpersAndTheClassReadEachOthersValues()  : void
testTheKeyLengthIsCountedInBytes()  : void
testThrowsADecryptionExceptionForAMalformedPayload()  : void
testThrowsADecryptionExceptionForAModifiedIv()  : void
testThrowsADecryptionExceptionForAModifiedTag()  : void
testThrowsADecryptionExceptionForAModifiedValue()  : void
testThrowsADecryptionExceptionForANonCanonicalEncoding()  : void
testThrowsADecryptionExceptionForAnUnknownCipher()  : void
testThrowsADecryptionExceptionForAnUnknownFormat()  : void
testThrowsADecryptionExceptionForAWrongKey()  : void
testThrowsARuntimeExceptionForAMissingKeyOnDecryption()  : void
testThrowsARuntimeExceptionForAMissingKeyOnEncryption()  : void
testThrowsARuntimeExceptionForAnEmptyKey()  : void
testThrowsARuntimeExceptionForAShortKeyOnEncryption()  : void
testUsesAFreshIvForEveryEncryption()  : void
unknownFormats()  : array<string|int, mixed>
assertThrows()  : Throwable
Asserts that the action throws exactly this class, no subclass of it, with exactly this message. expectException() accepts subclasses and a message that only contains the expected one.
bootFramework()  : ZubZet
Provides the framework instance the global helpers (zubzet(), config(), request(), ...) work on. It holds exactly the given settings: nothing is read from a config file, nothing connects, and there is no request, response, database or user until the test sets one.
callHidden()  : mixed
Calls a method that is not public. Only for logic that has no public way in; a test goes through the public method wherever there is one.
currentUser()  : User
Makes a user without database access the current one, the one user() returns. Its constructor would identify it through the database, so it is left out: the user is anonymous unless the test says otherwise.
inDirectory()  : mixed
Runs the action with the given directory as the working directory, for code that reads relative paths. The previous directory is restored afterwards, also when the action throws.
input()  : State
An input without any data. The with...() methods of the state fill it:
removeSetting()  : void
Removes a setting, as if its line was missing in the config file.
request()  : Request
Makes the given input the current request, the one request() returns.
requireArgon2id()  : void
Skips the test on a PHP built without Argon2. The framework hashes with PASSWORD_ARGON2ID unconditionally and composer.json does not require the support, so the tests that reach it have to tolerate its absence.
response()  : Response
Makes a new response the current one, the one response() returns.
setHiddenStatic()  : void
Sets a static property that is not public. Only for state a class keeps for the whole process and offers no way to reset.
setSettings()  : void
Changes single settings of the booted framework and keeps the others.
setUp()  : void
tearDown()  : void
temporaryDirectory()  : string
An empty directory with a trailing slash, removed after the test.
assertDecryptionFails()  : void
assertKeyIsRejected()  : void
clearEndpoint()  : void
clearRuntimeCaches()  : void
decodePayload()  : string
encodePayload()  : string

Constants

ERROR_KEY_LENGTH

private mixed ERROR_KEY_LENGTH = "The setting 'encryption_key' must be at least 32 bytes long."

ERROR_MALFORMED

private mixed ERROR_MALFORMED = "The encrypted value is malformed."

ERROR_NOT_DECRYPTED

private mixed ERROR_NOT_DECRYPTED = "The value could not be decrypted, the key is wrong or the value was modified."

ERROR_UNKNOWN_FORMAT

private mixed ERROR_UNKNOWN_FORMAT = "The value is not in a known encryption format."

KEY

private mixed KEY = "unit-test-encryption-key-0123456789abcdef"

SECRET

private mixed SECRET = "s3-secret-key/with+special=chars äöü"

Properties

$temporaryDirectories

private array<string|int, mixed> $temporaryDirectories = []

Methods

malformedPayloads()

public static malformedPayloads() : array<string|int, mixed>
Return values
array<string|int, mixed> —

testACipherNameIsCaseSensitive()

public testACipherNameIsCaseSensitive() : void
Return values
void —

testADecryptionExceptionIsARuntimeException()

public testADecryptionExceptionIsARuntimeException() : void
Return values
void —

testAKeyOfExactlyTheMinimumLengthIsAccepted()

public testAKeyOfExactlyTheMinimumLengthIsAccepted() : void
Return values
void —

testAKeyOneByteBelowTheMinimumLengthIsRejected()

public testAKeyOneByteBelowTheMinimumLengthIsRejected() : void
Return values
void —

testEncryptsToAUrlSafeValueNamingItsCipherThatDecryptsToThePlaintext()

public testEncryptsToAUrlSafeValueNamingItsCipherThatDecryptsToThePlaintext() : void
Return values
void —

testRoundTripsAJsonEncodedArray()

public testRoundTripsAJsonEncodedArray() : void
Return values
void —

testRoundTripsAnEmptyString()

public testRoundTripsAnEmptyString() : void
Return values
void —

testRoundTripsAValueOfEveryLengthUpToThreeBlocks()

public testRoundTripsAValueOfEveryLengthUpToThreeBlocks() : void
Return values
void —

testRoundTripsEveryByteValueIncludingNullBytesAndInvalidUtf8()

public testRoundTripsEveryByteValueIncludingNullBytesAndInvalidUtf8() : void
Return values
void —

testTheGlobalHelpersAndTheClassReadEachOthersValues()

public testTheGlobalHelpersAndTheClassReadEachOthersValues() : void
Return values
void —

testTheKeyLengthIsCountedInBytes()

public testTheKeyLengthIsCountedInBytes() : void
Return values
void —

testThrowsADecryptionExceptionForAMalformedPayload()

public testThrowsADecryptionExceptionForAMalformedPayload(string $payload) : void
Parameters
$payload : string
Tags
dataProvider

malformedPayloads

Return values
void —

testThrowsADecryptionExceptionForAModifiedIv()

public testThrowsADecryptionExceptionForAModifiedIv() : void
Return values
void —

testThrowsADecryptionExceptionForAModifiedTag()

public testThrowsADecryptionExceptionForAModifiedTag() : void
Return values
void —

testThrowsADecryptionExceptionForAModifiedValue()

public testThrowsADecryptionExceptionForAModifiedValue() : void
Return values
void —

testThrowsADecryptionExceptionForANonCanonicalEncoding()

public testThrowsADecryptionExceptionForANonCanonicalEncoding() : void
Return values
void —

testThrowsADecryptionExceptionForAnUnknownCipher()

public testThrowsADecryptionExceptionForAnUnknownCipher() : void
Return values
void —

testThrowsADecryptionExceptionForAnUnknownFormat()

public testThrowsADecryptionExceptionForAnUnknownFormat(string $value) : void
Parameters
$value : string
Tags
dataProvider

unknownFormats

Return values
void —

testThrowsADecryptionExceptionForAWrongKey()

public testThrowsADecryptionExceptionForAWrongKey() : void
Return values
void —

testThrowsARuntimeExceptionForAMissingKeyOnDecryption()

public testThrowsARuntimeExceptionForAMissingKeyOnDecryption() : void
Return values
void —

testThrowsARuntimeExceptionForAMissingKeyOnEncryption()

public testThrowsARuntimeExceptionForAMissingKeyOnEncryption() : void
Return values
void —

testThrowsARuntimeExceptionForAnEmptyKey()

public testThrowsARuntimeExceptionForAnEmptyKey() : void
Return values
void —

testThrowsARuntimeExceptionForAShortKeyOnEncryption()

public testThrowsARuntimeExceptionForAShortKeyOnEncryption() : void
Return values
void —

testUsesAFreshIvForEveryEncryption()

public testUsesAFreshIvForEveryEncryption() : void
Return values
void —

unknownFormats()

public static unknownFormats() : array<string|int, mixed>
Return values
array<string|int, mixed> —

assertThrows()

Asserts that the action throws exactly this class, no subclass of it, with exactly this message. expectException() accepts subclasses and a message that only contains the expected one.

protected assertThrows(class-string<\Throwable> $class, string $message, callable $action) : Throwable
Parameters
$class : class-string<\Throwable>
$message : string
$action : callable
Return values
Throwable —

bootFramework()

Provides the framework instance the global helpers (zubzet(), config(), request(), ...) work on. It holds exactly the given settings: nothing is read from a config file, nothing connects, and there is no request, response, database or user until the test sets one.

protected bootFramework([array<string, mixed> $settings = [] ]) : ZubZet
Parameters
$settings : array<string, mixed> = []

What config() returns

Return values
ZubZet —

callHidden()

Calls a method that is not public. Only for logic that has no public way in; a test goes through the public method wherever there is one.

protected callHidden(object|class-string $target, string $method, mixed ...$arguments) : mixed
Parameters
$target : object|class-string

An object, or a class name for a static method

$method : string
$arguments : mixed
Return values
mixed —

currentUser()

Makes a user without database access the current one, the one user() returns. Its constructor would identify it through the database, so it is left out: the user is anonymous unless the test says otherwise.

protected currentUser([bool $loggedIn = false ]) : User
Parameters
$loggedIn : bool = false
Return values
User —

inDirectory()

Runs the action with the given directory as the working directory, for code that reads relative paths. The previous directory is restored afterwards, also when the action throws.

protected inDirectory(string $directory, callable $action) : mixed
Parameters
$directory : string
$action : callable
Return values
mixed —

input()

An input without any data. The with...() methods of the state fill it:

protected input([string $requestOrder = "GPC" ]) : State

$this->input()->withMethod("POST")->withPost(["name" => "value"])

REQUEST is put together from GET, POST and COOKIE in the given order, whatever the php.ini of the machine says, so a test sees the same REQUEST everywhere.

Parameters
$requestOrder : string = "GPC"
Return values
State —

removeSetting()

Removes a setting, as if its line was missing in the config file.

protected removeSetting(string $key) : void
Parameters
$key : string
Return values
void —

request()

Makes the given input the current request, the one request() returns.

protected request([State|null $input = null ]) : Request

Boots the framework without settings when the test has not done so.

Parameters
$input : State|null = null
Return values
Request —

requireArgon2id()

Skips the test on a PHP built without Argon2. The framework hashes with PASSWORD_ARGON2ID unconditionally and composer.json does not require the support, so the tests that reach it have to tolerate its absence.

protected requireArgon2id() : void
Return values
void —

response()

Makes a new response the current one, the one response() returns.

protected response() : Response

Boots the framework without settings when the test has not done so.

Return values
Response —

setHiddenStatic()

Sets a static property that is not public. Only for state a class keeps for the whole process and offers no way to reset.

protected setHiddenStatic(class-string $class, string $property, mixed $value) : void
Parameters
$class : class-string
$property : string
$value : mixed
Return values
void —

setSettings()

Changes single settings of the booted framework and keeps the others.

protected setSettings(array<string, mixed> $settings) : void
Parameters
$settings : array<string, mixed>
Return values
void —

tearDown()

protected tearDown() : void
Return values
void —

temporaryDirectory()

An empty directory with a trailing slash, removed after the test.

protected temporaryDirectory() : string
Return values
string —

assertDecryptionFails()

private assertDecryptionFails(string $message, callable $action) : void
Parameters
$message : string
$action : callable
Return values
void —

assertKeyIsRejected()

private assertKeyIsRejected(callable $action) : void
Parameters
$action : callable
Return values
void —

clearEndpoint()

private clearEndpoint() : void
Return values
void —

clearRuntimeCaches()

private clearRuntimeCaches() : void
Return values
void —

decodePayload()

private decodePayload(string $encrypted) : string
Parameters
$encrypted : string
Return values
string —

encodePayload()

private encodePayload(string $payload) : string
Parameters
$payload : string
Return values
string —

Search results