php-src/ext/openssl/README

OpenSSL extension for PHP

$Id$

The functions implemented so far make it possible to seal and open data, and
also create and verify signatures.

NEW: support for S/MIME encrypt/decrypt/sign/verify, as well as more
flexibility for specifying certificates/keys.

To enable the extension, configure PHP with --with-openssl.

Specifying keys/certificates
----------------------------

Most of the functions require a key or a certificate as a parameter; to make
things easy for you to use openssl, this extension allows you
to specify certificates in the following way:

1. As an X.509 resource returned from openssl_x509_read
2. As a string in the format file://filename, where filename is the path to the
   certificate file (it will be opened and read automatically)
3. As a string containing the data from the certificate file

Similarly, you can use the following methods of specifying a public key:

1. As a key resource returned from openssl_get_publickey
2. An X509 resource - public key only
3. As a string in the format file://filename
4. As a string containing the data from the key file

Additionally, for a private key, when the openssl extension function does not
allow you to enter the passphrase as a parameter you may use the syntax
array($key, "passphrase") where $key can be a key specified using one of the
methods listed above.

Certificate Verification
------------------------
When calling a function that will verify a signature/certificate, the cainfo
parameter is an array containing file and directory names that specifiy the
locations of trusted CA files.  If a directory is specified, then it must be a
correctly hashed directory.

Misc:
-----

mixed openssl_error_string()

returns the message from the last error that the OpenSSL library encountered
and moves it's internal error pointer to the next message.  If there are no
more error messages, returns false.

General Key/Cert Functions:
---------------------------

resource openssl_get_privatekey(mixed key [, string passphrase])

Parses the key data and returns a key resource identifier. If the key is
encrypted a passphrase is needed. This can be supplied as second argument.


resource openssl_get_publickey(mixed cert)

Extracts the public key from the given certificate or public key and returns
a key resource identifier.


void openssl_free_key(resource key)

Frees the resource given by the key resource identifier.
Note that this function does not accept the extended key specification
syntax mentioned above, as it doesn't make sense in this case!

array openssl_x509_parse(mixed x509[, bool shortnames=true])

Parses the certificate data and returns an array containing information
about the certificate, it's intended purposes, subject, issuer, validity
etc. etc.  If shortnames is true (the default) then the fields will be
keyed by the shortname forms eg: CN as opposed to commonName (shortnames
= false).


bool openssl_x509_checkpurpose(mixed x509cert, int purpose,
	array cainfo[, string untrustedfile])

Verifies if the certificate can be used for a specific purpose.
Purpose can be one of the following values:
	X509_PURPOSE_SSL_CLIENT
	X509_PURPOSE_SSL_SERVER
	X509_PURPOSE_NS_SSL_SERVER
	X509_PURPOSE_SMIME_SIGN
	X509_PURPOSE_SMIME_ENCRYPT
	X509_PURPOSE_CRL_SIGN
	X509_PURPOSE_ANY

cainfo is an array of CA information (as mentioned above).
untrusted file specifies a file containing a bunch of certs that
are not trusted but may be useful in validating the certificate.


resource openssl_read_x509(mixed cert)

Parses the cert and returns a resource that can be used with the
other openssl functions


void openssl_free_x509(resource x509)

Frees the resource given by the x509 resource identifier.
Note that this function does not accept the extended cert specification
syntax mentioned above, as it doesn't make sense in this case!


PKCS7 (S/MIME) Sign/Verify/Encrypt/Decrypt Functions:
-----------------------------------------------------

These functions allow you to manipulate S/MIME messages!

They are based on apps/smime.c from the openssl dist, so for information,
see the documentation for openssl.

You may pass in some flags that affect how these functions work using
and array containing the following values:
"detached", "nodetached", "text", "nointern", "noverify", "nochain",
"nocerts", "noattr", "binary", "nosigs".
The options correspond to the options of the same name for the
"openssl smime" command (smime(1)).


bool openssl_pkcs7_verify(string filename, array flags[, string signerscerts][,
		array cainfo])

Verifies that the signature on the MIME message contained in the file
named by filename is valid.  If signerscerts is passed in, it holds the
name of a file into which the certificates of those that signed the
message will be stored.
cainfo and flags are CA information and flag information as described
above.


bool openssl_pkcs7_encrypt(string infile, string outfile, array recipcerts,
		array headers[, array flags])

Encrypts the MIME message contained in the file named by infile using
the certificates held in recipcerts.  The result is place in the file
named outfile.
recipcerts is an array of certificate identifiers representing the certs
of the intended recipients of the message.
headers is an array of headers to prepend to the message: they will
not be included in the encoded section.
flags is flag information as described above.
Hint: you will want to put "To", "From", and "Subject" headers in headers.
Headers can be either an assoc array keyed by header named, or can be
and indexed array containing a single header line per value.
The message will be encoded using a RC2-40 bit cipher.
TODO: allow user to specify cipher.

bool openssl_pkcs7_sign(string infile, string outfile, mixed signcert, mixed
		signkey, array headers[, array flags][, string extracertsfilename])

Signs the MIME message contained in the file named by infile using the
certificate and key pair identified by signcert/signkey.
Signkey must be the private key corresponding to signcert.
The result is placed in the file named by outfile.
Headers and flags have the same effects as mentioned above.
extracertsfilename names a file containing a bunch of additional certificates
to include in the signature, in order to aid the recipient in verifying the
message.


bool openssl_pkcs7_decrypt(string infilename, string outfilename, mixed
		recipcert, mixed recipkey)

Decrypts the MIME message contained in the file named by infilename
using the certificate and private key pair recipcert/recipkey.
The descrypted result is placed in outfilename.
TODO: add flags parameter, if needed?


EVP Sign/Verify/Encrypt/Decrypt Functions:
------------------------------------------

bool openssl_sign(string data, &string signature, mixed key)

Uses key to create signature for data, returns true on success and false
on failure. signature is passed by reference and contains the newly created
signature on success.


int openssl_verify(string data, string signature, mixed key)

Uses key to verify that the signature is correct for the given data.
Returns 1 if correct, 0 if incorrect, and -1 on error.


int openssl_seal(string data, &string sealdata, &array ekeys, array pubkeys)

Encrypts data using pubkeys, so that only owners of the respective private
keys and ekeys can decrypt and read the data. Returns the length of the
sealed data on success, else false. On success, sealdata and ekeys hold
the sealed data and envelope keys.


bool openssl_open(string data, &string opendata, string ekey, int privkey)

Opens (decrypts) sealed data using a private key and the corresponding
envelope key. Returns true on success and false on failure.  On success,
opendata will hold the descypted data.


See below for more details on usage. Also feel free to mail me at
venaas@php.net if you have questions. The OpenSSL documentation,
especially the EVP documentation at
http://www.openssl.org/docs/crypto/evp.html, might also be of help.


HOWTO:

To do anything you need a private key and a certificate containing the
corresponding public key. This is similar to what you have using say an
Apache webserver with OpenSSL. For testing you could try keys that come
with OpenSSL, that's what the sample scripts below do. You can also get
keys from some CA, or you can create them yourself.


Creating private key

To generate an unprotected 1024 bit RSA private key you can do

   openssl genrsa -out /tmp/test.key 1024

Private keys should be protected by a passphrase though.


Creating a self signed certificate

To generate a self signed certificate from the key that is valid for
365 days, do

    openssl req -new -key /tmp/test.key -out /tmp/test.crt -days 365 -x509


Example usage

These examples use keys that come with OpenSSL, you should perhaps test with
those first.


Seal and open

     <?php
     $data = "Follow the white rabbit";

     // Get certificate into a string
     // this file comes with OpenSSL 0.9.6
     $fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
     $cert = fread($fp, 8192);
     fclose($fp);
     // get public key from certificate
     $pk1 = openssl_get_publickey($cert);
     // $pk1 is an encryption key resource id if success, else false
     // Repeat if want public keys for multiple parties

     $fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
     $cert = fread($fp, 8192);
     fclose($fp);
     $pk2 = openssl_get_publickey($cert);

     // seal data, only owners of $pk1 and $pk2 can decrypt $sealed with keys
     // $ekeys[0] and $ekeys[1] respectively.
     openssl_seal($data, $sealed, $ekeys, array($pk1,$pk2));
     openssl_free_key($pk1);
     openssl_free_key($pk2);

     // now we try to decrypt data for one of the recipients
     $fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
     // Get PEM coded key into $pkey 
     $pkey = fread($fp, 8192);
     fclose($fp);
     // $key will be resource id for unpacked $pkey
     $key = openssl_get_privatekey($pkey);

     openssl_open($sealed, $open, $ekeys[1], $key);
     openssl_free_key($key);
     echo "$open\n";
     ?>


Sign and verify

     <?php
     $data = "Follow the white rabbit";

     // First we need to have a string containing the private key in PEM format
     // this file comes with OpenSSL 0.9.6
     $fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
     $pkey = fread($fp, 8192);
     fclose($fp);

     // get private key from the PEM format
     // $key is an encr key resource id if success, else false
     $key = openssl_get_privatekey($pkey);

     // calculate signature
     openssl_sign($data, $signature, $key);
     openssl_free_key($key);

     // recipient verifies signature
     // read certificate
     $fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
     $cert = fread($fp, 8192);
     fclose($fp);

     // Get public key from the certificate
     $pubkey = openssl_get_publickey($cert);

     // state whether signature is okay or not
     echo openssl_verify($data, $signature, $pubkey) == 1 ? "ok\n" : "bad\n";

     // free key
     openssl_free_key($pubkey);
     ?>