Crypto API

README.md

The $options parameter is not defined here. We should be very conservative with which options we permit users to muck with.

The constructor for each should look like:

public function __construct($driver) {
    switch ($driver) {
        case self::DRIVER_OPENSSL:
            // use openssl for underlying crypto
            break;
        case self::DRIVER_LIBSODIUM:
            // if ext/libsodium, use it for underlying crypto
            // else throw catchable fatal error
            break;
        default:
            // throw catchable fatal error
    }
}

Asymmetric.php

<?php
namespace Cryptography;

class Asymmetric
{
    // Let's not let users hang themselves; if we need more padding options let's add them later
    const PAD_DEFAULT = 0;
    
    const DRIVER_OPENSSL = 'openssl';
    const DRIVER_SODIUM = 'libsodium';
    
    /**
     * Diffie-Hellman, ECDHE, etc.
     * 
     * Get a shared secret from a private key you possess and a public key for
     * the intended message recipient
     * 
     * @param string $privatekey
     * @param string $publickey
     * 
     * @return string
     */
    public function getSharedSecret($privatekey, $publickey) { }
    
    /**
     * Encrypt a string using asymmetric cryptography
     * Seal then sign
     * 
     * @param string|resource $source Plaintext (or resource pointing to, e.g., a file)
     * @param string $ourPrivateKey Our private key
     * @param string $theirPublicKey Their public key
     * @param array $options
     * 
     * @return string
     */
    public function encrypt($source, $ourPrivateKey, $theirPublicKey, $options = []) { }
    
    /**
     * Decrypt a string using asymmetric cryptography
     * Verify then unseal
     * 
     * @param string|resource $source Ciphertext (or resource pointing to, e.g., a file)
     * @param string $ourPrivateKey Our private key
     * @param string $theirPublicKey Their public key
     * @param array $options
     * 
     * @return string
     */
    public function decrypt($source, $ourPrivateKey, $theirPublicKey, $options = []) { }
    
    /**
     * Encrypt a message with a target users' public key
     * 
     * @param string|resource $string Message to encrypt (string or resource for a file)
     * @param string $publicKey
     * @param array $options
     * 
     * @return string
     */
    public function seal($source, $publicKey, $options = []) { }
    
    /**
     * Decrypt a sealed message with our private key
     * 
     * @param string $string|resource Encrypted message (string or resource for a file)
     * @param string $privateKey
     * @param array $options
     * 
     * @return string
     */
    public function unseal($source, $privateKey, $options = []) { }
    
    /**
     * Sign a message with our private key
     * 
     * @param string|resource $message Message to sign (string or resource for a file)
     * @param string $privatekey
     * @param array $options
     * 
     * @return string Signature (detached)
     */
    public function sign($message, $privatekey, $options = []) { }
    
    /**
     * Verify a signed message with the correct public key
     * 
     * @param string|resource $message Message to sign (string or resource for a file)
     * @param string $publickey
     * @param string $signature
     * @param array $options
     * 
     * @return boolean
     */
    public function verify($message, $publickey, $signature, $options = []) { }
}

Symmetric.php

<?php
namespace Cryptography;

class Symmetric
{
    const PAD_ZEROFILL = -1;
    const PAD_NONE = 0; # for CTR, GCM, etc. modes; default
    const PAD_PKCS7 = 1;
    
    const DRIVER_OPENSSL = 'openssl';
    const DRIVER_SODIUM = 'libsodium';
    
    /**
     * Encrypt then authenticate a string or resource
     * 
     * @param string|resource $message Plaintext (or resource pointing to, e.g., a file)
     * @param string $masterKey
     * @param int $mode
     * @param array $options
     * 
     * @return string
     */
    public function encrypt($source, $masterKey, $mode = self::PAD_NONE, $options = []) { }
    
    /**
     * Verify then decrypt a string all at once
     * 
     * @param string|resource $source Ciphertext (or resource pointing to, e.g., a file)
     * @param string $masterKey
     * @param int $mode
     * @param array $options
     * 
     * @return string
     */
    public function decrypt($source, $masterKey, $mode = self::PAD_NONE, $options = []) { }
    
    /**
     * AEAD encryption
     * 
     * @param string $source Plaintext or file/socket resource
     * @param string $masterKey
     * @param string $additional_data Associated Data
     * @param int $mode
     * @param array $options
     * 
     * @return array: [$ciphertext, $additional_data]
     */
    public function aeadEncrypt($source, $masterKey, $additional_data = '', $mode = self::PAD_NONE, $options = []) { }
    
    /**
     * AEAD decryption
     * 
     * @param string|resource $source Ciphertext or file/socket resource
     * @param string $masterKey
     * @param string $additional_data Associated Data
     * @param int $mode
     * @param array $options
     * 
     * @return string
     */
    public function aeadDecrypt($source, $ciphertext, $additional_data = '', $mode = self::PAD_NONE, $options = []) { }
    
}

Someone with more RSA padding oracle experience should probably decide our default padding strategies. Though cperciva provides some useful suggestions.