phpseclib: X.509 Tutorial

Reading an X.509 cert
Understanding an X.509 cert
Creating an X.509 cert fail
Validating a certificate
Creating a self-signed cert
- Sample Code
Distinguished Names
Creating a CA cert and a cert signed by the CA
- Sample Code

To understand phpseclib's X.509 API it first helps to consider what an X.509 certificate aims to do. So let's start off by decoding one.

Reading an X.509 cert

Here's google.com's X.509 cert:

Certificate 1: google.com's X.509 cert

Let's use phpseclib to decode that:

<?php
include('File/X509.php');

$x509 = new File_X509();
$cert = $x509->loadX509('...');

print_r($cert);
?>

Specific values can be retrieved by accessing the appropriate array indices in $cert or with the following (self-explanatory) functions:

getDNProp(): See Distinguished Names for more information.
getDN()
getIssuerDN()
getPublicKey(): Returns a Crypt_RSA object

The contents of $cert are as follows:

$cert:

tbsCertificate
- version
  - v3
- serialNumber
  - 105827261859531100510423749949966875981
- signature
  - algorithm
    - sha1WithRSAEncryption
- issuer
  - rdnSequence
    - 0
      - 0
        type
        id-at-countryName
        value
        ZA
    - 1
      - 0
        type
        id-at-organizationName
        value
        Thawte Consulting (Pty) Ltd.
    - 2
      - 0
        type
        id-at-commonName
        value
        Thawte SGC CA
- validity
  - notBefore
    - utcTime
      - Oct 25 19:00:00 2011 CDT
  - notAfter
    - utcTime
      - Sep 30 18:59:59 2013 CDT
- subject
  - rdnSequence
    - 0
      - 0
        type
        id-at-countryName
        value
        US
    - 1
      - 0
        type
        id-at-stateOrProvinceName
        value
        California
    - 2
      - 0
        type
        id-at-localityName
        value
        Mountain View
    - 3
      - 0
        type
        id-at-organizationName
        value
        Google Inc
    - 4
      - 0
        type
        id-at-commonName
        value
        www.google.com
- subjectPublicKeyInfo
  - algorithm
    - algorithm
      - rsaEncryption
  - subjectPublicKey
    - ```
    -----BEGIN PUBLIC KEY-----
    MIGJAoGBAN63JkOmmYXNOKcVCbnPD8nDVYyI7oyNKCckSypeoNgW+mEYS89tYIDTNUAycsCPEtjl
    To+5svbZFV5ahjGjuoaqa8jZcYzMzScTHp1CXTj2p6zv+mLzGIHUJEZ/AXd8xiqJFJm7mDkdqBn7
    OQBEfRuUangtaa3Aeiz60NogEpjTAgMBAAE=
    -----END PUBLIC KEY-----
```
- extensions
  - 0
    - extnId
      - id-ce-basicConstraints
    - critical
      - true
    - extnValue
  - 1
    - extnId
      - id-ce-cRLDistributionPoints
    - critical
      - false
    - extnValue
      - 0
        distributionPoint
        fullName
        0
        uniformResourceIdentifier
        http://crl.thawte.com/ThawteSGCCA.crl
  - 2
    - extnId
      - id-ce-extKeyUsage
    - critical
      - false
    - extnValue
      - 0
        id-kp-serverAuth
      - 1
        id-kp-clientAuth
      - 2
        2.16.840.1.113730.4.1
  - 3
    - extnId
      - id-pe-authorityInfoAccess
    - critical
      - false
    - extnValue
      - 0
        accessMethod
        id-ad-ocsp
        accessLocation
        uniformResourceIdentifier
        http://ocsp.thawte.com
      - 1
        accessMethod
        id-ad-caIssuers
        accessLocation
        uniformResourceIdentifier
        http://www.thawte.com/repository/Thawte_SGC_CA.crt
signatureAlgorithm
- algorithm
  - sha1WithRSAEncryption
signature
- ACGs1a7KNIlawqtS0rI0Zp16q+7mfNV+wlwou3QAyRAfQhP8aYoeJKACAOm6W8oZBLLTrwGyfl8U26bbUrma8xJ/fKKcO2+ZfepQDXYjEv/3ZnMpt5UKrdiLst4g6QpwZBEIyFrxfZ7saaWl1YLXJx6eVs3SdtV5K/clQxxp8Lj5

Understanding an X.509 cert

When you connect to an HTTPS website you're given that website's public key via an X.509 certificate. The question is... how do you know that that public key hasn't, itself, been tampered with? SSH asks you if the certificate is valid upon your first connection attempt and alerts you when the certificate changes on subsequent connection attempts. HTTPS uses certificate authorities to verify the legitimacy of a public key. Certificate authorities have public keys as well, that are distributed via X.509 certificates. A website's X.509 certificate is signed by a certificate authorities private key and then verified by the certificate authorities public key.

$cert['tbsCertificate']['issuer']:
Identifies the certificate authority that signed the current certificate.
$cert['tbsCertificate']['subject']:
Identifies the current certificate. If this and the issuer match the certificate is self-signed.
$cert['tbsCertificate']['subjectPublicKeyInfo']['subjectPublicKey']:
Contains the current certificates public key. If the current certificate is, itself, a certificate authority, this is what is used to verify another certificates signature.
$cert['signature']:
The result of $rsa->sign($cert['tbsCertificate']) with the certificate authorities private key.

Creating an X.509 cert fail

Let's try to save that X.509 cert as is:

<?php
include('File/X509.php');

$x509 = new File_X509();
$cert = $x509->loadX509('...');
echo $x509->saveX509($cert);
?>

Here's the result:

Certificate 2: google.com's re-encoded cert

Great! So we have a valid X.509 cert, right? Not quite. Although it'll decode as one it's not going to properly validate. Even though nothing in the certificate has been changed (which one could do by editing the associative array) X.509 certificates have certain optional fields that when not present default to certain values. Some encoders may save these values explicitly, which would change the DER encoding of the tbsCertificate portion of the certificate which is what the signature is based off of.

Validating a certificate

To validate a cert that certs signing cert needs to be loaded. This can be done by calling $x509->loadCA('...'). After that one need simply call $x509->validateSignature(). Here's an example:

<?php
include('File/X509.php');

$x509 = new File_X509();
$x509->loadCA('...');
$cert = $x509->loadX509('...');
echo $x509->validateSignature() ? 'valid' : 'invalid';
?>

The certificate used to sign google.com's certificate is as follows:

Certificate 3: google.com's signing cert

Pass that cert into $x509->loadCA() and then pass Certificate 1 into $x509->loadX509() and the above code will output "valid". Use Certificate 2 and the above code will output "invalid".

Other validation methods are as follows:

$x509->validateSignature(FILE_X509_VALIDATE_SIGNATURE_BY_CA) does not accept self-signed certs as being valid.
$x509->validateURL()
$x509->validateDate() validates against the current date.
$x509->validateDate('June 1, 1983') validates against June 1, 1983

Creating a self-signed cert

As Creating an X.509 cert fail demonstrated, simply saving an X.509 associative array is insufficient. The array needs to be properly signed. This can be done by calling $x509->sign($issuer, $subject).

The following is a discussion of the various options that can be set on each of the parameters in the $x509->sign($issuer, $subject) call. Feel free to skip ahead to the example.

$issuer properties consist of the following:

The distinguished name.
- See Distinguished Names to see how to set the distinguished name
- Corresponds to $cert['tbsCertificate']['issuer']
The private key.
- Set by $issuer->setPrivateKey()
- Used to create $cert['signature'])
The key identifier.
- Set by $issuer->setKeyIdentifier(). It's purpose is beyond the scope of this tutorial.
- Corresponds to the id-ce-authorityKeyIdentifier extension

$subject properties consist of the following:

The distinguished name.
- See Distinguished Names to see how to set the distinguished name
- Corresponds to $cert['tbsCertificate']['subject']
The public key.
- Set by $subject->setPublicKey()
- Corresponds to $cert['tbsCertificate']['subjectPublicKeyInfo']
The domain name.
- Set by $subject->setDomain()
- Corresponds to $cert['tbsCertificate']['subject'] (id-at-commonName) and potentially the id-ce-subjectAltName extension.
The key identifier.
- Set by $issuer->setKeyIdentifier(). It's purpose is beyond the scope of this tutorial.
- Corresponds to the id-ce-subjectKeyIdentifier extension

$x509 properties (ie. those that don't belong to either the $issuer or $subject consist of the following:

The start date.
- Set by $x509->setStartDate(). Accepts anything strtotime() accepts. Defaults to the current time.
- Corresponds to $cert['tbsCertificate']['validity']['notBefore']['utcTime']
The end date.
- Set by $x509->setEndDate(). Accepts anything strtotime() accepts. Defaults to one year from now
- Corresponds to $cert['tbsCertificate']['validity']['notAfter']['utcTime']
The serial number.
- Set by $x509->setSerialNumber(). Defaults to 0.
- Corresponds to $cert['tbsCertificate']['serialNumber']
Certificate Authority flag
- Set by $x509->makeCA(). Needs to be set if you want to import cert into browser as CA.
- Corresponds to id-ce-keyUsage and id-ce-basicConstraints

<?php
include('File/X509.php');
include('Crypt/RSA.php');

// create private key / x.509 cert for stunnel / website
$privKey = new Crypt_RSA();
extract($privKey->createKey());
$privKey->loadKey($privatekey);

$pubKey = new Crypt_RSA();
$pubKey->loadKey($publickey);
$pubKey->setPublicKey();

$subject = new File_X509();
$subject->setPublicKey($pubKey);
$subject->setDNProp('id-at-organizationName', 'phpseclib demo cert');
$subject->setDomain('www.whatever.com');

$issuer = new File_X509();
$issuer->setPrivateKey($privKey);
$issuer->setDN($subject->getDN());

$x509 = new File_X509();
//$x509->setStartDate('-1 month'); // default: now
//$x509->setEndDate('+1 year'); // default: +1 year
//$x509->setSerialNumber(chr(1)); // default: 0

$result = $x509->sign($issuer, $subject);
echo "the stunnel.pem contents are as follows:\r\n\r\n";
echo $privKey->getPrivateKey();
echo "\r\n";
echo $x509->saveX509($result);
echo "\r\n";

The output of the above is as follows:

Certificate 4: RSA Private Key and self-signed X.509 cert

the stunnel.pem contents are as follows:

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQCtYr+TcpSQ043ZZi+akC1LR5Q6MJPJ6/0MQ7IFPt/SCywaxsdFsNQ40+TOSFNk
G68nscyB5nEPDkNzLJ7AklNSRHItqxTwohuW4a+fBfzAi0vXS9IrM2iep13cHE9r5QW9pouRQiYf
bi5FegEWbtIc5SrmAxHAH9K3KGRaXEeufwIDAQABAoGAFijgwz+JrVjccESXIPH8V/q1/xnmSZBX
rxGX1wPKJ1Y2NNXi8g0/kmPCgnrL7ad8I16d/JwvJvVzuWyifYo2C7++wHjPKvqTXgg7OiCai3KV
O0y3r3xhVdvKOOmD42zPuPkHXSORrWP0wgH07pPThKRLmc2I1EuRtXzLvGrCOMECQQDbD7YRotnC
biL7OzoFuzUKEpSN464LhdkTcDWeRUEvQQa/hTiKIeJ5aTdvyEOKBpuYzPTh6/79nBkgS7Lg5KtV
AkEAyp9X06ZMXiOIFZszARddoALM1FXJkAVsa5T+pUJAscKU5JHFrgckk+D9snnYvR7eN5OMHOkP
fH9yzKS4Zif6gwJABojicoY8HruwWXQ7193syB8jxVPMZlWY0yaewtjoB+PVsrLjq+M04VBNMg10
TlLCI33BtFeY5LHaYgdAD8tifQJBAKnBGZmuR2jPJ+HCJtcRNlUqQ2TZgobwpEb1iun1ObIzrP5Z
yl3kihaCdsmiH51CUTYKnWZTM7BALnOYxQyBDfUCQQCI1JOGXOveAxsr4sP6vornAU/G7ekX2n9x
LAjktKBd0pX25L9fdqrZPH61bOvF9S3VjuiX5vSp8OyUxoWMPbPn
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIB4zCCAU6gAwIBAgIAMAsGCSqGSIb3DQEBBTA5MRwwGgYDVQQKDBNwaHBzZWNsaWIgZGVtbyBj
ZXJ0MRkwFwYDVQQDDBB3d3cud2hhdGV2ZXIuY29tMCIYDzIwMTIwNjA0MDMxMDMxWhgPMjAxMzA2
MDQwMzEwMzFaMDkxHDAaBgNVBAoME3BocHNlY2xpYiBkZW1vIGNlcnQxGTAXBgNVBAMMEHd3dy53
aGF0ZXZlci5jb20wgZ0wCwYJKoZIhvcNAQEBA4GNADCBiQKBgQCtYr+TcpSQ043ZZi+akC1LR5Q6
MJPJ6/0MQ7IFPt/SCywaxsdFsNQ40+TOSFNkG68nscyB5nEPDkNzLJ7AklNSRHItqxTwohuW4a+f
BfzAi0vXS9IrM2iep13cHE9r5QW9pouRQiYfbi5FegEWbtIc5SrmAxHAH9K3KGRaXEeufwIDAQAB
MAsGCSqGSIb3DQEBBQOBgQBYEsMuWBA9ie4ulXxeLhLoQvEo6vgl5LDRFMuP+AhkKzfXUo2yEMWP
/QxbSglcPT/ycb+5+FhYGWxGatM5V+sB43ZBHZD14ZWPN35ePmDIfqXdRmphhXuhdNU7DWwp97ZR
c26CQXzHurRf29VloV8k5JKwsfnLRPVCrbJySMB6dg==
-----END CERTIFICATE-----

Distinguished Names

Distinguished Names can be set by any of the following functions:

$subject->loadX509('...') will set the $subject object to use the certificate subject's distinguished name as its own
$subject->setDNProp('propName', 'propValue') accepts propName's like id-at-commonName (used in the X.509 specs) or CN (used by OpenSSL as short hand)
$subject->setDN('...') takes stuff like $cert['tbsCertificate']['subject'], the $code['subject'] output of $cert = openssl_x509_parse('...') and full-on DN strings. eg:
```
C=US, ST=California, L=Mountain View, O=Google Inc, CN=www.google.com
```
$subject->loadCSR('...') gets the distinguished name from a certificate signing request
$subject->removeDNProp('propName')

Creating a CA cert and a cert signed by the CA

Here we just create a self-signed cert and its corresponding private key, as above, that'll serve as the CA, and then another cert, signed by the CA, with a second private key to correspond to this second cert.

CA certs need to have $x509->makeCA() called on them for browsers to accept them as certificate authorities.

<?php
include('File/X509.php');
include('Crypt/RSA.php');

// create private key for CA cert
// (you should probably print it out if you want to reuse it)
$CAPrivKey = new Crypt_RSA();
extract($CAPrivKey->createKey());
$CAPrivKey->loadKey($privatekey);

$pubKey = new Crypt_RSA();
$pubKey->loadKey($publickey);
$pubKey->setPublicKey();

echo "the private key for the CA cert (can be discarded):\r\n\r\n";
echo $privatekey;
echo "\r\n\r\n";







// create a self-signed cert that'll serve as the CA
$subject = new File_X509();
$subject->setPublicKey($pubKey);
$subject->setDNProp('id-at-organizationName', 'phpseclib demo CA');

$issuer = new File_X509();
$issuer->setPrivateKey($CAPrivKey);
$issuer->setDN($CASubject = $subject->getDN());

$x509 = new File_X509();
$x509->setStartDate('-1 month');
$x509->setEndDate('+1 year');
$x509->setSerialNumber(chr(1));
$x509->makeCA();

$result = $x509->sign($issuer, $subject);
echo "the CA cert to be imported into the browser is as follows:\r\n\r\n";
echo $x509->saveX509($result);
echo "\r\n\r\n";








// create private key / x.509 cert for stunnel / website
$privKey = new Crypt_RSA();
extract($privKey->createKey());
$privKey->loadKey($privatekey);

$pubKey = new Crypt_RSA();
$pubKey->loadKey($publickey);
$pubKey->setPublicKey();

$subject = new File_X509();
$subject->setPublicKey($pubKey);
$subject->setDNProp('id-at-organizationName', 'phpseclib demo cert');
$subject->setDomain('www.google.com');

$issuer = new File_X509();
$issuer->setPrivateKey($CAPrivKey);
$issuer->setDN($CASubject);

$x509 = new File_X509();
$x509->setStartDate('-1 month');
$x509->setEndDate('+1 year');
$x509->setSerialNumber(chr(1));

$result = $x509->sign($issuer, $subject);
echo "the stunnel.pem contents are as follows:\r\n\r\n";
echo $privKey->getPrivateKey();
echo "\r\n";
echo $x509->saveX509($result);
echo "\r\n";