class PublicKey extends RSA implements PublicKey (View source)

Raw RSA Key Handler

Traits

Fingerprint Trait for Private Keys

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 from  RSA
protected int $signaturePadding Signature padding mode from  RSA
protected int $hLen Length of hash function output from  RSA
protected int $sLen Length of salt from  RSA
protected string $label Label from  RSA
protected Hash $mgfHash Hash function for the Mask Generation Function from  RSA
protected int $mgfHLen Length of MGF hash function output from  RSA
protected BigInteger $modulus Modulus (ie. n) from  RSA
protected BigInteger $k Modulus length from  RSA
protected BigInteger $exponent Exponent (ie. e or d) from  RSA
static protected bool $enableBlinding Enable Blinding? from  RSA
static protected ?string $configFile OpenSSL configuration file name. from  RSA

Methods

__construct()

Constructor

from  RSA
static 
initialize_static_variables()

Initialize static variables

from  RSA
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

from  RSA
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

from  RSA
static 
setSmallestPrime(int $val)

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

from  RSA
static 
setOpenSSLConfigPath(string $val)

Sets the OpenSSL config file path

from  RSA
static RSA
createKey(int $bits = 2048)

Create a private key

from  RSA
static bool
onLoad(array $components)

OnLoad Handler

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

Integer-to-Octet-String primitive

from  RSA
os2ip(string $x)

Octet-String-to-Integer primitive

from  RSA
string
emsa_pkcs1_v1_5_encode(string $m, int $emLen)

EMSA-PKCS1-V1_5-ENCODE

from  RSA
string
emsa_pkcs1_v1_5_encode_without_null(string $m, int $emLen)

EMSA-PKCS1-V1_5-ENCODE (without NULL)

from  RSA
string
mgf1(string $mgfSeed, int $maskLen)

MGF1

from  RSA
int
getLength()

Returns the key size

from  RSA
withMGFHash(string $hash)

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

from  RSA
getMGFHash()

Returns the MGF hash algorithm currently being used

from  RSA
withSaltLength(int $sLen)

Determines the salt length

from  RSA
getSaltLength()

Returns the salt length currently being used

from  RSA
withLabel(string $label)

Determines the label

from  RSA
getLabel()

Returns the label currently being used

from  RSA
withPadding(int $padding)

Determines the padding modes

from  RSA
getPadding()

Returns the padding currently being used

from  RSA
string
getEngine()

Returns the current engine being used

from  RSA
static 
enableBlinding()

Enable RSA Blinding

from  RSA
static 
disableBlinding()

Disable RSA Blinding

from  RSA
mixed
getFingerprint(string $algorithm = 'md5')

Returns the public key's fingerprint

verify($message, $signature)

Verifies a signature

bool|string
encrypt(string $plaintext)

Encryption

toString($type, array $options = [])

Returns the public key

RSA
asPrivateKey()

Converts a public key to a private key

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

mixed getFingerprint(string $algorithm = 'md5')

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)

Parameters

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

Return Value

mixed

verify($message, $signature)

Verifies a signature

Parameters

$message
$signature

See also

\self::sign()

bool|string encrypt(string $plaintext)

Encryption

Both self::PADDING_OAEP and self::PADDING_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

string $plaintext

Return Value

bool|string

Exceptions

LengthException if the RSA modulus is too short

See also

\self::decrypt()

toString($type, array $options = [])

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.

Parameters

$type
array $options

RSA asPrivateKey()

Converts a public key to a private key

Return Value

RSA