diff options
Diffstat (limited to 'ext/openssl/README')
| -rw-r--r-- | ext/openssl/README | 322 |
1 files changed, 322 insertions, 0 deletions
diff --git a/ext/openssl/README b/ext/openssl/README new file mode 100644 index 0000000..20a3833 --- /dev/null +++ b/ext/openssl/README @@ -0,0 +1,322 @@ +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); + ?> |