Documentation

PrivateKey extends RSA
in package

RSA

implements PrivateKey uses PasswordProtected

Raw RSA Key Handler

Interfaces

PrivateKey: PrivateKey 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

$coefficients : array<string|int, mixed>: Coefficients for Chinese Remainder Theorem (ie. qInv)
$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)
$exponents : array<string|int, mixed>: Exponents for Chinese Remainder Theorem (ie. dP and dQ)
$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
$primes : array<string|int, mixed>: Primes for Chinese Remainder Theorem (ie. p and q)
$publicExponent : mixed: Public Exponent
$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
$password : string|bool: Password
$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
decrypt() : bool|string: Decryption
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
getPublicKey() : mixed: Returns the public key
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
sign() : string: Create a signature
toString() : string: Returns the private key
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
withPassword() : mixed: Sets the password
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)
exponentiate() : BigInteger: Exponentiate
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
blind() : BigInteger: Performs RSA Blinding
emsa_pss_encode() : string: EMSA-PSS-ENCODE
int2octets() : string: Integer to Octet String
loadPlugins() : mixed: Load Plugins
raw_encrypt() : bool|string: Raw Encryption / Decryption
rsadp() : bool|BigInteger: RSADP
rsaes_oaep_decrypt() : bool|string: RSAES-OAEP-DECRYPT
rsaes_pkcs1_v1_5_decrypt() : bool|string: RSAES-PKCS1-V1_5-DECRYPT
rsasp1() : bool|BigInteger: RSASP1
rsassa_pkcs1_v1_5_sign() : bool|string: RSASSA-PKCS1-V1_5-SIGN
rsassa_pss_sign() : bool|string: RSASSA-PSS-SIGN

ALGORITHM

Algorithm Name


    public
        string
    ALGORITHM
    = 'RSA'

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.

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

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.

SIGNATURE_PKCS1

Use PKCS#1 padding for signature verification


    public
        mixed
    SIGNATURE_PKCS1
    = 64

SIGNATURE_PSS

Use the Probabilistic Signature Scheme for signing


    public
        mixed
    SIGNATURE_PSS
    = 16

Uses sha256 and 0 as the salt length

SIGNATURE_RELAXED_PKCS1

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


    public
        mixed
    SIGNATURE_RELAXED_PKCS1
    = 32

$coefficients

Coefficients for Chinese Remainder Theorem (ie. qInv)


    protected
        array<string|int, mixed>
    $coefficients

$configFile

OpenSSL configuration file name.


    protected
    static    string|null
    $configFile

$enableBlinding

Enable Blinding?


    protected
    static    bool
    $enableBlinding
     = true

$encryptionPadding

Encryption padding mode


    protected
        int
    $encryptionPadding
     = self::ENCRYPTION_OAEP

$engines

Available Engines


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

$exponent

Exponent (ie. e or d)


    protected
        BigInteger
    $exponent

$exponents

Exponents for Chinese Remainder Theorem (ie. dP and dQ)


    protected
        array<string|int, mixed>
    $exponents

$format

Format of the loaded key


    protected
        string
    $format

$hash

Hash function


    protected
        Hash
    $hash

$hLen

Length of hash function output


    protected
        int
    $hLen

$k

Modulus length


    protected
        BigInteger
    $k

$label

Label


    protected
        string
    $label
     = ''

$mgfHash

Hash function for the Mask Generation Function


    protected
        Hash
    $mgfHash

$mgfHLen

Length of MGF hash function output


    protected
        int
    $mgfHLen

$modulus

Modulus (ie. n)


    protected
        BigInteger
    $modulus

$one

Precomputed One


    protected
    static    BigInteger
    $one

$primes

Primes for Chinese Remainder Theorem (ie. p and q)


    protected
        array<string|int, mixed>
    $primes

$publicExponent

Public Exponent


    protected
        mixed
    $publicExponent
     = false

$signaturePadding

Signature padding mode


    protected
        int
    $signaturePadding
     = self::SIGNATURE_PSS

$sLen

Length of salt


    protected
        int
    $sLen

$zero

Precomputed Zero


    protected
    static    BigInteger
    $zero

$comment

Key Comment


    private
        null|string
    $comment

$defaultExponent

Default public exponent


    private
    static    int
    $defaultExponent
     = 65537

$hmac

HMAC function


    private
        Hash
    $hmac

$invisiblePlugins

Invisible plugins


    private
    static    array<string|int, mixed>
    $invisiblePlugins
     = []

$password

Password


    private
        string|bool
    $password
     = false

$plugins

Supported plugins (lower case)


    private
    static    array<string|int, mixed>
    $plugins
     = []

$signatureFileFormats

Supported signature formats (original case)


    private
    static    array<string|int, mixed>
    $signatureFileFormats
     = []

$signatureFormats

Supported signature formats (lower case)


    private
    static    array<string|int, mixed>
    $signatureFormats
     = []

$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)

__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

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

Return values

RSA

decrypt()

Decryption


    public
                    decrypt(string $ciphertext) : bool|string

Parameters

$ciphertext : string

Return values

bool|string

disableBlinding()

Disable RSA Blinding


    public
            static        disableBlinding() : mixed

enableBlinding()

Enable RSA Blinding


    public
            static        enableBlinding() : mixed

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()

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

Return values

string

getHash()

Returns the hash algorithm currently being used


    public
                    getHash() : mixed

getLabel()

Returns the label currently being used


    public
                    getLabel() : mixed

getLength()

Returns the key size


    public
                    getLength() : int

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

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.

getMGFHash()

Returns the MGF hash algorithm currently being used


    public
                    getMGFHash() : mixed

getPadding()

Returns the padding currently being used


    public
                    getPadding() : mixed

getPublicKey()

Returns the public key


    public
                    getPublicKey() : mixed

getSaltLength()

Returns the salt length currently being used


    public
                    getSaltLength() : mixed

getSupportedKeyFormats()

Returns a list of supported formats.


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

Return values

array<string|int, mixed>

load()

Load the key


    public
            static        load(string $key[, string $password = false ]) : AsymmetricKey

Parameters

$key : string
$password : string = false: optional

Return values

AsymmetricKey

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>

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>

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

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

Return values

PrivateKey

loadPublicKey()

Loads a public key


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

Parameters

$key : string|array<string|int, mixed>

Return values

PublicKey

loadPublicKeyFormat()

Loads a public key


    public
                    loadPublicKeyFormat(string $type, string $key) : PublicKey

Parameters

$type : string
$key : string

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

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

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

sign()

Create a signature


    public
                    sign(string $message) : string

Parameters

$message : string

Return values

string

toString()

Returns the private key


    public
                    toString(string $type[, array<string|int, mixed> $options = [] ]) : string

Parameters

$type : string
$options : array<string|int, mixed> = []: optional

Return values

string

useBestEngine()

Tests engine validity


    public
            static        useBestEngine() : mixed

useInternalEngine()

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


    public
            static        useInternalEngine() : mixed

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

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

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

withPadding()

Determines the padding modes


    public
                    withPadding(int $padding) : mixed

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

Parameters

$padding : int

withPassword()

Sets the password


    public
                    withPassword([string|bool $password = false ]) : mixed

Private keys can be encrypted with a password. To unset the password, pass in the empty string or false. Or rather, pass in $password such that empty($password) && !is_string($password) is true.

Parameters

$password : string|bool = false

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

__construct()

Constructor


    protected
                    __construct() : mixed

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

bits2int()

Bit String to Integer


    protected
                    bits2int(string $in) : BigInteger

Parameters

$in : string

Return values

BigInteger

computek()

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


    protected
                    computek(string $h1) : string

Parameters

$h1 : string

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

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

Return values

string

exponentiate()

Exponentiate


    protected
                    exponentiate(BigInteger $x) : BigInteger

Parameters

$x : BigInteger

Return values

BigInteger

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

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

Return values

string

onLoad()

OnLoad Handler


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

Parameters

$components : array<string|int, mixed>

Return values

bool

os2ip()

Octet-String-to-Integer primitive


    protected
                    os2ip(string $x) : BigInteger

See RFC3447#section-4.2.

Parameters

$x : string

Return values

BigInteger

validatePlugin()

Validate Plugin


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

Parameters

$format : string
$type : string
$method : string = NULL: optional

bits2octets()

Bit String to Octet String


    private
                    bits2octets(string $in) : string

Parameters

$in : string

Return values

string

blind()

Performs RSA Blinding


    private
                    blind(BigInteger $x, BigInteger $r, int $i) : BigInteger

Protects against timing attacks by employing RSA Blinding. Returns $x->modPow($this->exponents[$i], $this->primes[$i])

Parameters

$x : BigInteger
$r : BigInteger
$i : int

Return values

BigInteger

emsa_pss_encode()

EMSA-PSS-ENCODE


    private
                    emsa_pss_encode(string $m, int $emBits) : string

See RFC3447#section-9.1.1.

Parameters

$m : string
$emBits : int

Return values

string

int2octets()

Integer to Octet String


    private
                    int2octets(BigInteger $v) : string

Parameters

$v : BigInteger

Return values

string

loadPlugins()

Load Plugins


    private
            static        loadPlugins(string $format) : mixed

Parameters

$format : string

raw_encrypt()

Raw Encryption / Decryption


    private
                    raw_encrypt(string $m) : bool|string

Doesn't use padding and is not recommended.

Parameters

$m : string

Return values

bool|string

rsadp()

RSADP


    private
                    rsadp(BigInteger $c) : bool|BigInteger

See RFC3447#section-5.1.2.

Parameters

$c : BigInteger

Return values

bool|BigInteger

rsaes_oaep_decrypt()

RSAES-OAEP-DECRYPT


    private
                    rsaes_oaep_decrypt(string $c) : bool|string

See RFC3447#section-7.1.2. The fact that the error messages aren't distinguishable from one another hinders debugging, but, to quote from RFC3447#section-7.1.2:

Note. Care must be taken to ensure that an opponent cannot distinguish the different error conditions in Step 3.g, whether by error message or timing, or, more generally, learn partial information about the encoded message EM. Otherwise an opponent may be able to obtain useful information about the decryption of the ciphertext C, leading to a chosen-ciphertext attack such as the one observed by Manger [36].

Parameters

$c : string

Return values

bool|string

rsaes_pkcs1_v1_5_decrypt()

RSAES-PKCS1-V1_5-DECRYPT


    private
                    rsaes_pkcs1_v1_5_decrypt(string $c) : bool|string

See RFC3447#section-7.2.2.

Parameters

$c : string

Return values

bool|string

rsasp1()

RSASP1


    private
                    rsasp1(BigInteger $m) : bool|BigInteger

See RFC3447#section-5.2.1.

Parameters

$m : BigInteger

Return values

bool|BigInteger

rsassa_pkcs1_v1_5_sign()

RSASSA-PKCS1-V1_5-SIGN


    private
                    rsassa_pkcs1_v1_5_sign(string $m) : bool|string

See RFC3447#section-8.2.1.

Parameters

$m : string

Return values

bool|string

rsassa_pss_sign()

RSASSA-PSS-SIGN


    private
                    rsassa_pss_sign(string $m) : bool|string

See RFC3447#section-8.1.1.

Parameters

$m : string

Return values

bool|string

PrivateKey extends RSA in package RSA implements PrivateKey uses PasswordProtected

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

ALGORITHM

Tags

ENCRYPTION_NONE

Tags

ENCRYPTION_OAEP

Tags

ENCRYPTION_PKCS1

Tags

SIGNATURE_PKCS1

Tags

SIGNATURE_PSS

Tags

SIGNATURE_RELAXED_PKCS1

Tags

Properties

$coefficients

Tags

$configFile

Tags

$enableBlinding

Tags

$encryptionPadding

Tags

$engines

Tags

$exponent

Tags

$exponents

Tags

$format

Tags

$hash

Tags

$hLen

Tags

$k

Tags

$label

Tags

$mgfHash

Tags

$mgfHLen

Tags

$modulus

Tags

$one

Tags

$primes

Tags

$publicExponent

Tags

$signaturePadding

Tags

$sLen

Tags

$zero

PrivateKey extends RSA
in package

RSA

implements PrivateKey uses PasswordProtected