[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/vendor/phpseclib/phpseclib/phpseclib/Crypt/ -> RSA.php (summary)

Pure-PHP PKCS#1 (v2.1) compliant implementation of RSA. PHP version 5

Author: Jim Wigginton
Copyright: 2009 Jim Wigginton
License: http://www.opensource.org/licenses/mit-license.html MIT License
Link: http://phpseclib.sourceforge.net
File Size: 3342 lines (118 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

RSA:: (60 methods):
  __construct()
  createKey()
  _convertPrivateKey()
  _convertPublicKey()
  _parseKey()
  getSize()
  _start_element_handler()
  _stop_element_handler()
  _data_handler()
  loadKey()
  setPassword()
  setPublicKey()
  setPrivateKey()
  getPublicKey()
  getPublicKeyFingerprint()
  getPrivateKey()
  _getPrivatePublicKey()
  __toString()
  __clone()
  _generateMinMax()
  _decodeLength()
  _encodeLength()
  _string_shift()
  setPrivateKeyFormat()
  setPublicKeyFormat()
  setHash()
  setMGFHash()
  setSaltLength()
  _i2osp()
  _os2ip()
  _exponentiate()
  _blind()
  _equals()
  _rsaep()
  _rsadp()
  _rsasp1()
  _rsavp1()
  _mgf1()
  _rsaes_oaep_encrypt()
  _rsaes_oaep_decrypt()
  _raw_encrypt()
  _rsaes_pkcs1_v1_5_encrypt()
  _rsaes_pkcs1_v1_5_decrypt()
  _emsa_pss_encode()
  _emsa_pss_verify()
  _rsassa_pss_sign()
  _rsassa_pss_verify()
  _emsa_pkcs1_v1_5_encode()
  _emsa_pkcs1_v1_5_encode_without_null()
  _rsassa_pkcs1_v1_5_sign()
  _rsassa_pkcs1_v1_5_verify()
  setEncryptionMode()
  setSignatureMode()
  setComment()
  getComment()
  encrypt()
  decrypt()
  sign()
  verify()
  _extractBER()


Class: RSA  - X-Ref

Pure-PHP PKCS#1 compliant implementation of RSA.

__construct()   X-Ref
The constructor

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: \phpseclib\Crypt\RSA

createKey($bits = 1024, $timeout = false, $partial = array()   X-Ref
Create public / private key pair

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.

param: int $bits
param: int $timeout
param: array $partial

_convertPrivateKey($n, $e, $d, $primes, $exponents, $coefficients)   X-Ref
Convert a private key to the appropriate format.

param: Math_BigInteger $n
param: Math_BigInteger $e
param: Math_BigInteger $d
param: array<int,Math_BigInteger> $primes
param: array<int,Math_BigInteger> $exponents
param: array<int,Math_BigInteger> $coefficients
see: self::setPrivateKeyFormat()
return: string

_convertPublicKey($n, $e)   X-Ref
Convert a public key to the appropriate format

param: Math_BigInteger $n
param: Math_BigInteger $e
see: self::setPublicKeyFormat()
return: string|array<string,Math_BigInteger>

_parseKey($key, $type)   X-Ref
Break a public or private key down into its constituant components

param: string|array $key
param: int $type
see: self::_convertPublicKey()
see: self::_convertPrivateKey()
return: array|bool

getSize()   X-Ref
No description

_start_element_handler($parser, $name, $attribs)   X-Ref
Start Element Handler

Called by xml_set_element_handler()

param: resource $parser
param: string $name
param: array $attribs

_stop_element_handler($parser, $name)   X-Ref
Stop Element Handler

Called by xml_set_element_handler()

param: resource $parser
param: string $name

_data_handler($parser, $data)   X-Ref
Data Handler

Called by xml_set_character_data_handler()

param: resource $parser
param: string $data

loadKey($key, $type = false)   X-Ref
Loads a public or private key

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

param: string|RSA|array $key
param: bool|int $type optional
return: bool

setPassword($password = false)   X-Ref
Sets the 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_string($password) is true.

param: string $password
see: self::createKey()
see: self::loadKey()

setPublicKey($key = false, $type = false)   X-Ref
Defines the public key

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

param: string $key optional
param: int $type optional
see: self::getPublicKey()
return: bool

setPrivateKey($key = false, $type = false)   X-Ref
Defines the private key

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

param: string $key optional
param: int $type optional
see: self::getPublicKey()
return: bool

getPublicKey($type = self::PUBLIC_FORMAT_PKCS8)   X-Ref
Returns the public key

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.

param: int $type optional
see: self::getPublicKey()

getPublicKeyFingerprint($algorithm = 'md5')   X-Ref
Returns the public key's fingerprint

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)

param: string $algorithm The hashing algorithm to be used. Valid options are 'md5' and 'sha256'. False is returned
return: mixed

getPrivateKey($type = self::PUBLIC_FORMAT_PKCS1)   X-Ref
Returns the private key

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

param: int $type optional
see: self::getPublicKey()
return: mixed

_getPrivatePublicKey($mode = self::PUBLIC_FORMAT_PKCS8)   X-Ref
Returns a minimalistic private key

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

param: int $mode optional
see: self::getPrivateKey()

__toString()   X-Ref
__toString() magic method

return: string

__clone()   X-Ref
__clone() magic method

return: Crypt_RSA

_generateMinMax($bits)   X-Ref
Generates the smallest and largest numbers requiring $bits bits

param: int $bits
return: array

_decodeLength(&$string)   X-Ref
DER-decode the length

DER supports lengths up to (2**8)**127, however, we'll only support lengths up to (2**8)**4.  See
{@link http://itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf#p=13 X.690 paragraph 8.1.3} for more information.

param: string $string
return: int

_encodeLength($length)   X-Ref
DER-encode the length

DER supports lengths up to (2**8)**127, however, we'll only support lengths up to (2**8)**4.  See
{@link http://itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf#p=13 X.690 paragraph 8.1.3} for more information.

param: int $length
return: string

_string_shift(&$string, $index = 1)   X-Ref
String Shift

Inspired by array_shift

param: string $string
param: int $index
return: string

setPrivateKeyFormat($format)   X-Ref
Determines the private key format

param: int $format
see: self::createKey()

setPublicKeyFormat($format)   X-Ref
Determines the public key format

param: int $format
see: self::createKey()

setHash($hash)   X-Ref
Determines which hashing function should be used

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.

param: string $hash

setMGFHash($hash)   X-Ref
Determines which hashing function should be used for the mask generation function

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.

param: string $hash

setSaltLength($sLen)   X-Ref
Determines the salt length

To quote from {@link http://tools.ietf.org/html/rfc3447#page-38 RFC3447#page-38}:

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

param: int $sLen

_i2osp($x, $xLen)   X-Ref
Integer-to-Octet-String primitive

See {@link http://tools.ietf.org/html/rfc3447#section-4.1 RFC3447#section-4.1}.

param: \phpseclib\Math\BigInteger $x
param: int $xLen
return: string

_os2ip($x)   X-Ref
Octet-String-to-Integer primitive

See {@link http://tools.ietf.org/html/rfc3447#section-4.2 RFC3447#section-4.2}.

param: int|string|resource $x
return: \phpseclib\Math\BigInteger

_exponentiate($x)   X-Ref
Exponentiate with or without Chinese Remainder Theorem

See {@link http://tools.ietf.org/html/rfc3447#section-5.1.1 RFC3447#section-5.1.2}.

param: \phpseclib\Math\BigInteger $x
return: \phpseclib\Math\BigInteger

_blind($x, $r, $i)   X-Ref
Performs RSA Blinding

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

param: \phpseclib\Math\BigInteger $x
param: \phpseclib\Math\BigInteger $r
param: int $i
return: \phpseclib\Math\BigInteger

_equals($x, $y)   X-Ref
Performs blinded RSA equality testing

Protects against a particular type of timing attack described.

See {@link http://codahale.com/a-lesson-in-timing-attacks/ A Lesson In Timing Attacks (or, Don't use MessageDigest.isEquals)}

Thanks for the heads up singpolyma!

param: string $x
param: string $y
return: bool

_rsaep($m)   X-Ref
RSAEP

See {@link http://tools.ietf.org/html/rfc3447#section-5.1.1 RFC3447#section-5.1.1}.

param: \phpseclib\Math\BigInteger $m
return: \phpseclib\Math\BigInteger

_rsadp($c)   X-Ref
RSADP

See {@link http://tools.ietf.org/html/rfc3447#section-5.1.2 RFC3447#section-5.1.2}.

param: \phpseclib\Math\BigInteger $c
return: \phpseclib\Math\BigInteger

_rsasp1($m)   X-Ref
RSASP1

See {@link http://tools.ietf.org/html/rfc3447#section-5.2.1 RFC3447#section-5.2.1}.

param: \phpseclib\Math\BigInteger $m
return: \phpseclib\Math\BigInteger

_rsavp1($s)   X-Ref
RSAVP1

See {@link http://tools.ietf.org/html/rfc3447#section-5.2.2 RFC3447#section-5.2.2}.

param: \phpseclib\Math\BigInteger $s
return: \phpseclib\Math\BigInteger

_mgf1($mgfSeed, $maskLen)   X-Ref
MGF1

See {@link http://tools.ietf.org/html/rfc3447#appendix-B.2.1 RFC3447#appendix-B.2.1}.

param: string $mgfSeed
param: int $maskLen
return: string

_rsaes_oaep_encrypt($m, $l = '')   X-Ref
RSAES-OAEP-ENCRYPT

See {@link http://tools.ietf.org/html/rfc3447#section-7.1.1 RFC3447#section-7.1.1} and
{http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding OAES}.

param: string $m
param: string $l
return: string

_rsaes_oaep_decrypt($c, $l = '')   X-Ref
RSAES-OAEP-DECRYPT

See {@link http://tools.ietf.org/html/rfc3447#section-7.1.2 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 {@link http://tools.ietf.org/html/rfc3447#page-17 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.

param: string $c
param: string $l
return: string

_raw_encrypt($m)   X-Ref
Raw Encryption / Decryption

Doesn't use padding and is not recommended.

param: string $m
return: string

_rsaes_pkcs1_v1_5_encrypt($m)   X-Ref
RSAES-PKCS1-V1_5-ENCRYPT

See {@link http://tools.ietf.org/html/rfc3447#section-7.2.1 RFC3447#section-7.2.1}.

param: string $m
return: string

_rsaes_pkcs1_v1_5_decrypt($c)   X-Ref
RSAES-PKCS1-V1_5-DECRYPT

See {@link http://tools.ietf.org/html/rfc3447#section-7.2.2 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.

param: string $c
return: string

_emsa_pss_encode($m, $emBits)   X-Ref
EMSA-PSS-ENCODE

See {@link http://tools.ietf.org/html/rfc3447#section-9.1.1 RFC3447#section-9.1.1}.

param: string $m
param: int $emBits

_emsa_pss_verify($m, $em, $emBits)   X-Ref
EMSA-PSS-VERIFY

See {@link http://tools.ietf.org/html/rfc3447#section-9.1.2 RFC3447#section-9.1.2}.

param: string $m
param: string $em
param: int $emBits
return: string

_rsassa_pss_sign($m)   X-Ref
RSASSA-PSS-SIGN

See {@link http://tools.ietf.org/html/rfc3447#section-8.1.1 RFC3447#section-8.1.1}.

param: string $m
return: string

_rsassa_pss_verify($m, $s)   X-Ref
RSASSA-PSS-VERIFY

See {@link http://tools.ietf.org/html/rfc3447#section-8.1.2 RFC3447#section-8.1.2}.

param: string $m
param: string $s
return: string

_emsa_pkcs1_v1_5_encode($m, $emLen)   X-Ref
EMSA-PKCS1-V1_5-ENCODE

See {@link http://tools.ietf.org/html/rfc3447#section-9.2 RFC3447#section-9.2}.

param: string $m
param: int $emLen
return: string

_emsa_pkcs1_v1_5_encode_without_null($m, $emLen)   X-Ref
EMSA-PKCS1-V1_5-ENCODE (without NULL)

Quoting https://tools.ietf.org/html/rfc8017#page-65,

"The parameters field associated with id-sha1, id-sha224, id-sha256,
id-sha384, id-sha512, id-sha512/224, and id-sha512/256 should
generally be omitted, but if present, it shall have a value of type
NULL"

param: string $m
param: int $emLen
return: string

_rsassa_pkcs1_v1_5_sign($m)   X-Ref
RSASSA-PKCS1-V1_5-SIGN

See {@link http://tools.ietf.org/html/rfc3447#section-8.2.1 RFC3447#section-8.2.1}.

param: string $m
return: string

_rsassa_pkcs1_v1_5_verify($m, $s)   X-Ref
RSASSA-PKCS1-V1_5-VERIFY

See {@link http://tools.ietf.org/html/rfc3447#section-8.2.2 RFC3447#section-8.2.2}.

param: string $m
param: string $s
return: string

setEncryptionMode($mode)   X-Ref
Set Encryption Mode

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

param: int $mode

setSignatureMode($mode)   X-Ref
Set Signature Mode

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

param: int $mode

setComment($comment)   X-Ref
Set public key comment.

param: string $comment

getComment()   X-Ref
Get public key comment.

return: string

encrypt($plaintext)   X-Ref
Encryption

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.

param: string $plaintext
see: self::decrypt()
return: string

decrypt($ciphertext)   X-Ref
Decryption

param: string $ciphertext
see: self::encrypt()
return: string

sign($message)   X-Ref
Create a signature

param: string $message
see: self::verify()
return: string

verify($message, $signature)   X-Ref
Verifies a signature

param: string $message
param: string $signature
see: self::sign()
return: bool

_extractBER($str)   X-Ref
Extract raw BER from Base64 encoding

param: string $str
return: string