Documentation

RSA extends AsymmetricKey
in package

AbstractYes

Pure-PHP PKCS#1 compliant implementation of RSA.

Tags
author

Jim Wigginton terrafrost@php.net

access

public

Table of Contents

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
createKey()  : RSA
Create a private key
disableBlinding()  : mixed
Disable RSA Blinding
enableBlinding()  : mixed
Enable RSA Blinding
getComment()  : null|string
Returns the key's comment
getEngine()  : string
Returns the current engine being used
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
useBestEngine()  : mixed
Tests engine validity
useInternalEngine()  : mixed
Flag to use internal engine only (useful for unit testing)
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
int2octets()  : string
Integer to Octet String
loadPlugins()  : mixed
Load Plugins

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

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

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

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

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

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

loadPlugins()

Load Plugins

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

private


        
On this page

Search results