Documentation

RSA
in package

RSA

Pure-PHP PKCS#1 compliant implementation of RSA.

ASN1_BITSTRING

ASN1 Bit String


    public
    mixed
    ASN1_BITSTRING
    = 3

ASN1_INTEGER

ASN1 Integer


    public
    mixed
    ASN1_INTEGER
    = 2

ASN1_OBJECT

ASN1 Object Identifier


    public
    mixed
    ASN1_OBJECT
    = 6

ASN1_OCTETSTRING

ASN1 Octet String


    public
    mixed
    ASN1_OCTETSTRING
    = 4

ASN1_SEQUENCE

ASN1 Sequence (with the constucted bit set)


    public
    mixed
    ASN1_SEQUENCE
    = 48

ENCRYPTION_NONE

Do not use any padding


    public
    mixed
    ENCRYPTION_NONE
    = 3

Although this method is not recommended it can none-the-less sometimes be useful if you're trying to decrypt some legacy stuff, if you're trying to diagnose why an encrypted message isn't decrypting, etc.

ENCRYPTION_OAEP

Use {@link http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding Optimal Asymmetric Encryption Padding} (OAEP) for encryption / decryption.


    public
    mixed
    ENCRYPTION_OAEP
    = 1

Uses sha1 by default.

ENCRYPTION_PKCS1

Use PKCS#1 padding.


    public
    mixed
    ENCRYPTION_PKCS1
    = 2

Although self::ENCRYPTION_OAEP offers more security, including PKCS#1 padding is necessary for purposes of backwards compatibility with protocols (like SSH-1) written before OAEP's introduction.

MODE_INTERNAL

To use the pure-PHP implementation


    public
    mixed
    MODE_INTERNAL
    = 1

MODE_OPENSSL

To use the OpenSSL library


    public
    mixed
    MODE_OPENSSL
    = 2

(if enabled; otherwise, the internal implementation will be used)

PRIVATE_FORMAT_OPENSSH

OpenSSH formatted private key


    public
    mixed
    PRIVATE_FORMAT_OPENSSH
    = 9

PRIVATE_FORMAT_PKCS1

PKCS#1 formatted private key


    public
    mixed
    PRIVATE_FORMAT_PKCS1
    = 0

Used by OpenSSH

PRIVATE_FORMAT_PKCS8

PKCS#8 formatted private key


    public
    mixed
    PRIVATE_FORMAT_PKCS8
    = 8

PRIVATE_FORMAT_PUTTY

PuTTY formatted private key


    public
    mixed
    PRIVATE_FORMAT_PUTTY
    = 1

PRIVATE_FORMAT_XML

XML formatted private key


    public
    mixed
    PRIVATE_FORMAT_XML
    = 2

PUBLIC_FORMAT_OPENSSH

OpenSSH formatted public key


    public
    mixed
    PUBLIC_FORMAT_OPENSSH
    = 6

Place in $HOME/.ssh/authorized_keys

PUBLIC_FORMAT_PKCS1

PKCS#1 formatted public key (raw)


    public
    mixed
    PUBLIC_FORMAT_PKCS1
    = 4

Used by File/X509.php

Has the following header:

-----BEGIN RSA PUBLIC KEY-----

Analogous to ssh-keygen's pem format (as specified by -m)

PUBLIC_FORMAT_PKCS1_RAW


    public
    mixed
    PUBLIC_FORMAT_PKCS1_RAW
    = 4

PUBLIC_FORMAT_PKCS8

PKCS#1 formatted public key (encapsulated)


    public
    mixed
    PUBLIC_FORMAT_PKCS8
    = 7

Used by PHP's openssl_public_encrypt() and openssl's rsautl (when -pubin is set)

Has the following header:

-----BEGIN PUBLIC KEY-----

Analogous to ssh-keygen's pkcs8 format (as specified by -m). Although PKCS8 is specific to private keys it's basically creating a DER-encoded wrapper for keys. This just extends that same concept to public keys (much like ssh-keygen)

PUBLIC_FORMAT_RAW

Raw public key


    public
    mixed
    PUBLIC_FORMAT_RAW
    = 3

An array containing two \phpseclib\Math\BigInteger objects.

The exponent can be indexed with any of the following:

0, e, exponent, publicExponent

The modulus can be indexed with any of the following:

1, n, modulo, modulus

PUBLIC_FORMAT_XML

XML formatted public key


    public
    mixed
    PUBLIC_FORMAT_XML
    = 5

SIGNATURE_PKCS1

Use the PKCS#1 scheme by default.


    public
    mixed
    SIGNATURE_PKCS1
    = 2

Although self::SIGNATURE_PSS offers more security, including PKCS#1 signing is necessary for purposes of backwards compatibility with protocols (like SSH-2) written before PSS's introduction.

SIGNATURE_PSS

Use the Probabilistic Signature Scheme for signing


    public
    mixed
    SIGNATURE_PSS
    = 1

Uses sha1 by default.

$coefficients

Coefficients for Chinese Remainder Theorem (ie. qInv)


    public
        array<string|int, mixed>
    $coefficients

$comment

Public key comment field.


    public
        string
    $comment
     = 'phpseclib-generated-key'

$components

Components


    public
        array<string|int, mixed>
    $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.

$configFile

OpenSSL configuration file name.


    public
        mixed
    $configFile

Set to null to use system configuration file.

$current

Current String


    public
        mixed
    $current

For use with parsing XML formatted keys.

$encryptionMode

Encryption mode


    public
        int
    $encryptionMode
     = self::ENCRYPTION_OAEP

$exponent

Exponent (ie. e or d)


    public
        BigInteger
    $exponent

$exponents

Exponents for Chinese Remainder Theorem (ie. dP and dQ)


    public
        array<string|int, mixed>
    $exponents

$hash

Hash function


    public
        Hash
    $hash

$hashName

Hash name


    public
        string
    $hashName

$hLen

Length of hash function output


    public
        int
    $hLen

$k

Modulus length


    public
        BigInteger
    $k

$mgfHash

Hash function for the Mask Generation Function


    public
        Hash
    $mgfHash

$mgfHLen

Length of MGF hash function output


    public
        int
    $mgfHLen

$modulus

Modulus (ie. n)


    public
        BigInteger
    $modulus

$one

Precomputed One


    public
        BigInteger
    $one

$password

Password


    public
        string
    $password
     = false

$primes

Primes for Chinese Remainder Theorem (ie. p and q)


    public
        array<string|int, mixed>
    $primes

$privateKeyFormat

Private Key Format


    public
        int
    $privateKeyFormat
     = self::PRIVATE_FORMAT_PKCS1

$publicExponent

Public Exponent


    public
        mixed
    $publicExponent
     = false

$publicKeyFormat

Public Key Format


    public
        int
    $publicKeyFormat
     = self::PUBLIC_FORMAT_PKCS8

$signatureMode

Signature mode


    public
        int
    $signatureMode
     = self::SIGNATURE_PSS

$sLen

Length of salt


    public
        int
    $sLen

$zero

Precomputed Zero


    public
        BigInteger
    $zero

__clone()

__clone() magic method


    public
                __clone() : Crypt_RSA

Return values

Crypt_RSA —

__construct()

The constructor


    public
                __construct() : RSA

If you want to make use of the openssl extension, you'll need to set the mode manually, yourself. The reason \phpseclib\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.

Return values

RSA —

__toString()

__toString() magic method


    public
                __toString() : string

Return values

string —

_blind()

Performs RSA Blinding


    public
                _blind(BigInteger $x, BigInteger $r, int $i) : BigInteger

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

Parameters

$x : BigInteger
$r : BigInteger
$i : int

Return values

BigInteger —

_convertPrivateKey()

Convert a private key to the appropriate format.


    public
                _convertPrivateKey(mixed $n, mixed $e, mixed $d, mixed $primes, mixed $exponents, mixed $coefficients) : string

Parameters

$n : mixed
$e : mixed
$d : mixed
$primes : mixed
$exponents : mixed
$coefficients : mixed

Return values

string —

_convertPublicKey()

Convert a public key to the appropriate format


    public
                _convertPublicKey(mixed $n, mixed $e) : string

Parameters

$n : mixed
$e : mixed

Return values

string —

_data_handler()

Data Handler


    public
                _data_handler(resource $parser, string $data) : mixed

Called by xml_set_character_data_handler()

Parameters

$parser : resource
$data : string

Return values

mixed —

_decodeLength()

DER-decode the length


    public
                _decodeLength(string &$string) : int

DER supports lengths up to (2**8)127, however, we'll only support lengths up to (28)**4. See X.690 paragraph 8.1.3 for more information.

Parameters

$string : string

Return values

int —

_emsa_pkcs1_v1_5_encode()

EMSA-PKCS1-V1_5-ENCODE


    public
                _emsa_pkcs1_v1_5_encode(string $m, int $emLen) : string

See RFC3447#section-9.2.

Parameters

$m : string
$emLen : int

Return values

string —

_emsa_pss_encode()

EMSA-PSS-ENCODE


    public
                _emsa_pss_encode(string $m, int $emBits) : mixed

See RFC3447#section-9.1.1.

Parameters

$m : string
$emBits : int

Return values

mixed —

_emsa_pss_verify()

EMSA-PSS-VERIFY


    public
                _emsa_pss_verify(string $m, string $em, int $emBits) : string

See RFC3447#section-9.1.2.

Parameters

$m : string
$em : string
$emBits : int

Return values

string —

_encodeLength()

DER-encode the length


    public
                _encodeLength(int $length) : string

DER supports lengths up to (2**8)127, however, we'll only support lengths up to (28)**4. See X.690 paragraph 8.1.3 for more information.

Parameters

$length : int

Return values

string —

_equals()

Performs blinded RSA equality testing


    public
                _equals(string $x, string $y) : bool

Protects against a particular type of timing attack described.

See A Lesson In Timing Attacks (or, Don't use MessageDigest.isEquals)

Thanks for the heads up singpolyma!

Parameters

$x : string
$y : string

Return values

bool —

_exponentiate()

Exponentiate with or without Chinese Remainder Theorem


    public
                _exponentiate(BigInteger $x) : BigInteger

See RFC3447#section-5.1.2.

Parameters

$x : BigInteger

Return values

BigInteger —

_extractBER()

Extract raw BER from Base64 encoding


    public
                _extractBER(string $str) : string

Parameters

$str : string

Return values

string —

_generateMinMax()

Generates the smallest and largest numbers requiring $bits bits


    public
                _generateMinMax(int $bits) : array<string|int, mixed>

Parameters

$bits : int

Return values

array<string|int, mixed> —

_getPrivatePublicKey()

Returns a minimalistic private key


    public
                _getPrivatePublicKey([mixed $mode = self::PUBLIC_FORMAT_PKCS8 ]) : mixed

Returns the private key without the prime number constituants. Structurally identical to a public key that hasn't been set as the public key

Parameters

$mode : mixed = self::PUBLIC_FORMAT_PKCS8

Return values

mixed —

_i2osp()

Integer-to-Octet-String primitive


    public
                _i2osp(BigInteger $x, int $xLen) : string

See RFC3447#section-4.1.

Parameters

$x : BigInteger
$xLen : int

Return values

string —

_mgf1()

MGF1


    public
                _mgf1(string $mgfSeed, mixed $maskLen) : string

See RFC3447#appendix-B.2.1.

Parameters

$mgfSeed : string
$maskLen : mixed

Return values

string —

_os2ip()

Octet-String-to-Integer primitive


    public
                _os2ip(string $x) : BigInteger

See RFC3447#section-4.2.

Parameters

$x : string

Return values

BigInteger —

_parseKey()

Break a public or private key down into its constituant components


    public
                _parseKey(string|array<string|int, mixed> $key, int $type) : array<string|int, mixed>|bool

Parameters

$key : string|array<string|int, mixed>
$type : int

Return values

array<string|int, mixed>|bool —

_raw_encrypt()

Raw Encryption / Decryption


    public
                _raw_encrypt(string $m) : string

Doesn't use padding and is not recommended.

Parameters

$m : string

Return values

string —

_rsadp()

RSADP


    public
                _rsadp(BigInteger $c) : BigInteger

See RFC3447#section-5.1.2.

Parameters

$c : BigInteger

Return values

BigInteger —

_rsaep()

RSAEP


    public
                _rsaep(BigInteger $m) : BigInteger

See RFC3447#section-5.1.1.

Parameters

$m : BigInteger

Return values

BigInteger —

_rsaes_oaep_decrypt()

RSAES-OAEP-DECRYPT


    public
                _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.

Parameters

$c : string
$l : string = ''

Return values

string —

_rsaes_oaep_encrypt()

RSAES-OAEP-ENCRYPT


    public
                _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}.

Parameters

$m : string
$l : string = ''

Return values

string —

_rsaes_pkcs1_v1_5_decrypt()

RSAES-PKCS1-V1_5-DECRYPT


    public
                _rsaes_pkcs1_v1_5_decrypt(string $c) : string

See RFC3447#section-7.2.2.

For compatibility 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 compatibility 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 \phpseclib\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.

Parameters

$c : string

Return values

string —

_rsaes_pkcs1_v1_5_encrypt()

RSAES-PKCS1-V1_5-ENCRYPT


    public
                _rsaes_pkcs1_v1_5_encrypt(string $m) : string

See RFC3447#section-7.2.1.

Parameters

$m : string

Return values

string —

_rsasp1()

RSASP1


    public
                _rsasp1(BigInteger $m) : BigInteger

See RFC3447#section-5.2.1.

Parameters

$m : BigInteger

Return values

BigInteger —

_rsassa_pkcs1_v1_5_sign()

RSASSA-PKCS1-V1_5-SIGN


    public
                _rsassa_pkcs1_v1_5_sign(string $m) : string

See RFC3447#section-8.2.1.

Parameters

$m : string

Return values

string —

_rsassa_pkcs1_v1_5_verify()

RSASSA-PKCS1-V1_5-VERIFY


    public
                _rsassa_pkcs1_v1_5_verify(string $m, mixed $s) : string

See RFC3447#section-8.2.2.

Parameters

$m : string
$s : mixed

Return values

string —

_rsassa_pss_sign()

RSASSA-PSS-SIGN


    public
                _rsassa_pss_sign(string $m) : string

See RFC3447#section-8.1.1.

Parameters

$m : string

Return values

string —

_rsassa_pss_verify()

RSASSA-PSS-VERIFY


    public
                _rsassa_pss_verify(string $m, string $s) : string

See RFC3447#section-8.1.2.

Parameters

$m : string
$s : string

Return values

string —

_rsavp1()

RSAVP1


    public
                _rsavp1(BigInteger $s) : BigInteger

See RFC3447#section-5.2.2.

Parameters

$s : BigInteger

Return values

BigInteger —

_start_element_handler()

Start Element Handler


    public
                _start_element_handler(resource $parser, string $name, array<string|int, mixed> $attribs) : mixed

Called by xml_set_element_handler()

Parameters

$parser : resource
$name : string
$attribs : array<string|int, mixed>

Return values

mixed —

_stop_element_handler()

Stop Element Handler


    public
                _stop_element_handler(resource $parser, string $name) : mixed

Called by xml_set_element_handler()

Parameters

$parser : resource
$name : string

Return values

mixed —

_string_shift()

String Shift


    public
                _string_shift(string &$string[, int $index = 1 ]) : string

Inspired by array_shift

Parameters

$string : string
$index : int = 1

Return values

string —

createKey()

Create public / private key pair


    public
                createKey([int $bits = 1024 ][, int $timeout = false ][, mixed $partial = array() ]) : mixed

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 \phpseclib\Crypt\RSA::createKey() as the third parameter for further processing.

Parameters

$bits : int = 1024
$timeout : int = false
$partial : mixed = array()

Return values

mixed —

decrypt()

Decryption


    public
                decrypt(mixed $ciphertext) : string

Parameters

$ciphertext : mixed

Return values

string —

encrypt()

Encryption


    public
                encrypt(string $plaintext) : string

Both self::ENCRYPTION_OAEP and self::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.

Parameters

$plaintext : string

Return values

string —

getComment()

Get public key comment.


    public
                getComment() : string

Return values

string —

getPrivateKey()

Returns the private key


    public
                getPrivateKey([int $type = self::PUBLIC_FORMAT_PKCS1 ]) : mixed

The private key is only returned if the currently loaded key contains the constituent prime numbers.

Parameters

$type : int = self::PUBLIC_FORMAT_PKCS1: optional

Return values

mixed —

getPublicKey()

Returns the public key


    public
                getPublicKey([int $type = self::PUBLIC_FORMAT_PKCS8 ]) : mixed

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.

Parameters

$type : int = self::PUBLIC_FORMAT_PKCS8: optional

Return values

mixed —

getPublicKeyFingerprint()

Returns the public key's fingerprint


    public
                getPublicKeyFingerprint([string $algorithm = 'md5' ]) : mixed

The public key's fingerprint is returned, which is equivalent to running ssh-keygen -lf rsa.pub. If there is no public key currently loaded, false is returned. Example output (md5): "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87" (as specified by RFC 4716)

Parameters

$algorithm : string = 'md5': The hashing algorithm to be used. Valid options are 'md5' and 'sha256'. False is returned for invalid values.

Return values

mixed —

getSize()

Returns the key size


    public
                getSize() : int

More specifically, this returns the size of the modulo in bits.

Return values

int —

loadKey()

Loads a public or private key


    public
                loadKey(string|RSA|array<string|int, mixed> $key[, bool|int $type = false ]) : bool

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

Parameters

$key : string|RSA|array<string|int, mixed>
$type : bool|int = false: optional

Return values

bool —

setComment()

Set public key comment.


    public
                setComment(string $comment) : mixed

Parameters

$comment : string

Return values

mixed —

setEncryptionMode()

Set Encryption Mode


    public
                setEncryptionMode(int $mode) : mixed

Valid values include self::ENCRYPTION_OAEP and self::ENCRYPTION_PKCS1.

Parameters

$mode : int

Return values

mixed —

setHash()

Determines which hashing function should be used


    public
                setHash(string $hash) : mixed

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

Parameters

$hash : string

Return values

mixed —

setMGFHash()

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


    public
                setMGFHash(string $hash) : mixed

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

Parameters

$hash : string

Return values

mixed —

setPassword()

Sets the password


    public
                setPassword([string $password = false ]) : mixed

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_string($password) is true.

Parameters

$password : string = false

Return values

mixed —

setPrivateKey()

Defines the private key


    public
                setPrivateKey([string $key = false ][, int $type = false ]) : bool

If phpseclib guessed a private key was a public key and loaded it as such it might be desirable to force phpseclib to treat the key as a private key. This function will do that.

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

Returns true on success, false on failure

Parameters

$key : string = false: optional
$type : int = false: optional

Return values

bool —

setPrivateKeyFormat()

Determines the private key format


    public
                setPrivateKeyFormat(int $format) : mixed

Parameters

$format : int

Return values

mixed —

setPublicKey()

Defines the public key


    public
                setPublicKey([string $key = false ][, int $type = false ]) : bool

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. phpseclib tries to guess if the key being used is the public key but in the event that it guesses incorrectly you might still want to explicitly set the key as being public.

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

Returns true on success, false on failure

Parameters

$key : string = false: optional
$type : int = false: optional

Return values

bool —

setPublicKeyFormat()

Determines the public key format


    public
                setPublicKeyFormat(int $format) : mixed

Parameters

$format : int

Return values

mixed —

setSaltLength()

Determines the salt length


    public
                setSaltLength(mixed $sLen) : mixed

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.

Parameters

$sLen : mixed

Return values

mixed —

setSignatureMode()

Set Signature Mode


    public
                setSignatureMode(int $mode) : mixed

Valid values include self::SIGNATURE_PSS and self::SIGNATURE_PKCS1

Parameters

$mode : int

Return values

mixed —

sign()

Create a signature


    public
                sign(string $message) : string

Parameters

$message : string

Return values

string —

verify()

Verifies a signature


    public
                verify(string $message, string $signature) : bool

Parameters

$message : string
$signature : string

Return values

bool —