Pure-PHP PKCS#1 compliant implementation of RSA.

author | Jim Wigginton
version | 0.1.0
access | public
package | Crypt_RSA

### Methods

## The constructor

    Crypt_RSA() : \Crypt_RSA

If you want to make use of the openssl extension, you'll need to set the mode manually, yourself. The reason Crypt_RSA doesn't do it is because OpenSSL doesn't fail gracefully. openssl_pkey_new(), in particular, requires openssl.cnf be present somewhere and, unfortunately, the only real way to find out is too late.

access | public

### Returns

`\Crypt_RSA`

## Performs RSA Blinding

    _blind(\Math_BigInteger $x, \Math_BigInteger $r, Integer $i) : \Math_BigInteger

Protects against timing attacks by employing RSA Blinding. Returns $x->modPow($this->exponents[$i], $this->primes[$i])

access | private

### Parameters

#### $x

`\Math_BigInteger`

#### $r

`\Math_BigInteger`

#### $i

`Integer`

### Returns

`\Math_BigInteger`

## Convert a private key to the appropriate format.

    _convertPrivateKey($n, $e, $d, $primes, $exponents, $coefficients) : String

access | private
see | \global\setPrivateKeyFormat()

### Parameters

#### $n

#### $e

#### $d

#### $primes

#### $exponents

#### $coefficients

### Returns

`String`

## Convert a public key to the appropriate format

    _convertPublicKey($n, $e) : String

access | private
see | \global\setPublicKeyFormat()

### Parameters

#### $n

#### $e

### Returns

`String`

## Data Handler

    _data_handler(Resource $parser, String $data)

Called by xml_set_character_data_handler()

access | private

### Parameters

#### $parser

`Resource`

#### $data

`String`

## _decodeLength()

    _decodeLength($string)

### Parameters

#### $string

## EMSA-PKCS1-V1_5-ENCODE

    _emsa_pkcs1_v1_5_encode(String $m, Integer $emLen) : String

See RFC3447#section-9.2.

access | private

### Parameters

#### $m

`String`

#### $emLen

`Integer`

### Returns

`String`

## EMSA-PSS-ENCODE

    _emsa_pss_encode(String $m, Integer $emBits)

See RFC3447#section-9.1.1.

access | private

### Parameters

#### $m

`String`

#### $emBits

`Integer`

## EMSA-PSS-VERIFY

    _emsa_pss_verify(String $m, String $em, Integer $emBits) : String

See RFC3447#section-9.1.2.

access | private

### Parameters

#### $m

`String`

#### $em

`String`

#### $emBits

`Integer`

### Returns

`String`

## _encodeLength()

    _encodeLength($length)

### Parameters

#### $length

## Exponentiate with or without Chinese Remainder Theorem

    _exponentiate(\Math_BigInteger $x) : \Math_BigInteger

See RFC3447#section-5.1.2.

access | private

### Parameters

#### $x

`\Math_BigInteger`

### Returns

`\Math_BigInteger`

## Generates the smallest and largest numbers requiring $bits bits

    _generateMinMax(Integer $bits) : Array

access | private

### Parameters

#### $bits

`Integer`

### Returns

`Array`

## Integer-to-Octet-String primitive

    _i2osp(\Math_BigInteger $x, Integer $xLen) : String

See RFC3447#section-4.1.

access | private

### Parameters

#### $x

`\Math_BigInteger`

#### $xLen

`Integer`

### Returns

`String`

## MGF1

    _mgf1(String $mgfSeed, $maskLen) : String

See RFC3447#appendix-B.2.1.

access | private

### Parameters

#### $mgfSeed

`String`

#### $maskLen

### Returns

`String`

## Octet-String-to-Integer primitive

    _os2ip(String $x) : \Math_BigInteger

See RFC3447#section-4.2.

access | private

### Parameters

#### $x

`String`

### Returns

`\Math_BigInteger`

## Break a public or private key down into its constituant components

    _parseKey(String $key, Integer $type) : Array

access | private
see | \global\_convertPublicKey()
see | \global\_convertPrivateKey()

### Parameters

#### $key

`String`

#### $type

`Integer`

### Returns

`Array`

## Generates a random string x bytes long

    _random(Integer $bytes, \optional $nonzero) : String

access | public

### Parameters

#### $bytes

`Integer`

#### $nonzero

`\optional`

Integer $nonzero

### Returns

`String`

## RSADP

    _rsadp(\Math_BigInteger $c) : \Math_BigInteger

See RFC3447#section-5.1.2.

access | private

### Parameters

#### $c

`\Math_BigInteger`

### Returns

`\Math_BigInteger`

## RSAEP

    _rsaep(\Math_BigInteger $m) : \Math_BigInteger

See RFC3447#section-5.1.1.

access | private

### Parameters

#### $m

`\Math_BigInteger`

### Returns

`\Math_BigInteger`

## RSAES-OAEP-DECRYPT

    _rsaes_oaep_decrypt(String $c, String $l) : String

See RFC3447#section-7.1.2. The fact that the error messages aren't distinguishable from one another hinders debugging, but, to quote from RFC3447#section-7.1.2:

Note. Care must be taken to ensure that an opponent cannot distinguish the different error conditions in Step 3.g, whether by error message or timing, or, more generally, learn partial information about the encoded message EM. Otherwise an opponent may be able to obtain useful information about the decryption of the ciphertext C, leading to a chosen-ciphertext attack such as the one observed by Manger [36].

As for $l... to quote from RFC3447#page-17:

Both the encryption and the decryption operations of RSAES-OAEP take the value of a label L as input. In this version of PKCS #1, L is the empty string; other uses of the label are outside the scope of this document.

access | private

### Parameters

#### $c

`String`

#### $l

`String`

### Returns

`String`

## RSAES-OAEP-ENCRYPT

    _rsaes_oaep_encrypt(String $m, String $l) : String

See RFC3447#section-7.1.1 and {http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding OAES}.

access | private

### Parameters

#### $m

`String`

#### $l

`String`

### Returns

`String`

## RSAES-PKCS1-V1_5-DECRYPT

    _rsaes_pkcs1_v1_5_decrypt(String $c) : String

See RFC3447#section-7.2.2.

For compatability purposes, this function departs slightly from the description given in RFC3447. The reason being that RFC2313#section-8.1 (PKCS#1 v1.5) states that ciphertext's encrypted by the private key should have the second byte set to either 0 or 1 and that ciphertext's encrypted by the public key should have the second byte set to 2. In RFC3447 (PKCS#1 v2.1), the second byte is supposed to be 2 regardless of which key is used. for compatability purposes, we'll just check to make sure the second byte is 2 or less. If it is, we'll accept the decrypted string as valid.

As a consequence of this, a private key encrypted ciphertext produced with Crypt_RSA may not decrypt with a strictly PKCS#1 v1.5 compliant RSA implementation. Public key encrypted ciphertext's should but not private key encrypted ciphertext's.

access | private

### Parameters

#### $c

`String`

### Returns

`String`

## RSAES-PKCS1-V1_5-ENCRYPT

    _rsaes_pkcs1_v1_5_encrypt(String $m) : String

See RFC3447#section-7.2.1.

access | private

### Parameters

#### $m

`String`

### Returns

`String`

## RSASP1

    _rsasp1(\Math_BigInteger $m) : \Math_BigInteger

See RFC3447#section-5.2.1.

access | private

### Parameters

#### $m

`\Math_BigInteger`

### Returns

`\Math_BigInteger`

## RSASSA-PKCS1-V1_5-SIGN

    _rsassa_pkcs1_v1_5_sign(String $m) : String

See RFC3447#section-8.2.1.

access | private

### Parameters

#### $m

`String`

### Returns

`String`

## RSASSA-PKCS1-V1_5-VERIFY

    _rsassa_pkcs1_v1_5_verify(String $m, $s) : String

See RFC3447#section-8.2.2.

access | private

### Parameters

#### $m

`String`

#### $s

### Returns

`String`

## RSASSA-PSS-SIGN

    _rsassa_pss_sign(String $m) : String

See RFC3447#section-8.1.1.

access | private

### Parameters

#### $m

`String`

### Returns

`String`

## RSASSA-PSS-VERIFY

    _rsassa_pss_verify(String $m, String $s) : String

See RFC3447#section-8.1.2.

access | private

### Parameters

#### $m

`String`

#### $s

`String`

### Returns

`String`

## RSAVP1

    _rsavp1(\Math_BigInteger $s) : \Math_BigInteger

See RFC3447#section-5.2.2.

access | private

### Parameters

#### $s

`\Math_BigInteger`

### Returns

`\Math_BigInteger`

## Start Element Handler

    _start_element_handler(Resource $parser, String $name, Array $attribs)

Called by xml_set_element_handler()

access | private

### Parameters

#### $parser

`Resource`

#### $name

`String`

#### $attribs

`Array`

## Stop Element Handler

    _stop_element_handler(Resource $parser, String $name)

Called by xml_set_element_handler()

access | private

### Parameters

#### $parser

`Resource`

#### $name

`String`

## String Shift

    _string_shift(String $string, \optional $index) : String

Inspired by array_shift

access | private

### Parameters

#### $string

`String`

#### $index

`\optional`

Integer $index

### Returns

`String`

## Create public / private key pair

    createKey(\optional $bits, \optional $timeout, \optional $partial)

Returns an array with the following three elements: - 'privatekey': The private key. - 'publickey': The public key. - 'partialkey': A partially computed key (if the execution time exceeded $timeout). Will need to be passed back to Crypt_RSA::createKey() as the third parameter for further processing.

access | public

### Parameters

#### $bits

`\optional`

Integer $bits

#### $timeout

`\optional`

Integer $timeout

#### $partial

`\optional`

Math_BigInteger $p

## Decryption

    decrypt($ciphertext) : String

see | \global\encrypt()
access | public

### Parameters

#### $ciphertext

### Returns

`String`

## Encryption

    encrypt(String $plaintext) : String

Both CRYPT_RSA_ENCRYPTION_OAEP and CRYPT_RSA_ENCRYPTION_PKCS1 both place limits on how long $plaintext can be. If $plaintext exceeds those limits it will be broken up so that it does and the resultant ciphertext's will be concatenated together.

see | \global\decrypt()
access | public

### Parameters

#### $plaintext

`String`

### Returns

`String`

## Returns the public key

    getPublicKey(Integer $type)

The public key is only returned under two circumstances - if the private key had the public key embedded within it or if the public key was set via setPublicKey(). If the currently loaded key is supposed to be the public key this function won't return it since this library, for the most part, doesn't distinguish between public and private keys.

see | \global\getPublicKey()
access | public

### Parameters

#### $type

`Integer`

optional

## Loads a public or private key

    loadKey(String $key, Integer $type)

Returns true on success and false on failure (ie. an incorrect password was provided or the key was malformed)

access | public

### Parameters

#### $key

`String`

#### $type

`Integer`

optional

## Set Encryption Mode

    setEncryptionMode(Integer $mode)

Valid values include CRYPT_RSA_ENCRYPTION_OAEP and CRYPT_RSA_ENCRYPTION_PKCS1.

access | public

### Parameters

#### $mode

`Integer`

## Determines which hashing function should be used

    setHash(String $hash)

Used with signature production / verification and (if the encryption mode is CRYPT_RSA_ENCRYPTION_OAEP) encryption and decryption. If $hash isn't supported, sha1 is used.

access | public

### Parameters

#### $hash

`String`

## Determines which hashing function should be used for the mask generation function

    setMGFHash(String $hash)

The mask generation function is used by CRYPT_RSA_ENCRYPTION_OAEP and CRYPT_RSA_SIGNATURE_PSS and although it's best if Hash and MGFHash are set to the same thing this is not a requirement.

access | public

### Parameters

#### $hash

`String`

## Sets the password

    setPassword(String $password)

Private keys can be encrypted with a password. To unset the password, pass in the empty string or false. Or rather, pass in $password such that empty($password) is true.

see | \global\createKey()
see | \global\loadKey()
access | public

### Parameters

#### $password

`String`

## Determines the private key format

    setPrivateKeyFormat(Integer $format)

see | \global\createKey()
access | public

### Parameters

#### $format

`Integer`

## Defines the public key

    setPublicKey(String $key, Integer $type) : Boolean

Some private key formats define the public exponent and some don't. Those that don't define it are problematic when used in certain contexts. For example, in SSH-2, RSA authentication works by sending the public key along with a message signed by the private key to the server. The SSH-2 server looks the public key up in an index of public keys and if it's present then proceeds to verify the signature. Problem is, if your private key doesn't include the public exponent this won't work unless you manually add the public exponent.

Do note that when a new key is loaded the index will be cleared.

Returns true on success, false on failure

see | \global\getPublicKey()
access | public

### Parameters

#### $key

`String`

#### $type

`Integer`

optional

### Returns

`Boolean`

## Determines the public key format

    setPublicKeyFormat(Integer $format)

see | \global\createKey()
access | public

### Parameters

#### $format

`Integer`

## Determines the salt length

    setSaltLength($sLen)

To quote from RFC3447#page-38:

Typical salt lengths in octets are hLen (the length of the output of the hash function Hash) and 0.

access | public

### Parameters

#### $sLen

## Set Signature Mode

    setSignatureMode(Integer $mode)

Valid values include CRYPT_RSA_SIGNATURE_PSS and CRYPT_RSA_SIGNATURE_PKCS1

access | public

### Parameters

#### $mode

`Integer`

## Create a signature

    sign(String $message) : String

see | \global\verify()
access | public

### Parameters

#### $message

`String`

### Returns

`String`

## Verifies a signature

    verify(String $message, String $signature) : Boolean

see | \global\sign()
access | public

### Parameters

#### $message

`String`

#### $signature

`String`

### Returns

`Boolean`

### Properties

## Coefficients for Chinese Remainder Theorem (ie.

    $coefficients : Array

qInv)

access | private

## Components

    $components : Array

For use with parsing XML formatted keys. PHP's XML Parser functions use utilized - instead of PHP's DOM functions - because PHP's XML Parser functions work on PHP4 whereas PHP's DOM functions - although surperior - don't.

see | \global\Crypt_RSA::_start_element_handler()
access | private

## Current String

    $current : Mixed

For use with parsing XML formatted keys.

see | \global\Crypt_RSA::_character_handler()
see | \global\Crypt_RSA::_stop_element_handler()
access | private

## Encryption mode

    $encryptionMode : Integer

access | private

## Exponent (ie.

    $exponent : \Math_BigInteger

e or d)

access | private

## Exponents for Chinese Remainder Theorem (ie.

    $exponents : Array

dP and dQ)

access | private

## Length of hash function output

    $hLen : Integer

access | private

## Hash function

    $hash : \Crypt_Hash

access | private

## Hash name

    $hashName : String

access | private

## Modulus length

    $k : \Math_BigInteger

access | private

## Length of MGF hash function output

    $mgfHLen : Integer

access | private

## Hash function for the Mask Generation Function

    $mgfHash : \Crypt_Hash

access | private

## Modulus (ie.

    $modulus : \Math_BigInteger

n)

access | private

## Precomputed One

    $one : Array

access | private

## Password

    $password : String

access | private

## Primes for Chinese Remainder Theorem (ie.

    $primes : Array

p and q)

access | private

## Private Key Format

    $privateKeyFormat : Integer

access | private

## Public Exponent

    $publicExponent : Mixed

access | private

## Public Key Format

    $publicKeyFormat : Integer

access | public

## Length of salt

    $sLen : Integer

access | private

## Signature mode

    $signatureMode : Integer

access | private

## Precomputed Zero

    $zero : Array

access | private