1# Constant-Time Encoding
2
3[![Build Status](https://github.com/paragonie/constant_time_encoding/actions/workflows/ci.yml/badge.svg)](https://github.com/paragonie/constant_time_encoding/actions)
4[![Latest Stable Version](https://poser.pugx.org/paragonie/constant_time_encoding/v/stable)](https://packagist.org/packages/paragonie/constant_time_encoding)
5[![Latest Unstable Version](https://poser.pugx.org/paragonie/constant_time_encoding/v/unstable)](https://packagist.org/packages/paragonie/constant_time_encoding)
6[![License](https://poser.pugx.org/paragonie/constant_time_encoding/license)](https://packagist.org/packages/paragonie/constant_time_encoding)
7[![Downloads](https://img.shields.io/packagist/dt/paragonie/constant_time_encoding.svg)](https://packagist.org/packages/paragonie/constant_time_encoding)
8
9Based on the [constant-time base64 implementation made by Steve "Sc00bz" Thomas](https://github.com/Sc00bz/ConstTimeEncoding),
10this library aims to offer character encoding functions that do not leak
11information about what you are encoding/decoding via processor cache
12misses. Further reading on [cache-timing attacks](http://blog.ircmaxell.com/2014/11/its-all-about-time.html).
13
14Our fork offers the following enhancements:
15
16* `mbstring.func_overload` resistance
17* Unit tests
18* Composer- and Packagist-ready
19* Base16 encoding
20* Base32 encoding
21* Uses `pack()` and `unpack()` instead of `chr()` and `ord()`
22
23## PHP Version Requirements
24
25Version 2 of this library should work on **PHP 7** or newer. For PHP 5
26support, see [the v1.x branch](https://github.com/paragonie/constant_time_encoding/tree/v1.x).
27
28If you are adding this as a dependency to a project intended to work on both PHP 5 and PHP 7, please set the required version to `^1|^2` instead of just `^1` or `^2`.
29
30## How to Install
31
32```sh
33composer require paragonie/constant_time_encoding
34```
35
36## How to Use
37
38```php
39use ParagonIE\ConstantTime\Encoding;
40
41// possibly (if applicable):
42// require 'vendor/autoload.php';
43
44$data = random_bytes(32);
45echo Encoding::base64Encode($data), "\n";
46echo Encoding::base32EncodeUpper($data), "\n";
47echo Encoding::base32Encode($data), "\n";
48echo Encoding::hexEncode($data), "\n";
49echo Encoding::hexEncodeUpper($data), "\n";
50```
51
52Example output:
53
54```
551VilPkeVqirlPifk5scbzcTTbMT2clp+Zkyv9VFFasE=
562VMKKPSHSWVCVZJ6E7SONRY3ZXCNG3GE6ZZFU7TGJSX7KUKFNLAQ====
572vmkkpshswvcvzj6e7sonry3zxcng3ge6zzfu7tgjsx7kukfnlaq====
58d558a53e4795aa2ae53e27e4e6c71bcdc4d36cc4f6725a7e664caff551456ac1
59D558A53E4795AA2AE53E27E4E6C71BDCC4D36CC4F6725A7E664CAFF551456AC1
60```
61
62If you only need a particular variant, you can just reference the
63required class like so:
64
65```php
66use ParagonIE\ConstantTime\Base64;
67use ParagonIE\ConstantTime\Base32;
68
69$data = random_bytes(32);
70echo Base64::encode($data), "\n";
71echo Base32::encode($data), "\n";
72```
73
74Example output:
75
76```
771VilPkeVqirlPifk5scbzcTTbMT2clp+Zkyv9VFFasE=
782vmkkpshswvcvzj6e7sonry3zxcng3ge6zzfu7tgjsx7kukfnlaq====
79```
80
81## Support Contracts
82
83If your company uses this library in their products or services, you may be
84interested in [purchasing a support contract from Paragon Initiative Enterprises](https://paragonie.com/enterprise).
85