extlib/ParagonIE/README.md

   1 # Constant-Time Encoding
   2
   3 [![Build Status](https://travis-ci.org/paragonie/constant_time_encoding.svg?branch=v1.x)](https://travis-ci.org/paragonie/constant_time_encoding)
   4
   5 Based on the [constant-time base64 implementation made by Steve "Sc00bz" Thomas](https://github.com/Sc00bz/ConstTimeEncoding),
   6 this library aims to offer character encoding functions that do not leak
   7 information about what you are encoding/decoding via processor cache
   8 misses. Further reading on [cache-timing attacks](http://blog.ircmaxell.com/2014/11/its-all-about-time.html).
   9
  10 Our fork offers the following enchancements:
  11
  12 * `mbstring.func_overload` resistance
  13 * Unit tests
  14 * Composer- and Packagist-ready
  15 * Base16 encoding
  16 * Base32 encoding
  17 * Uses `pack()` and `unpack()` instead of `chr()` and `ord()`
  18
  19 ## PHP Version Requirements
  20
  21 This library should work on any [supported version of PHP](https://secure.php.net/supported-versions.php).
  22 It *may* work on earlier versions, but we **do not** guarantee it. If it
  23 doesn't, we **will not** fix it to work on earlier versions of PHP.
  24
  25 ## How to Install
  26
  27 ```sh
  28 composer require paragonie/constant_time_encoding
  29 ```
  30
  31 ## How to Use
  32
  33 ```php
  34 use \ParagonIE\ConstantTime\Encoding;
  35
  36 // possibly (if applicable):
  37 // require 'vendor/autoload.php';
  38
  39 $data = random_bytes(32);
  40 echo Encoding::base64Encode($data), "\n";
  41 echo Encoding::base32EncodeUpper($data), "\n";
  42 echo Encoding::base32Encode($data), "\n";
  43 echo Encoding::hexEncode($data), "\n";
  44 echo Encoding::hexEncodeUpper($data), "\n";
  45 ```
  46
  47 Example output:
  48
  49 ```
  50 1VilPkeVqirlPifk5scbzcTTbMT2clp+Zkyv9VFFasE=
  51 2VMKKPSHSWVCVZJ6E7SONRY3ZXCNG3GE6ZZFU7TGJSX7KUKFNLAQ====
  52 2vmkkpshswvcvzj6e7sonry3zxcng3ge6zzfu7tgjsx7kukfnlaq====
  53 d558a53e4795aa2ae53e27e4e6c71bcdc4d36cc4f6725a7e664caff551456ac1
  54 D558A53E4795AA2AE53E27E4E6C71BDCC4D36CC4F6725A7E664CAFF551456AC1
  55 ```
  56
  57 If you only need a particular variant, you can just reference the
  58 required class like so:
  59
  60 ```php
  61 use \ParagonIE\ConstantTime\Base64;
  62 use \ParagonIE\ConstantTime\Base32;
  63
  64 $data = random_bytes(32);
  65 echo Base64::encode($data), "\n";
  66 echo Base32::encode($data), "\n";
  67 ```
  68
  69 Example output:
  70
  71 ```
  72 1VilPkeVqirlPifk5scbzcTTbMT2clp+Zkyv9VFFasE=
  73 2vmkkpshswvcvzj6e7sonry3zxcng3ge6zzfu7tgjsx7kukfnlaq====
  74 ```