octoleo
/
phpseclib
mirror of https://github.com/phpseclib/phpseclib.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update how @internal phpdoc attributes are used

This commit is contained in:
terrafrost 2020-12-30 05:05:54 -06:00
parent 7a9418e4e0
commit a19b5b4ca8
14 changed files with 67 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
phpseclib/Crypt/Blowfish.php
View File

@ -274,14 +274,14 @@ class Blowfish extends BlockCipher
/**
* The Key Length (in bytes)
* {@internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16. Exists in conjunction with $Nk
* because the encryption / decryption / key schedule creation requires this number and not $key_length. We could
* derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.}
*
* @see \phpseclib3\Crypt\Common\SymmetricKey::setKeyLength()
* @var int
* @access private
* @internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16. Exists in conjunction with $Nk
* because the encryption / decryption / key schedule creation requires this number and not $key_length. We could
* derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.
*/
protected $key_length = 16;

29
phpseclib/Crypt/Common/SymmetricKey.php
View File

@ -660,11 +660,12 @@ abstract class SymmetricKey
*
* setIV() is not required when ecb or gcm modes are being used.
*
* {@internal Can be overwritten by a sub class, but does not have to be}
*
* @access public
* @param string $iv
* @throws \LengthException if the IV length isn't equal to the block size
* @throws \BadMethodCallException if an IV is provided when one shouldn't be
* @internal Can be overwritten by a sub class, but does not have to be
*/
public function setIV($iv)
{
@ -855,9 +856,10 @@ abstract class SymmetricKey
*
* If the key is not explicitly set, it'll be assumed to be all null bytes.
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @access public
* @param string $key
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function setKey($key)
{
@ -879,6 +881,8 @@ abstract class SymmetricKey
*
* Where $hash (default = sha1) currently supports the following hashes: see: Crypt/Hash.php
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see Crypt/Hash.php
* @param string $password
* @param string $method
@ -886,7 +890,6 @@ abstract class SymmetricKey
* @throws \LengthException if pbkdf1 is being used and the derived key length exceeds the hash length
* @return bool
* @access public
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function setPassword($password, $method = 'pbkdf2', ...$func_args)
{
@ -1086,11 +1089,12 @@ abstract class SymmetricKey
* strlen($plaintext) will still need to be a multiple of the block size, however, arbitrary values can be added to make it that
* length.
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see self::decrypt()
* @access public
* @param string $plaintext
* @return string $ciphertext
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function encrypt($plaintext)
{
@ -1429,12 +1433,13 @@ abstract class SymmetricKey
* If strlen($ciphertext) is not a multiple of the block size, null bytes will be added to the end of the string until
* it is.
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see self::encrypt()
* @access public
* @param string $ciphertext
* @return string $plaintext
* @throws \LengthException if we're inside a block cipher and the ciphertext length is not a multiple of the block size
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function decrypt($ciphertext)
{
@ -2073,9 +2078,10 @@ abstract class SymmetricKey
* continuous buffers not be used. They do offer better security and are, in fact, sometimes required (SSH uses them),
* however, they are also less intuitive and more likely to cause you problems.
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see self::disableContinuousBuffer()
* @access public
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function enableContinuousBuffer()
{
@ -2097,9 +2103,10 @@ abstract class SymmetricKey
*
* The default behavior.
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see self::enableContinuousBuffer()
* @access public
* @internal Could, but not must, extend by the child Crypt_* class
*/
public function disableContinuousBuffer()
{
@ -2331,12 +2338,14 @@ abstract class SymmetricKey
*
* - First run of encrypt() / decrypt() with no init-settings
*
* {@internal setup() is always called before en/decryption.}
*
* {@internal Could, but not must, extend by the child Crypt_* class}
*
* @see self::setKey()
* @see self::setIV()
* @see self::disableContinuousBuffer()
* @access private
* @internal setup() is always called before en/decryption.
* @internal Could, but not must, extend by the child Crypt_* class
*/
protected function setup()
{
@ -2529,13 +2538,13 @@ abstract class SymmetricKey
* - $in (the content of $in has to en/decrypt by the generated code)
* - The callback function should not use the 'return' statement, but en/decrypt'ing the content of $in only
*
* {@internal If a Crypt_* class providing inline crypting it must extend _setupInlineCrypt()}
*
* @see self::setup()
* @see self::createInlineCryptFunction()
* @see self::encrypt()
* @see self::decrypt()
* @access private
* @internal If a Crypt_* class providing inline crypting it must extend _setupInlineCrypt()
*/
//protected function setupInlineCrypt();

9
phpseclib/Crypt/RC2.php
View File

@ -116,23 +116,26 @@ class RC2 extends BlockCipher
/**
* The key length in bits.
*
* {@internal Should be in range [1..1024].}
*
* {@internal Changing this value after setting the key has no effect.}
*
* @see self::setKeyLength()
* @see self::setKey()
* @var int
* @access private
* @internal Should be in range [1..1024].
* @internal Changing this value after setting the key has no effect.
*/
private $default_key_length = 1024;
/**
* The key length in bits.
*
* {@internal Should be in range [1..1024].}
*
* @see self::isValidEnine()
* @see self::setKey()
* @var int
* @access private
* @internal Should be in range [1..1024].
*/
private $current_key_length;

21
phpseclib/Crypt/Rijndael.php
View File

@ -107,26 +107,28 @@ class Rijndael extends BlockCipher
/**
* The Block Length divided by 32
*
* {@internal The max value is 256 / 32 = 8, the min value is 128 / 32 = 4. Exists in conjunction with $block_size
* because the encryption / decryption / key schedule creation requires this number and not $block_size. We could
* derive this from $block_size or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.}
*
* @see self::setBlockLength()
* @var int
* @access private
* @internal The max value is 256 / 32 = 8, the min value is 128 / 32 = 4. Exists in conjunction with $block_size
* because the encryption / decryption / key schedule creation requires this number and not $block_size. We could
* derive this from $block_size or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.
*/
private $Nb = 4;
/**
* The Key Length (in bytes)
*
* {@internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16. Exists in conjunction with $Nk
* because the encryption / decryption / key schedule creation requires this number and not $key_length. We could
* derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.}
*
* @see self::setKeyLength()
* @var int
* @access private
* @internal The max value is 256 / 8 = 32, the min value is 128 / 8 = 16. Exists in conjunction with $Nk
* because the encryption / decryption / key schedule creation requires this number and not $key_length. We could
* derive this from $key_length or vice versa, but that'd mean we'd have to do multiple shift operations, so in lieu
* of that, we'll just precompute it once.
*/
protected $key_length = 16;
@ -143,9 +145,10 @@ class Rijndael extends BlockCipher
/**
* The Number of Rounds
*
* {@internal The max value is 14, the min value is 10.}
*
* @var int
* @access private
* @internal The max value is 14, the min value is 10.
*/
private $Nr;

3
phpseclib/Math/BigInteger.php
View File

@ -462,11 +462,12 @@ class BigInteger implements \Serializable
*
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
*
* {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
*
* @param BigInteger $y
* @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @access public
* @see self::equals()
* @internal Could return $this->subtract($x), but that's not as fast as what we do do.
*/
public function compare(BigInteger $y)
{

3
phpseclib/Math/BigInteger/Engines/BCMath.php
View File

@ -437,10 +437,11 @@ class BCMath extends Engine
*
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
*
* {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
*
* @param BCMath $y
* @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @see self::equals()
* @internal Could return $this->subtract($x), but that's not as fast as what we do do.
*/
public function compare(BCMath $y)
{

6
phpseclib/Math/BigInteger/Engines/Engine.php
View File

@ -257,9 +257,10 @@ abstract class Engine implements \Serializable
*
* Say you have (30 mod 17 * x mod 17) mod 17 == 1. x can be found using modular inverses.
*
* {@internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information.}
*
* @param \phpseclib3\Math\BigInteger\Engines\Engine $n
* @return \phpseclib3\Math\BigInteger\Engines\Engine|false
* @internal See {@link http://www.cacr.math.uwaterloo.ca/hac/about/chap14.pdf#page=21 HAC 14.64} for more information.
*/
protected function modInverseHelper(Engine $n)
{
@ -952,9 +953,10 @@ abstract class Engine implements \Serializable
*
* Returns the nth root of a positive biginteger, where n defaults to 2
*
* {@internal This function is based off of {@link http://mathforum.org/library/drmath/view/52605.html this page} and {@link http://stackoverflow.com/questions/11242920/calculating-nth-root-with-bcmath-in-php this stackoverflow question}.}
*
* @param int $n
* @return \phpseclib3\Math\BigInteger\Engines\Engine
* @internal This function is based off of {@link http://mathforum.org/library/drmath/view/52605.html this page} and {@link http://stackoverflow.com/questions/11242920/calculating-nth-root-with-bcmath-in-php this stackoverflow question}.
*/
protected function rootInner($n)
{

3
phpseclib/Math/BigInteger/Engines/GMP.php
View File

@ -288,11 +288,12 @@ class GMP extends Engine
*
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
*
* {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
*
* @param GMP $y
* @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @access public
* @see self::equals()
* @internal Could return $this->subtract($x), but that's not as fast as what we do do.
*/
public function compare(GMP $y)
{

3
phpseclib/Math/BigInteger/Engines/PHP32.php
View File

@ -290,11 +290,12 @@ class PHP32 extends PHP
*
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
*
* {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
*
* @param PHP32 $y
* @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @access public
* @see self::equals()
* @internal Could return $this->subtract($x), but that's not as fast as what we do do.
*/
public function compare(PHP32 $y)
{

3
phpseclib/Math/BigInteger/Engines/PHP64.php
View File

@ -294,11 +294,12 @@ class PHP64 extends PHP
*
* Note how the same comparison operator is used. If you want to test for equality, use $x->equals($y).
*
* {@internal Could return $this->subtract($x), but that's not as fast as what we do do.}
*
* @param PHP64 $y
* @return int in case < 0 if $this is less than $y; > 0 if $this is greater than $y, and 0 if they are equal.
* @access public
* @see self::equals()
* @internal Could return $this->subtract($x), but that's not as fast as what we do do.
*/
public function compare(PHP64 $y)
{

3
phpseclib/Net/SFTP.php
View File

@ -1843,6 +1843,8 @@ class SFTP extends SSH2
*
* Setting $local_start to > 0 or $mode | self::RESUME_START doesn't do anything unless $mode | self::SOURCE_LOCAL_FILE.
*
* {@internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().}
*
* @param string $remote_file
* @param string|resource $data
* @param int $mode
@ -1854,7 +1856,6 @@ class SFTP extends SSH2
* @throws \phpseclib3\Exception\FileNotFoundException if you're uploading via a file and the file doesn't exist
* @return bool
* @access public
* @internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().
*/
public function put($remote_file, $data, $mode = self::SOURCE_STRING, $start = -1, $local_start = -1, $progressCallback = null)
{

10
phpseclib/Net/SSH2.php
View File

@ -2100,14 +2100,15 @@ class SSH2
/**
* Login Helper
*
* {@internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
* by sending dummy SSH_MSG_IGNORE messages.}
*
* @param string $username
* @param string $password
* @return bool
* @throws \UnexpectedValueException on receipt of unexpected packets
* @throws \RuntimeException on other errors
* @access private
* @internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
* by sending dummy SSH_MSG_IGNORE messages.
*/
private function login_helper($username, $password = null)
{
@ -2403,13 +2404,14 @@ class SSH2
/**
* Login with an RSA private key
*
* {@internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
* by sending dummy SSH_MSG_IGNORE messages.}
*
* @param string $username
* @param \phpseclib3\Crypt\Common\PrivateKey $privatekey
* @return bool
* @throws \RuntimeException on connection error
* @access private
* @internal It might be worthwhile, at some point, to protect against {@link http://tools.ietf.org/html/rfc4251#section-9.3.9 traffic analysis}
* by sending dummy SSH_MSG_IGNORE messages.
*/
private function privatekey_login($username, PrivateKey $privatekey)
{

3
phpseclib/System/SSH/Agent.php
View File

@ -3,6 +3,8 @@
/**
* Pure-PHP ssh-agent client.
*
* {@internal See http://api.libssh.org/rfc/PROTOCOL.agent}
*
* PHP version 5
*
* Here are some examples of how to use this library:
@ -28,7 +30,6 @@
* @copyright 2014 Jim Wigginton
* @license http://www.opensource.org/licenses/mit-license.html MIT License
* @link http://phpseclib.sourceforge.net
* @internal See http://api.libssh.org/rfc/PROTOCOL.agent
*/
namespace phpseclib3\System\SSH;

3
phpseclib/System/SSH/Agent/Identity.php
View File

@ -3,6 +3,8 @@
/**
* Pure-PHP ssh-agent client.
*
* {@internal See http://api.libssh.org/rfc/PROTOCOL.agent}
*
* PHP version 5
*
* @category System
@ -11,7 +13,6 @@
* @copyright 2009 Jim Wigginton
* @license http://www.opensource.org/licenses/mit-license.html MIT License
* @link http://phpseclib.sourceforge.net
* @internal See http://api.libssh.org/rfc/PROTOCOL.agent
*/
namespace phpseclib3\System\SSH\Agent;