Documentation

PublicKey extends RSA
in package

RSA

implements PublicKey uses Fingerprint

Raw RSA Key Handler

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

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

$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

$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

$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
     = []

$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

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

Return values

RSA

disableBlinding()

Disable RSA Blinding


    public
            static        disableBlinding() : mixed

enableBlinding()

Enable RSA Blinding


    public
            static        enableBlinding() : mixed

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

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

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

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.

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

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

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

useInternalEngine()

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


    public
            static        useInternalEngine() : mixed

verify()

Verifies a signature


    public
                    verify(string $message, string $signature) : bool

Parameters

$message : string
$signature : string

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

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

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

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

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

Return values

string

exponentiate()

Exponentiate


    private
                    exponentiate(BigInteger $x) : BigInteger

Parameters

$x : BigInteger

Return values

BigInteger

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

rsaep()

RSAEP


    private
                    rsaep(BigInteger $m) : bool|BigInteger

See RFC3447#section-5.1.1.

Parameters

$m : BigInteger

Return values

bool|BigInteger

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

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

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

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

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

Return values

bool|string

rsavp1()

RSAVP1


    private
                    rsavp1(BigInteger $s) : bool|BigInteger

See RFC3447#section-5.2.2.

Parameters

$s : BigInteger

Return values

bool|BigInteger

PublicKey extends RSA in package RSA implements PublicKey uses Fingerprint

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

$configFile

Tags

$enableBlinding

Tags

$encryptionPadding

Tags

$engines

Tags

$exponent

Tags

$format

Tags

$hash

Tags

$hLen

Tags

$k

Tags

$label

Tags

$mgfHash

Tags

$mgfHLen

Tags

$modulus

Tags

$one

Tags

$signaturePadding

Tags

$sLen

Tags

$zero

Tags

$comment

Tags

$defaultExponent

Tags

$hmac

Tags

$invisiblePlugins

PublicKey extends RSA
in package

RSA

implements PublicKey uses Fingerprint