Documentation

PublicKey extends RSA
in package
implements PublicKey uses Fingerprint

Raw RSA Key Handler

Tags
author

Jim Wigginton terrafrost@php.net

access

public

Table of Contents

Interfaces

PublicKey
PublicKey interface

Constants

ALGORITHM  = 'RSA'
Algorithm Name
ENCRYPTION_NONE  = 4
Do not use any padding
ENCRYPTION_OAEP  = 1
Use {@link http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding Optimal Asymmetric Encryption Padding} (OAEP) for encryption / decryption.
ENCRYPTION_PKCS1  = 2
Use PKCS#1 padding.
SIGNATURE_PKCS1  = 64
Use PKCS#1 padding for signature verification
SIGNATURE_PSS  = 16
Use the Probabilistic Signature Scheme for signing
SIGNATURE_RELAXED_PKCS1  = 32
Use a relaxed version of PKCS#1 padding for signature verification

Properties

$configFile  : string|null
OpenSSL configuration file name.
$enableBlinding  : bool
Enable Blinding?
$encryptionPadding  : int
Encryption padding mode
$engines  : array<string|int, bool>
Available Engines
$exponent  : BigInteger
Exponent (ie. e or d)
$format  : string
Format of the loaded key
$hash  : Hash
Hash function
$hLen  : int
Length of hash function output
$k  : BigInteger
Modulus length
$label  : string
Label
$mgfHash  : Hash
Hash function for the Mask Generation Function
$mgfHLen  : int
Length of MGF hash function output
$modulus  : BigInteger
Modulus (ie. n)
$one  : BigInteger
Precomputed One
$signaturePadding  : int
Signature padding mode
$sLen  : int
Length of salt
$zero  : BigInteger
Precomputed Zero
$comment  : null|string
Key Comment
$defaultExponent  : int
Default public exponent
$hmac  : Hash
HMAC function
$invisiblePlugins  : array<string|int, mixed>
Invisible plugins
$plugins  : array<string|int, mixed>
Supported plugins (lower case)
$signatureFileFormats  : array<string|int, mixed>
Supported signature formats (original case)
$signatureFormats  : array<string|int, mixed>
Supported signature formats (lower case)
$smallestPrime  : int
Smallest Prime

Methods

__toString()  : string
__toString() magic method
addFileFormat()  : bool
Add a fileformat plugin
asPrivateKey()  : RSA
Converts a public key to a private key
createKey()  : RSA
Create a private key
disableBlinding()  : mixed
Disable RSA Blinding
enableBlinding()  : mixed
Enable RSA Blinding
encrypt()  : bool|string
Encryption
getComment()  : null|string
Returns the key's comment
getEngine()  : string
Returns the current engine being used
getFingerprint()  : mixed
Returns the public key's fingerprint
getHash()  : mixed
Returns the hash algorithm currently being used
getLabel()  : mixed
Returns the label currently being used
getLength()  : int
Returns the key size
getLoadedFormat()  : mixed
Returns the format of the loaded key.
getMGFHash()  : mixed
Returns the MGF hash algorithm currently being used
getPadding()  : mixed
Returns the padding currently being used
getSaltLength()  : mixed
Returns the salt length currently being used
getSupportedKeyFormats()  : array<string|int, mixed>
Returns a list of supported formats.
load()  : AsymmetricKey
Load the key
loadFormat()  : AsymmetricKey
Load the key, assuming a specific format
loadParameters()  : AsymmetricKey
Loads parameters
loadParametersFormat()  : AsymmetricKey
Loads parameters
loadPrivateKey()  : PrivateKey
Loads a private key
loadPrivateKeyFormat()  : PrivateKey
Loads a private key
loadPublicKey()  : PublicKey
Loads a public key
loadPublicKeyFormat()  : PublicKey
Loads a public key
setExponent()  : mixed
Sets the public exponent for key generation
setOpenSSLConfigPath()  : mixed
Sets the OpenSSL config file path
setSmallestPrime()  : mixed
Sets the smallest prime number in bits. Used for key generation
toString()  : mixed
Returns the public key
useBestEngine()  : mixed
Tests engine validity
useInternalEngine()  : mixed
Flag to use internal engine only (useful for unit testing)
verify()  : bool
Verifies a signature
withHash()  : mixed
Determines which hashing function should be used
withLabel()  : mixed
Determines the label
withMGFHash()  : mixed
Determines which hashing function should be used for the mask generation function
withPadding()  : mixed
Determines the padding modes
withSaltLength()  : mixed
Determines the salt length
__construct()  : mixed
Constructor
bits2int()  : BigInteger
Bit String to Integer
computek()  : string
Compute the pseudorandom k for signature generation, using the process specified for deterministic DSA.
emsa_pkcs1_v1_5_encode()  : string
EMSA-PKCS1-V1_5-ENCODE
emsa_pkcs1_v1_5_encode_without_null()  : string
EMSA-PKCS1-V1_5-ENCODE (without NULL)
i2osp()  : bool|string
Integer-to-Octet-String primitive
initialize_static_variables()  : mixed
Initialize static variables
mgf1()  : string
MGF1
onLoad()  : bool
OnLoad Handler
os2ip()  : BigInteger
Octet-String-to-Integer primitive
validatePlugin()  : mixed
Validate Plugin
bits2octets()  : string
Bit String to Octet String
emsa_pss_verify()  : string
EMSA-PSS-VERIFY
exponentiate()  : BigInteger
Exponentiate
int2octets()  : string
Integer to Octet String
loadPlugins()  : mixed
Load Plugins
raw_encrypt()  : bool|string
Raw Encryption / Decryption
rsaep()  : bool|BigInteger
RSAEP
rsaes_oaep_encrypt()  : string
RSAES-OAEP-ENCRYPT
rsaes_pkcs1_v1_5_encrypt()  : bool|string
RSAES-PKCS1-V1_5-ENCRYPT
rsassa_pkcs1_v1_5_relaxed_verify()  : bool
RSASSA-PKCS1-V1_5-VERIFY (relaxed matching)
rsassa_pkcs1_v1_5_verify()  : bool
RSASSA-PKCS1-V1_5-VERIFY
rsassa_pss_verify()  : bool|string
RSASSA-PSS-VERIFY
rsavp1()  : bool|BigInteger
RSAVP1

Constants

ALGORITHM

Algorithm Name

public string ALGORITHM = 'RSA'
Tags
access

private

ENCRYPTION_NONE

Do not use any padding

public mixed ENCRYPTION_NONE = 4

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.

Tags
access

public

see
self::encrypt()
see
self::decrypt()

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 sha256 by default

Tags
see
self::setHash()
see
self::setMGFHash()
see
self::encrypt()
see
self::decrypt()
access

public

ENCRYPTION_PKCS1

Use PKCS#1 padding.

public mixed ENCRYPTION_PKCS1 = 2

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.

Tags
access

public

see
self::encrypt()
see
self::decrypt()

SIGNATURE_PKCS1

Use PKCS#1 padding for signature verification

public mixed SIGNATURE_PKCS1 = 64
Tags
see
self::sign()
see
self::verify()
see
self::setHash()
access

public

SIGNATURE_PSS

Use the Probabilistic Signature Scheme for signing

public mixed SIGNATURE_PSS = 16

Uses sha256 and 0 as the salt length

Tags
see
self::setSaltLength()
see
self::setMGFHash()
see
self::setHash()
see
self::sign()
see
self::verify()
see
self::setHash()
access

public

SIGNATURE_RELAXED_PKCS1

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

public mixed SIGNATURE_RELAXED_PKCS1 = 32
Tags
see
self::sign()
see
self::verify()
see
self::setHash()
access

public

Properties

$configFile

OpenSSL configuration file name.

protected static string|null $configFile
Tags
see
self::createKey()

$enableBlinding

Enable Blinding?

protected static bool $enableBlinding = true
Tags
access

private

$encryptionPadding

Encryption padding mode

protected int $encryptionPadding = self::ENCRYPTION_OAEP
Tags
access

private

$engines

Available Engines

protected static array<string|int, bool> $engines = []
Tags
access

private

$exponent

Exponent (ie. e or d)

protected BigInteger $exponent
Tags
access

private

$format

Format of the loaded key

protected string $format
Tags
access

private

$hLen

Length of hash function output

protected int $hLen
Tags
access

private

$label

Label

protected string $label = ''
Tags
access

private

$mgfHash

Hash function for the Mask Generation Function

protected Hash $mgfHash
Tags
access

private

$mgfHLen

Length of MGF hash function output

protected int $mgfHLen
Tags
access

private

$modulus

Modulus (ie. n)

protected BigInteger $modulus
Tags
access

private

$signaturePadding

Signature padding mode

protected int $signaturePadding = self::SIGNATURE_PSS
Tags
access

private

$sLen

Length of salt

protected int $sLen
Tags
access

private

$comment

Key Comment

private null|string $comment
Tags
access

private

$invisiblePlugins

Invisible plugins

private static array<string|int, mixed> $invisiblePlugins = []
Tags
see
self::initialize_static_variables()
access

private

$plugins

Supported plugins (lower case)

private static array<string|int, mixed> $plugins = []
Tags
see
self::initialize_static_variables()
access

private

$signatureFileFormats

Supported signature formats (original case)

private static array<string|int, mixed> $signatureFileFormats = []
Tags
see
self::initialize_static_variables()
access

private

$signatureFormats

Supported signature formats (lower case)

private static array<string|int, mixed> $signatureFormats = []
Tags
see
self::initialize_static_variables()
access

private

$smallestPrime

Smallest Prime

private static int $smallestPrime = 4096

Per http://cseweb.ucsd.edu/~hovav/dist/survey.pdf#page=5, this number ought not result in primes smaller than 256 bits. As a consequence if the key you're trying to create is 1024 bits and you've set smallestPrime to 384 bits then you're going to get a 384 bit prime and a 640 bit prime (384 + 1024 % 384). At least if engine is set to self::ENGINE_INTERNAL. If Engine is set to self::ENGINE_OPENSSL then smallest Prime is ignored (ie. multi-prime RSA support is more intended as a way to speed up RSA key generation when there's a chance neither gmp nor OpenSSL are installed)

Tags
access

private

Methods

__toString()

__toString() magic method

public __toString() : string
Return values
string

addFileFormat()

Add a fileformat plugin

public static addFileFormat(string $fullname) : bool

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
$fullname : string
Tags
see
self::load()
access

public

Return values
bool

asPrivateKey()

Converts a public key to a private key

public asPrivateKey() : RSA
Return values
RSA

createKey()

Create a private key

public static createKey([int $bits = 2048 ]) : RSA

The public key can be extracted from the private key

Parameters
$bits : int = 2048
Tags
access

public

Return values
RSA

disableBlinding()

Disable RSA Blinding

public static disableBlinding() : mixed
Tags
access

public

enableBlinding()

Enable RSA Blinding

public static enableBlinding() : mixed
Tags
access

public

encrypt()

Encryption

public encrypt(string $plaintext) : bool|string

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
$plaintext : string
Tags
see
self::decrypt()
access

public

throws
LengthException

if the RSA modulus is too short

Return values
bool|string

getComment()

Returns the key's comment

public getComment() : null|string

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

Tags
access

public

Return values
null|string

getEngine()

Returns the current engine being used

public getEngine() : string

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

Tags
see
self::useInternalEngine()
see
self::useBestEngine()
access

public

Return values
string

getFingerprint()

Returns the public key's fingerprint

public getFingerprint([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.

Tags
access

public

getHash()

Returns the hash algorithm currently being used

public getHash() : mixed
Tags
access

public

getLabel()

Returns the label currently being used

public getLabel() : mixed
Tags
access

public

getLength()

Returns the key size

public getLength() : int

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

Tags
access

public

Return values
int

getLoadedFormat()

Returns the format of the loaded key.

public getLoadedFormat() : mixed

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.

Tags
see
self::load()
access

public

getMGFHash()

Returns the MGF hash algorithm currently being used

public getMGFHash() : mixed
Tags
access

public

getPadding()

Returns the padding currently being used

public getPadding() : mixed
Tags
access

public

getSaltLength()

Returns the salt length currently being used

public getSaltLength() : mixed
Tags
access

public

getSupportedKeyFormats()

Returns a list of supported formats.

public static getSupportedKeyFormats() : array<string|int, mixed>
Tags
access

public

Return values
array<string|int, mixed>

loadFormat()

Load the key, assuming a specific format

public static loadFormat(string $type, string $key[, string $password = false ]) : AsymmetricKey
Parameters
$type : string
$key : string
$password : string = false

optional

Return values
AsymmetricKey

loadParameters()

Loads parameters

public loadParameters(string|array<string|int, mixed> $key) : AsymmetricKey
Parameters
$key : string|array<string|int, mixed>
Tags
access

public

Return values
AsymmetricKey

loadParametersFormat()

Loads parameters

public loadParametersFormat(string $type, string|array<string|int, mixed> $key) : AsymmetricKey
Parameters
$type : string
$key : string|array<string|int, mixed>
Tags
access

public

Return values
AsymmetricKey

loadPrivateKey()

Loads a private key

public loadPrivateKey(string|array<string|int, mixed> $key[, string $password = '' ]) : PrivateKey
Parameters
$key : string|array<string|int, mixed>
$password : string = ''

optional

Tags
access

public

Return values
PrivateKey

loadPrivateKeyFormat()

Loads a private key

public loadPrivateKeyFormat(string $type, string $key[, string $password = false ]) : PrivateKey
Parameters
$type : string
$key : string
$password : string = false

optional

Tags
access

public

Return values
PrivateKey

loadPublicKey()

Loads a public key

public loadPublicKey(string|array<string|int, mixed> $key) : PublicKey
Parameters
$key : string|array<string|int, mixed>
Tags
access

public

Return values
PublicKey

loadPublicKeyFormat()

Loads a public key

public loadPublicKeyFormat(string $type, string $key) : PublicKey
Parameters
$type : string
$key : string
Tags
access

public

Return values
PublicKey

setExponent()

Sets the public exponent for key generation

public static setExponent(int $val) : mixed

This will be 65537 unless changed.

Parameters
$val : int
Tags
access

public

setOpenSSLConfigPath()

Sets the OpenSSL config file path

public static setOpenSSLConfigPath(string $val) : mixed

Set to the empty string to use the default config file

Parameters
$val : string
Tags
access

public

setSmallestPrime()

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

public static setSmallestPrime(int $val) : mixed

This will be 4096 unless changed.

Parameters
$val : int
Tags
access

public

toString()

Returns the public key

public toString(string $type[, array<string|int, mixed> $options = [] ]) : 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 : string
$options : array<string|int, mixed> = []

optional

useBestEngine()

Tests engine validity

public static useBestEngine() : mixed
Tags
access

public

useInternalEngine()

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

public static useInternalEngine() : mixed
Tags
access

public

verify()

Verifies a signature

public verify(string $message, string $signature) : bool
Parameters
$message : string
$signature : string
Tags
see
self::sign()
Return values
bool

withHash()

Determines which hashing function should be used

public withHash(string $hash) : mixed

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

Parameters
$hash : string
Tags
access

public

withLabel()

Determines the label

public withLabel(string $label) : mixed

Used by RSA::PADDING_OAEP

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
$label : string
Tags
access

public

withMGFHash()

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

public withMGFHash(string $hash) : mixed

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
$hash : string
Tags
access

public

withPadding()

Determines the padding modes

public withPadding(int $padding) : mixed

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

Parameters
$padding : int
Tags
access

public

withSaltLength()

Determines the salt length

public withSaltLength(int $sLen) : mixed

Used by RSA::PADDING_PSS

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 : int
Tags
access

public

__construct()

Constructor

protected __construct() : mixed

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

computek()

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

protected computek(string $h1) : string
Parameters
$h1 : string
Tags
access

public

Return values
string

emsa_pkcs1_v1_5_encode()

EMSA-PKCS1-V1_5-ENCODE

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

See RFC3447#section-9.2.

Parameters
$m : string
$emLen : int
Tags
access

private

throws
LengthException

if the intended encoded message length is too short

Return values
string

emsa_pkcs1_v1_5_encode_without_null()

EMSA-PKCS1-V1_5-ENCODE (without NULL)

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

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
$m : string
$emLen : int
Tags
access

private

Return values
string

i2osp()

Integer-to-Octet-String primitive

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

See RFC3447#section-4.1.

Parameters
$x : bool|BigInteger
$xLen : int
Tags
access

private

Return values
bool|string

initialize_static_variables()

Initialize static variables

protected static initialize_static_variables() : mixed

mgf1()

MGF1

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

See RFC3447#appendix-B.2.1.

Parameters
$mgfSeed : string
$maskLen : int
Tags
access

private

Return values
string

onLoad()

OnLoad Handler

protected static onLoad(array<string|int, mixed> $components) : bool
Parameters
$components : array<string|int, mixed>
Tags
access

protected

Return values
bool

validatePlugin()

Validate Plugin

protected static validatePlugin(string $format, string $type[, string $method = NULL ]) : mixed
Parameters
$format : string
$type : string
$method : string = NULL

optional

Tags
access

private

bits2octets()

Bit String to Octet String

private bits2octets(string $in) : string
Parameters
$in : string
Tags
access

private

Return values
string

emsa_pss_verify()

EMSA-PSS-VERIFY

private emsa_pss_verify(string $m, string $em, int $emBits) : string

See RFC3447#section-9.1.2.

Parameters
$m : string
$em : string
$emBits : int
Tags
access

private

Return values
string

loadPlugins()

Load Plugins

private static loadPlugins(string $format) : mixed
Parameters
$format : string
Tags
access

private

raw_encrypt()

Raw Encryption / Decryption

private raw_encrypt(string $m) : bool|string

Doesn't use padding and is not recommended.

Parameters
$m : string
Tags
access

private

throws
LengthException

if strlen($m) > $this->k

Return values
bool|string

rsaes_oaep_encrypt()

RSAES-OAEP-ENCRYPT

private rsaes_oaep_encrypt(string $m) : string

See RFC3447#section-7.1.1 and {http://en.wikipedia.org/wiki/Optimal_Asymmetric_Encryption_Padding OAES}.

Parameters
$m : string
Tags
access

private

throws
LengthException

if strlen($m) > $this->k - 2 * $this->hLen - 2

Return values
string

rsaes_pkcs1_v1_5_encrypt()

RSAES-PKCS1-V1_5-ENCRYPT

private rsaes_pkcs1_v1_5_encrypt(string $m[, bool $pkcs15_compat = false ]) : bool|string

See RFC3447#section-7.2.1.

Parameters
$m : string
$pkcs15_compat : bool = false

optional

Tags
access

private

throws
LengthException

if strlen($m) > $this->k - 11

Return values
bool|string

rsassa_pkcs1_v1_5_relaxed_verify()

RSASSA-PKCS1-V1_5-VERIFY (relaxed matching)

private rsassa_pkcs1_v1_5_relaxed_verify(string $m, string $s) : bool

Per RFC3447#page-43 PKCS1 v1.5 specified the use BER encoding rather than DER encoding that PKCS1 v2.0 specified. This means that under rare conditions you can have a perfectly valid v1.5 signature that fails to validate with _rsassa_pkcs1_v1_5_verify(). PKCS1 v2.1 also recommends that if you're going to validate these types of signatures you "should indicate whether the underlying BER encoding is a DER encoding and hence whether the signature is valid with respect to the specification given in [PKCS1 v2.0+]". so if you do $rsa->getLastPadding() and get RSA::PADDING_RELAXED_PKCS1 back instead of RSA::PADDING_PKCS1... that means BER encoding was used.

Parameters
$m : string
$s : string
Tags
access

private

Return values
bool

rsassa_pkcs1_v1_5_verify()

RSASSA-PKCS1-V1_5-VERIFY

private rsassa_pkcs1_v1_5_verify(string $m, string $s) : bool

See RFC3447#section-8.2.2.

Parameters
$m : string
$s : string
Tags
access

private

throws
LengthException

if the RSA modulus is too short

Return values
bool

rsassa_pss_verify()

RSASSA-PSS-VERIFY

private rsassa_pss_verify(string $m, string $s) : bool|string

See RFC3447#section-8.1.2.

Parameters
$m : string
$s : string
Tags
access

private

Return values
bool|string

        
On this page

Search results