Imported from /home/lorry/working-area/delta_php2/php-5.4.13.tar.bz2.HEADphp-5.4.13master

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);
+     ?>