diff options
Diffstat (limited to 'ext/openssl/README')
| -rw-r--r-- | ext/openssl/README | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/ext/openssl/README b/ext/openssl/README deleted file mode 100644 index df3f79d509..0000000000 --- a/ext/openssl/README +++ /dev/null @@ -1,321 +0,0 @@ -OpenSSL extension for PHP4 -$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); - ?> |