OpenSSL extension for PHP 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 Sign and verify