Skip to content

Latest commit

 

History

History
83 lines (68 loc) · 2.57 KB

streams.md

File metadata and controls

83 lines (68 loc) · 2.57 KB
Raw

Streams

Crypto registers a stream called crypto.file://. As the name suggests, it has to be used with files only. The prefix is followed by the file path. All options has to be passed using stream context.

Options

Cipher context is created using stream_context_create function which accepts an array of parameters. Options for crypto are under an array with key crypto. That has to contain an array of filters that are applied to the stream when reading or writing. It's done in the same order as the array indexes (first item in the array is applied first, second item is applied after that and so on).

For example a context definition for stream with one cipher filter could look like:

$context_write = stream_context_create(array(
    'crypto' => array(
        'filters' => array(
            array(
                'type' => 'cipher',
                'action' => 'encrypt',
                'algorithm' => 'AES-128-CBC',
                'key' => $key,
                'iv'  => $iv,
            )
        )
    ),
));

The type item in the filter identifies a type. Currently only cipher is allowed but more filter types may be added in the future.

Filter: cipher

The cipher filter can have following options for the filter (all fields that are not optional are required):

  • action => string (encrypt|decrypt) - whether to encrypt or decrypt data
  • algorithm => string - algorithm name
  • mode => string|int - cipher mode (optional - if not set, then it must be part of algorithm name)
  • key_size => string|int - key size for the algorithm (optional - if not set, then it must be part of algorithm name)
  • key => string - key string
  • iv => string - initial vector string (optional for ECB mode and ciphers that does not require IV)
  • tag => string - authentication tag (optional and only for auth modes and action decrypt)
  • aad => string - additional application data (optional only for auth modes)

If a mode is GCM and an action is encrypt, then the resulted tag can be found in stream meta as

X-PHP-Crypto-Auth-Tag: <tag>

If the action for GCM mode is descrypt, then the result can be found as

X-PHP-Crypto-Auth-Result: <result>

where <result> can be either success or failure.

A CCM mode is not supported for stream because data can be updated just once which doesn't make sense for stream operations.

Example

Code examples can be found in stream_cipher_gcm.php for GCM mode and stream_cipher_cbc.php for simple CBC mode.