Documentation

CryptoToken extends AutoService
in package

The "Crypto Token" service supports a token format suitable for storing specific values in the database with encryption. Characteristics:

  • Primarily designed to defend confidentiality in case of data-leaks (SQL injections, lost backups, etc).
  • NOT appropriate for securing data-transmission. Data-transmission requires more protections (eg mandatory TTLs + signatures). If you need that, consider adding a JWT/JWS/JWE implementation.
  • Data-format allows phase-in/phase-out. If you have a datum that was written with an old key or with no key, it will still be readable.

USAGE: The "encrypt()" and "decrypt()" methods are the primary interfaces.

$encrypted = Civi::service('crypto.token')->encrypt('my-mail-password, 'KEY_ID_OR_TAG'); $decrypted = Civi::service('crypto.token')->decrypt($encrypted, '*');

FORMAT: An encoded token may be in either of these formats:

  • Plain text: Any string which does not begin with chr(2)
  • Encrypted text: A string in the format: TOKEN := DLM + FMT + QUERY DLM := ASCII char #2 FMT := String, 4-digit, alphanumeric (as in "CTK?") QUERY := String, URL-encoded key-value pairs, "k", the key ID (alphanumeric and symbols "_-.,:;=+/") "t", the text (base64-encoded ciphertext)
Tags
service

crypto.token

Table of Contents

Constants

FMT_QUERY  = 'CTK?'
Format identification code

Properties

$delim  : string
$registry  : CryptoRegistry|null

Methods

__construct()  : mixed
CryptoToken constructor.
decrypt()  : string
Get the plaintext (given an encrypted token).
encrypt()  : string
Create an encrypted token (given the plaintext).
isPlainText()  : bool
Determine if a string looks like plain-text.
parse()  : array<string|int, mixed>
Parse the content of a token (without decrypting it).
rekey()  : string|null
Re-encrypt an existing token with a newer version of the key.
getRegistry()  : CryptoRegistry

Constants

FMT_QUERY

Format identification code

public mixed FMT_QUERY = 'CTK?'

Properties

Methods

decrypt()

Get the plaintext (given an encrypted token).

public decrypt(string $token[, string|array<string|int, string> $keyIdOrTag = '*' ]) : string
Parameters
$token : string
$keyIdOrTag : string|array<string|int, string> = '*'

Whitelist of acceptable keys. Wildcard '*' will allow it to use any/all available means to decode the token.

Tags
throws
CryptoException
Return values
string

encrypt()

Create an encrypted token (given the plaintext).

public encrypt(string $plainText, string|array<string|int, string> $keyIdOrTag) : string
Parameters
$plainText : string

The secret value to encode (e.g. plain-text password).

$keyIdOrTag : string|array<string|int, string>

List of key IDs or key tags to check. First available match wins.

Tags
throws
CryptoException
Return values
string —

A token

isPlainText()

Determine if a string looks like plain-text.

public isPlainText(string $plainText) : bool
Parameters
$plainText : string
Return values
bool

parse()

Parse the content of a token (without decrypting it).

public parse(string $token) : array<string|int, mixed>
Parameters
$token : string
Tags
throws
CryptoException
Return values
array<string|int, mixed>

rekey()

Re-encrypt an existing token with a newer version of the key.

public rekey(string $oldToken, string $keyTag) : string|null
Parameters
$oldToken : string
$keyTag : string

Ex: 'CRED'

Tags
throws
CryptoException
Return values
string|null —

A re-encrypted version of $oldToken, or NULL if there should be no change.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results