Version: 4.0

PFX

PFX, also known as PKCS12, is a container format that can contain multiple X509 certificates and private keys.

So let's say you wanted to sign an X.509 certificate. You have $CAprivate, $CAX509 and $pfx as existent variables.

If you didn't use the $pfx variable you would have to do this:

$x509->setIssuerDN($CAX509->getSubjectDN());
$x509->setAuthorityKeyIdentifier(
    $CAX509->getExtension('id-ce-subjectKeyIdentifier')['extnValue']
);
$CAprivate->sign($x509);

Or you could just do this:

$pfx->sign($x509);

Reading PFXs

use phpseclib4\File\PFX;

$pfx = PFX::load(file_get_contents('pfx.der'), 'password');

print_r($pfx);

^{(download pfx.der)}

password is optional. If you omit it, phpseclib tries null first and then falls back to the empty string, so a PFX encrypted with an empty password loads without your having to know that in advance. You only need to pass the argument when the PFX was encrypted with an actual password.

$pfx, in this case, is a PFX object which, in turn, is basically a thin wrapper around an instance of \phpseclib4\File\ASN1\Constructed. Passing $pfx through print_r() or var_dump() triggers the __debugInfo() magic method which, in turn, produces the following output:

version

phpseclib4\File\ASN1\Types\Integer

authSafe

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

bagId

phpseclib4\File\ASN1\Types\OID

PKCS8ShroudedKeyBag

bagValue

phpseclib4\Crypt\RSA\PrivateKey

contentType

phpseclib4\File\ASN1\Types\OID

id-encryptedData

content

bagId

phpseclib4\File\ASN1\Types\OID

CertBag

bagValue

certId

phpseclib4\File\ASN1\Types\OID

x509Certificate

certValue

phpseclib4\File\X509

macData

mac

digestAlgorithm

algorithm

phpseclib4\File\ASN1\Types\OID

id-sha256

digest

phpseclib4\File\ASN1\Types\OctetString

dab02d9c7f577fcd5ddb4094b50f397455c1b79474d5fcabafb950d3fc610712

macSalt

phpseclib4\File\ASN1\Types\OctetString

dc71b16a001622d4b57b2a7d31b1d9cbf00fcdf69256bd7ac214652cd0419fa1

iterations

phpseclib4\File\ASN1\Types\Integer

2048

An unencrypted PFX (eg. pfx2.der) looks like this:

version

phpseclib4\File\ASN1\Types\Integer

authSafe

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

bagId

phpseclib4\File\ASN1\Types\OID

KeyBag

bagValue

phpseclib4\Crypt\RSA\PrivateKey

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

bagId

phpseclib4\File\ASN1\Types\OID

CertBag

bagValue

certId

phpseclib4\File\ASN1\Types\OID

x509Certificate

certValue

phpseclib4\File\X509

If an encrypted PFX is loaded and neither null nor the empty string can decrypt it, \phpseclib4\Exception\PasswordNeededException will be thrown. If the password is wrong then \phpseclib4\Exception\BadDecryptionException will be thrown instead. The two are distinct so that you can prompt the user for a password in the first case and report a credential mismatch in the second.

All elements and subelements of the above PFX objects can be accessed as array elements vis-a-vis ArrayAccess.

To learn more about the capabilities afforded to the PFX class by virtue of it being a thin wrapper around \phpseclib4\File\ASN1\Constructed please refer to Deep Dive: ASN1\Constructed Objects.

getAll()

Returns an array containing all private key and X509 objects that are contained within the PFX.

This method is slightly more complicated than one might think because the X.509 certificates and private keys don't live next to one another. Here are the respective locations of the private key and the certificate for both the encrypted and unencrypted PFX:

$pfx['authSafe']['content'][0]['content'][0]['bagValue']
$pfx['authSafe']['content'][1]['content'][0]['bagValue']['certValue']

getCertificates()

Returns an array containing all the X.509 objects that are contained within the PFX.

getPrivateKeys()

Returns an array containing all the private objects that are contained within the PFX.

getFriendlyNames()

Returns an array containing all private key and X509 pkcs-9-at-friendlyName values.

getLocalKeyIDs()

Returns an array containing all private key and X509 pkcs-9-at-localKeyId values.

pluckByFriendlyName()

Has one parameter - $value, which can be a string or any \phpseclib4\File\ASN1\Types\BaseString instance (use BaseString when you need to pin a specific ASN.1 string type for matching).

Returns an array containing all private key and X509 objects that are contained within the PFX that have a pkcs-9-at-friendlyName matching $value.

pluckByLocalKeyID()

Has one parameter - $value, which can be a string or any \phpseclib4\File\ASN1\Types\BaseString instance.

Returns an array containing all private key and X509 objects that are contained within the PFX that have a pkcs-9-at-localKeyId matching $value.

A common idiom when bundling a cert with its matching private key is to give both bags the same localKeyID so that they can be paired up later:

$keyId = random_bytes(16);
$pfx->add($x509, friendlyName: 'production', localKeyID: $keyId);
$pfx->add($privKey, friendlyName: 'production', localKeyID: $keyId);

This is what Windows and Apple Keychain use to figure out which key belongs to which cert. pluckByLocalKeyID($keyId) will then return both objects together.

pfxFromFriendlyName()

Has one parameter - $value, which can be a string or any \phpseclib4\File\ASN1\Types\BaseString instance.

Returns a PFX object containing all private key and X509 objects that are contained within the PFX that have a pkcs-9-at-friendlyName matching $value.

pfxFromLocalKeyID()

Has one parameter - $value, which can be a string or any \phpseclib4\File\ASN1\Types\BaseString instance.

Returns a PFX object containing all private key and X509 objects that are contained within the PFX that have a pkcs-9-at-localKeyId matching $value.

Both pfxFrom* methods give the new PFX the same password as the one it came from, so a subset extracted from an encrypted PFX re-exports encrypted. The pkcs-9-at-friendlyName and pkcs-9-at-localKeyId attributes are not carried over, however — the objects are re-added without them. If you need the labels preserved, use the corresponding pluckBy* method and re-add() them yourself.

Creating PFXs

Minimalistic PFX

Consider the following:

use phpseclib4\File\PFX;

$pfx = new PFX();
echo $pfx;

Since PFXs are only available in binary format their output is not being included here.

This PFX has no X509 certificate and no private key, but it does have a password — the empty string — and therefore a MAC.

If you did print_r($pfx) on that PFX you'd get this:

version

phpseclib4\File\ASN1\Types\Integer

authSafe

contentType

phpseclib4\File\ASN1\Types\OID

id-data

content

Making Additions

Here's how you'd add an X.509 certificate and a private key:

$pfx->add($x509);
$pfx->add($privKey);

If you wanted them to be added with a pkcs-9-at-friendlyName attribute you could do this:

$pfx->add($x509, friendlyName: 'whatever');
$pfx->add($privKey, friendlyName: 'whatever');

If you wanted them to be added with a pkcs-9-at-localKeyId attribute you could do this:

$pfx->add($x509, localKeyID: 'whatever');
$pfx->add($privKey, localKeyID: 'whatever');

Setting Password

Passwords can be set (or changed) on a PFX by calling $pfx->setPassword('password'). By default, phpseclib uses the empty string as the password, which yields an encrypted, MAC'd PFX — this is what most other software means by a "passwordless" PFX.

Passwords can be removed from a PFX by calling $pfx->removePassword(). Note that $pfx->setPassword(null) and a bare $pfx->setPassword() do the same thing; to get an empty password you have to write $pfx->setPassword('') explicitly. Password-less PFXs do not have a MAC (as MACs require a password) and are not widely supported by other softwares. ¹

Set the password before calling add() where you can, since add() bag-types things according to the password state at the time: private keys go into a PKCS8ShroudedKeyBag when a password is set and a plain KeyBag when one isn't. Setting the password afterwards re-bags everything and works fine, but going from no password to a password is the more involved path.

Setting MAC Parameters

MAC Parameters can be set globally thusly:

PFX::setHashAlgorithm('sha256');
PFX::setIterationCount(1024);
PFX::setSaltLength(32);

Or they can be set on a per key basis thusly:

echo $key
    ->withPassword('demo')
    ->toString('PKCS8', [
        'hashAlgorithm' => 'sha256',
        'iterationCount' => 1024,
        'saltLength' => 32
    ]);

PFX::toString() accepts the same three options, overriding the global defaults for that one call without changing them:

echo $pfx->toString([
    'hashAlgorithm' => 'sha256',
    'iterationCount' => 1024,
    'saltLength' => 32
]);

These apply when phpseclib writes a PFX. Reading one uses whatever parameters the file itself specifies.

Valid hash algorithms are:

md2
md5
sha1
sha224
sha256
sha384
sha512/224
sha512/256

Creating signatures

Signatures can be created from strings or from objects implementing the phpseclib4\File\Common\Signable interface.

Example:

$pfx->sign($x509);

To sign with a PFX, the PFX must contain either:

Exactly one private key, no cert. Behaves like signing with a bare PrivateKey — no auto-fill of issuer info.
Exactly one private key and exactly one matching X509. The X509's public key must match the private key's public side. In this case sign() additionally copies the CA cert's subject DN as the target's issuer DN, and the CA cert's subjectKeyIdentifier as the target's authorityKeyIdentifier.

A PFX with more than one cert/key pair, or with non-matching cert and key, will throw \phpseclib4\Exception\InvalidArgumentException when you try to sign with it. If you have a PFX containing multiple identities, use pfxFromFriendlyName() or pfxFromLocalKeyID() to extract the specific pair you want to sign with first.

KeyStore Explorer 5.6.1, for instance, cannot open them at all. See also this Feb 2022 feature request for OpenSSL or this Aug 2016 issue for .NET. ↩

Reading PFXs​

getAll()​

getCertificates()​

getPrivateKeys()​

getFriendlyNames()​

getLocalKeyIDs()​

pluckByFriendlyName()​

pluckByLocalKeyID()​

pfxFromFriendlyName()​

pfxFromLocalKeyID()​

Creating PFXs​

Minimalistic PFX​

Making Additions​

Setting Password​

Setting MAC Parameters​

Creating signatures​

Footnotes​

Reading PFXs

getAll()

getCertificates()

getPrivateKeys()

getFriendlyNames()

getLocalKeyIDs()

pluckByFriendlyName()

pluckByLocalKeyID()

pfxFromFriendlyName()

pfxFromLocalKeyID()

Creating PFXs

Minimalistic PFX

Making Additions

Setting Password

Setting MAC Parameters

Creating signatures

Footnotes