abstract class RSA extends AsymmetricKey (View source)

Pure-PHP PKCS#1 compliant implementation of RSA.

Constants

ALGORITHM

Algorithm Name

ENCRYPTION_OAEP

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

Uses sha256 by default

ENCRYPTION_PKCS1

Use PKCS#1 padding.

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

ENCRYPTION_NONE

Do not use any padding

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.

SIGNATURE_PSS

Use the Probabilistic Signature Scheme for signing

Uses sha256 and 0 as the salt length

SIGNATURE_RELAXED_PKCS1

Use a relaxed version of PKCS#1 padding for signature verification

SIGNATURE_PKCS1

Use PKCS#1 padding for signature verification

Properties

static protected BigInteger $zero Precomputed Zero from  AsymmetricKey
static protected BigInteger $one Precomputed One from  AsymmetricKey
protected string $format Format of the loaded key from  AsymmetricKey
protected Hash $hash Hash function from  AsymmetricKey
static protected bool[] $engines Available Engines from  AsymmetricKey
protected int $encryptionPadding Encryption padding mode
protected int $signaturePadding Signature padding mode
protected int $hLen Length of hash function output
protected int $sLen Length of salt
protected string $label Label
protected Hash $mgfHash Hash function for the Mask Generation Function
protected int $mgfHLen Length of MGF hash function output
protected BigInteger $modulus Modulus (ie. n)
protected BigInteger $k Modulus length
protected BigInteger $exponent Exponent (ie. e or d)
static protected bool $enableBlinding Enable Blinding?
static protected ?string $configFile OpenSSL configuration file name.

Methods

__construct()

Constructor

static 
initialize_static_variables()

Initialize static variables

static AsymmetricKey
load(string $key, string $password = false)

Load the key

PrivateKey
loadPrivateKey(string|array $key, string $password = '')

Loads a private key

PublicKey
loadPublicKey(string|array $key)

Loads a public key

AsymmetricKey
loadParameters(string|array $key)

Loads parameters

static AsymmetricKey
loadFormat(string $type, string $key, string $password = false)

Load the key, assuming a specific format

PrivateKey
loadPrivateKeyFormat(string $type, string $key, string $password = false)

Loads a private key

PublicKey
loadPublicKeyFormat(string $type, string $key)

Loads a public key

AsymmetricKey
loadParametersFormat(string $type, string|array $key)

Loads parameters

static mixed
validatePlugin(string $format, string $type, string $method = NULL)

Validate Plugin

static array
getSupportedKeyFormats()

Returns a list of supported formats.

static bool
addFileFormat(string $fullname)

Add a fileformat plugin

mixed
getLoadedFormat()

Returns the format of the loaded key.

null|string
getComment()

Returns the key's comment

static 
useBestEngine()

Tests engine validity

static 
useInternalEngine()

Flag to use internal engine only (useful for unit testing)

string
__toString()

__toString() magic method

withHash(string $hash)

Determines which hashing function should be used

getHash()

Returns the hash algorithm currently being used

string
computek(string $h1)

Compute the pseudorandom k for signature generation, using the process specified for deterministic DSA.

bits2int(string $in)

Bit String to Integer

static 
setExponent(int $val)

Sets the public exponent for key generation

static 
setSmallestPrime(int $val)

Sets the smallest prime number in bits. Used for key generation

static 
setOpenSSLConfigPath(string $val)

Sets the OpenSSL config file path

static RSA
createKey(int $bits = 2048)

Create a private key

static bool
onLoad(array $components)

OnLoad Handler

bool|string
i2osp(bool|BigInteger $x, int $xLen)

Integer-to-Octet-String primitive

os2ip(string $x)

Octet-String-to-Integer primitive

string
emsa_pkcs1_v1_5_encode(string $m, int $emLen)

EMSA-PKCS1-V1_5-ENCODE

string
emsa_pkcs1_v1_5_encode_without_null(string $m, int $emLen)

EMSA-PKCS1-V1_5-ENCODE (without NULL)

string
mgf1(string $mgfSeed, int $maskLen)

MGF1

int
getLength()

Returns the key size

withMGFHash(string $hash)

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

getMGFHash()

Returns the MGF hash algorithm currently being used

withSaltLength(int $sLen)

Determines the salt length

getSaltLength()

Returns the salt length currently being used

withLabel(string $label)

Determines the label

getLabel()

Returns the label currently being used

withPadding(int $padding)

Determines the padding modes

getPadding()

Returns the padding currently being used

string
getEngine()

Returns the current engine being used

static 
enableBlinding()

Enable RSA Blinding

static 
disableBlinding()

Disable RSA Blinding

Details

protected __construct()

Constructor

PublicKey and PrivateKey objects can only be created from abstract RSA class

static protected initialize_static_variables()

Initialize static variables

static AsymmetricKey load(string $key, string $password = false)

Load the key

Parameters

string $key
string $password optional

Return Value

AsymmetricKey

PrivateKey loadPrivateKey(string|array $key, string $password = '')

Loads a private key

Parameters

string|array $key
string $password optional

Return Value

PrivateKey

PublicKey loadPublicKey(string|array $key)

Loads a public key

Parameters

string|array $key

Return Value

PublicKey

AsymmetricKey loadParameters(string|array $key)

Loads parameters

Parameters

string|array $key

Return Value

AsymmetricKey

static AsymmetricKey loadFormat(string $type, string $key, string $password = false)

Load the key, assuming a specific format

Parameters

string $type
string $key
string $password optional

Return Value

AsymmetricKey

PrivateKey loadPrivateKeyFormat(string $type, string $key, string $password = false)

Loads a private key

Parameters

string $type
string $key
string $password optional

Return Value

PrivateKey

PublicKey loadPublicKeyFormat(string $type, string $key)

Loads a public key

Parameters

string $type
string $key

Return Value

PublicKey

AsymmetricKey loadParametersFormat(string $type, string|array $key)

Loads parameters

Parameters

string $type
string|array $key

Return Value

AsymmetricKey

static protected mixed validatePlugin(string $format, string $type, string $method = NULL)

Validate Plugin

Parameters

string $format
string $type
string $method optional

Return Value

mixed

static array getSupportedKeyFormats()

Returns a list of supported formats.

Return Value

array

static bool addFileFormat(string $fullname)

Add a fileformat plugin

The plugin needs to either already be loaded or be auto-loadable. Loading a plugin whose shortname overwrite an existing shortname will overwrite the old plugin.

Parameters

string $fullname

Return Value

bool

See also

\self::load()

mixed getLoadedFormat()

Returns the format of the loaded key.

If the key that was loaded wasn't in a valid or if the key was auto-generated with RSA::createKey() then this will throw an exception.

Return Value

mixed

See also

\self::load()

null|string getComment()

Returns the key's comment

Not all key formats support comments. If you want to set a comment use toString()

Return Value

null|string

static useBestEngine()

Tests engine validity

static useInternalEngine()

Flag to use internal engine only (useful for unit testing)

string __toString()

__toString() magic method

Return Value

string

withHash(string $hash)

Determines which hashing function should be used

Used with signature production / verification and (if the encryption mode is self::PADDING_OAEP) encryption and decryption.

Parameters

string $hash

getHash()

Returns the hash algorithm currently being used

protected string computek(string $h1)

Compute the pseudorandom k for signature generation, using the process specified for deterministic DSA.

Parameters

string $h1

Return Value

string

protected BigInteger bits2int(string $in)

Bit String to Integer

Parameters

string $in

Return Value

BigInteger

static setExponent(int $val)

Sets the public exponent for key generation

This will be 65537 unless changed.

Parameters

int $val

static setSmallestPrime(int $val)

Sets the smallest prime number in bits. Used for key generation

This will be 4096 unless changed.

Parameters

int $val

static setOpenSSLConfigPath(string $val)

Sets the OpenSSL config file path

Set to the empty string to use the default config file

Parameters

string $val

static RSA createKey(int $bits = 2048)

Create a private key

The public key can be extracted from the private key

Parameters

int $bits

Return Value

RSA

static protected bool onLoad(array $components)

OnLoad Handler

Parameters

array $components

Return Value

bool

protected bool|string i2osp(bool|BigInteger $x, int $xLen)

Integer-to-Octet-String primitive

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

Parameters

bool|BigInteger $x
int $xLen

Return Value

bool|string

protected BigInteger os2ip(string $x)

Octet-String-to-Integer primitive

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

Parameters

string $x

Return Value

BigInteger

protected string emsa_pkcs1_v1_5_encode(string $m, int $emLen)

EMSA-PKCS1-V1_5-ENCODE

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

Parameters

string $m
int $emLen

Return Value

string

Exceptions

LengthException if the intended encoded message length is too short

protected string emsa_pkcs1_v1_5_encode_without_null(string $m, int $emLen)

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"

Parameters

string $m
int $emLen

Return Value

string

protected string mgf1(string $mgfSeed, int $maskLen)

MGF1

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

Parameters

string $mgfSeed
int $maskLen

Return Value

string

int getLength()

Returns the key size

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

Return Value

int

withMGFHash(string $hash)

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

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

Parameters

string $hash

getMGFHash()

Returns the MGF hash algorithm currently being used

withSaltLength(int $sLen)

Determines the salt length

Used by RSA::PADDING_PSS

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.

Parameters

int $sLen

getSaltLength()

Returns the salt length currently being used

withLabel(string $label)

Determines the label

Used by RSA::PADDING_OAEP

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.

Parameters

string $label

getLabel()

Returns the label currently being used

withPadding(int $padding)

Determines the padding modes

Example: $key->withPadding(RSA::ENCRYPTION_PKCS1 | RSA::SIGNATURE_PKCS1);

Parameters

int $padding

getPadding()

Returns the padding currently being used

string getEngine()

Returns the current engine being used

OpenSSL is only used in this class (and it's subclasses) for key generation Even then it depends on the parameters you're using. It's not used for multi-prime RSA nor is it used if the key length is outside of the range supported by OpenSSL

Return Value

string

See also

\self::useInternalEngine()
\self::useBestEngine()

static enableBlinding()

Enable RSA Blinding

static disableBlinding()

Disable RSA Blinding