PublicKey
extends RSA
in package
implements
PublicKey
uses
Fingerprint
Raw RSA Key Handler
Tags
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
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
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
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
SIGNATURE_PKCS1
Use PKCS#1 padding for signature verification
public
mixed
SIGNATURE_PKCS1
= 64
Tags
SIGNATURE_PSS
Use the Probabilistic Signature Scheme for signing
public
mixed
SIGNATURE_PSS
= 16
Uses sha256 and 0 as the salt length
Tags
SIGNATURE_RELAXED_PKCS1
Use a relaxed version of PKCS#1 padding for signature verification
public
mixed
SIGNATURE_RELAXED_PKCS1
= 32
Tags
Properties
$configFile
OpenSSL configuration file name.
protected
static string|null
$configFile
Tags
$enableBlinding
Enable Blinding?
protected
static bool
$enableBlinding
= true
Tags
$encryptionPadding
Encryption padding mode
protected
int
$encryptionPadding
= self::ENCRYPTION_OAEP
Tags
$engines
Available Engines
protected
static array<string|int, bool>
$engines
= []
Tags
$exponent
Exponent (ie. e or d)
protected
BigInteger
$exponent
Tags
$format
Format of the loaded key
protected
string
$format
Tags
$hash
Hash function
protected
Hash
$hash
Tags
$hLen
Length of hash function output
protected
int
$hLen
Tags
$k
Modulus length
protected
BigInteger
$k
Tags
$label
Label
protected
string
$label
= ''
Tags
$mgfHash
Hash function for the Mask Generation Function
protected
Hash
$mgfHash
Tags
$mgfHLen
Length of MGF hash function output
protected
int
$mgfHLen
Tags
$modulus
Modulus (ie. n)
protected
BigInteger
$modulus
Tags
$one
Precomputed One
protected
static BigInteger
$one
Tags
$signaturePadding
Signature padding mode
protected
int
$signaturePadding
= self::SIGNATURE_PSS
Tags
$sLen
Length of salt
protected
int
$sLen
Tags
$zero
Precomputed Zero
protected
static BigInteger
$zero
Tags
$comment
Key Comment
private
null|string
$comment
Tags
$defaultExponent
Default public exponent
private
static int
$defaultExponent
= 65537
Tags
$hmac
HMAC function
private
Hash
$hmac
Tags
$invisiblePlugins
Invisible plugins
private
static array<string|int, mixed>
$invisiblePlugins
= []
Tags
$plugins
Supported plugins (lower case)
private
static array<string|int, mixed>
$plugins
= []
Tags
$signatureFileFormats
Supported signature formats (original case)
private
static array<string|int, mixed>
$signatureFileFormats
= []
Tags
$signatureFormats
Supported signature formats (lower case)
private
static array<string|int, mixed>
$signatureFormats
= []
Tags
$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
Methods
__toString()
__toString() magic method
public
__toString() : string
Return values
stringaddFileFormat()
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
Return values
boolasPrivateKey()
Converts a public key to a private key
public
asPrivateKey() : RSA
Return values
RSAcreateKey()
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
Return values
RSAdisableBlinding()
Disable RSA Blinding
public
static disableBlinding() : mixed
Tags
enableBlinding()
Enable RSA Blinding
public
static enableBlinding() : mixed
Tags
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
Return values
bool|stringgetComment()
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
Return values
null|stringgetEngine()
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
Return values
stringgetFingerprint()
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
getHash()
Returns the hash algorithm currently being used
public
getHash() : mixed
Tags
getLabel()
Returns the label currently being used
public
getLabel() : mixed
Tags
getLength()
Returns the key size
public
getLength() : int
More specifically, this returns the size of the modulo in bits.
Tags
Return values
intgetLoadedFormat()
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
getMGFHash()
Returns the MGF hash algorithm currently being used
public
getMGFHash() : mixed
Tags
getPadding()
Returns the padding currently being used
public
getPadding() : mixed
Tags
getSaltLength()
Returns the salt length currently being used
public
getSaltLength() : mixed
Tags
getSupportedKeyFormats()
Returns a list of supported formats.
public
static getSupportedKeyFormats() : array<string|int, mixed>
Tags
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
AsymmetricKeyloadFormat()
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
AsymmetricKeyloadParameters()
Loads parameters
public
loadParameters(string|array<string|int, mixed> $key) : AsymmetricKey
Parameters
- $key : string|array<string|int, mixed>
Tags
Return values
AsymmetricKeyloadParametersFormat()
Loads parameters
public
loadParametersFormat(string $type, string|array<string|int, mixed> $key) : AsymmetricKey
Parameters
- $type : string
- $key : string|array<string|int, mixed>
Tags
Return values
AsymmetricKeyloadPrivateKey()
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
Return values
PrivateKeyloadPrivateKeyFormat()
Loads a private key
public
loadPrivateKeyFormat(string $type, string $key[, string $password = false ]) : PrivateKey
Parameters
- $type : string
- $key : string
- $password : string = false
-
optional
Tags
Return values
PrivateKeyloadPublicKey()
Loads a public key
public
loadPublicKey(string|array<string|int, mixed> $key) : PublicKey
Parameters
- $key : string|array<string|int, mixed>
Tags
Return values
PublicKeyloadPublicKeyFormat()
Loads a public key
public
loadPublicKeyFormat(string $type, string $key) : PublicKey
Parameters
- $type : string
- $key : string
Tags
Return values
PublicKeysetExponent()
Sets the public exponent for key generation
public
static setExponent(int $val) : mixed
This will be 65537 unless changed.
Parameters
- $val : int
Tags
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
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
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
useInternalEngine()
Flag to use internal engine only (useful for unit testing)
public
static useInternalEngine() : mixed
Tags
verify()
Verifies a signature
public
verify(string $message, string $signature) : bool
Parameters
- $message : string
- $signature : string
Tags
Return values
boolwithHash()
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
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
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
withPadding()
Determines the padding modes
public
withPadding(int $padding) : mixed
Example: $key->withPadding(RSA::ENCRYPTION_PKCS1 | RSA::SIGNATURE_PKCS1);
Parameters
- $padding : int
Tags
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
__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
Tags
Return values
BigIntegercomputek()
Compute the pseudorandom k for signature generation, using the process specified for deterministic DSA.
protected
computek(string $h1) : string
Parameters
- $h1 : string
Tags
Return values
stringemsa_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
Return values
stringemsa_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
Return values
stringi2osp()
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
Return values
bool|stringinitialize_static_variables()
Initialize static variables
protected
static initialize_static_variables() : mixed
mgf1()
MGF1
protected
mgf1(string $mgfSeed, int $maskLen) : string
Parameters
- $mgfSeed : string
- $maskLen : int
Tags
Return values
stringonLoad()
OnLoad Handler
protected
static onLoad(array<string|int, mixed> $components) : bool
Parameters
- $components : array<string|int, mixed>
Tags
Return values
boolos2ip()
Octet-String-to-Integer primitive
protected
os2ip(string $x) : BigInteger
See RFC3447#section-4.2.
Parameters
- $x : string
Tags
Return values
BigIntegervalidatePlugin()
Validate Plugin
protected
static validatePlugin(string $format, string $type[, string $method = NULL ]) : mixed
Parameters
- $format : string
- $type : string
- $method : string = NULL
-
optional
Tags
bits2octets()
Bit String to Octet String
private
bits2octets(string $in) : string
Parameters
- $in : string
Tags
Return values
stringemsa_pss_verify()
EMSA-PSS-VERIFY
private
emsa_pss_verify(string $m, string $em, int $emBits) : string
Parameters
- $m : string
- $em : string
- $emBits : int
Tags
Return values
stringexponentiate()
Exponentiate
private
exponentiate(BigInteger $x) : BigInteger
Parameters
- $x : BigInteger
Return values
BigIntegerint2octets()
Integer to Octet String
private
int2octets(BigInteger $v) : string
Parameters
- $v : BigInteger
Tags
Return values
stringloadPlugins()
Load Plugins
private
static loadPlugins(string $format) : mixed
Parameters
- $format : string
Tags
raw_encrypt()
Raw Encryption / Decryption
private
raw_encrypt(string $m) : bool|string
Doesn't use padding and is not recommended.
Parameters
- $m : string
Tags
Return values
bool|stringrsaep()
RSAEP
private
rsaep(BigInteger $m) : bool|BigInteger
Parameters
- $m : BigInteger
Tags
Return values
bool|BigIntegerrsaes_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
Return values
stringrsaes_pkcs1_v1_5_encrypt()
RSAES-PKCS1-V1_5-ENCRYPT
private
rsaes_pkcs1_v1_5_encrypt(string $m[, bool $pkcs15_compat = false ]) : bool|string
Parameters
- $m : string
- $pkcs15_compat : bool = false
-
optional
Tags
Return values
bool|stringrsassa_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
Return values
boolrsassa_pkcs1_v1_5_verify()
RSASSA-PKCS1-V1_5-VERIFY
private
rsassa_pkcs1_v1_5_verify(string $m, string $s) : bool
Parameters
- $m : string
- $s : string
Tags
Return values
boolrsassa_pss_verify()
RSASSA-PSS-VERIFY
private
rsassa_pss_verify(string $m, string $s) : bool|string
Parameters
- $m : string
- $s : string
Tags
Return values
bool|stringrsavp1()
RSAVP1
private
rsavp1(BigInteger $s) : bool|BigInteger
Parameters
- $s : BigInteger