Annotation of embedaddon/php/ext/openssl/README, revision 1.1
1.1 ! misho 1: OpenSSL extension for PHP
! 2:
! 3: $Id: README 242949 2007-09-26 15:44:16Z cvs2svn $
! 4:
! 5: The functions implemented so far make it possible to seal and open data, and
! 6: also create and verify signatures.
! 7:
! 8: NEW: support for S/MIME encrypt/decrypt/sign/verify, as well as more
! 9: flexibility for specifying certificates/keys.
! 10:
! 11: To enable the extension, configure PHP with --with-openssl.
! 12:
! 13: Specifying keys/certificates
! 14: ----------------------------
! 15:
! 16: Most of the functions require a key or a certificate as a parameter; to make
! 17: things easy for you to use openssl, this extension allows you
! 18: to specify certificates in the following way:
! 19:
! 20: 1. As an X.509 resource returned from openssl_x509_read
! 21: 2. As a string in the format file://filename, where filename is the path to the
! 22: certificate file (it will be opened and read automatically)
! 23: 3. As a string containing the data from the certificate file
! 24:
! 25: Similarly, you can use the following methods of specifying a public key:
! 26:
! 27: 1. As a key resource returned from openssl_get_publickey
! 28: 2. An X509 resource - public key only
! 29: 3. As a string in the format file://filename
! 30: 4. As a string containing the data from the key file
! 31:
! 32: Additionally, for a private key, when the openssl extension function does not
! 33: allow you to enter the passphrase as a parameter you may use the syntax
! 34: array($key, "passphrase") where $key can be a key specified using one of the
! 35: methods listed above.
! 36:
! 37: Certificate Verification
! 38: ------------------------
! 39: When calling a function that will verify a signature/certificate, the cainfo
! 40: parameter is an array containing file and directory names that specifiy the
! 41: locations of trusted CA files. If a directory is specified, then it must be a
! 42: correctly hashed directory.
! 43:
! 44: Misc:
! 45: -----
! 46:
! 47: mixed openssl_error_string()
! 48:
! 49: returns the message from the last error that the OpenSSL library encountered
! 50: and moves it's internal error pointer to the next message. If there are no
! 51: more error messages, returns false.
! 52:
! 53: General Key/Cert Functions:
! 54: ---------------------------
! 55:
! 56: resource openssl_get_privatekey(mixed key [, string passphrase])
! 57:
! 58: Parses the key data and returns a key resource identifier. If the key is
! 59: encrypted a passphrase is needed. This can be supplied as second argument.
! 60:
! 61:
! 62: resource openssl_get_publickey(mixed cert)
! 63:
! 64: Extracts the public key from the given certificate or public key and returns
! 65: a key resource identifier.
! 66:
! 67:
! 68: void openssl_free_key(resource key)
! 69:
! 70: Frees the resource given by the key resource identifier.
! 71: Note that this function does not accept the extended key specification
! 72: syntax mentioned above, as it doesn't make sense in this case!
! 73:
! 74: array openssl_x509_parse(mixed x509[, bool shortnames=true])
! 75:
! 76: Parses the certificate data and returns an array containing information
! 77: about the certificate, it's intended purposes, subject, issuer, validity
! 78: etc. etc. If shortnames is true (the default) then the fields will be
! 79: keyed by the shortname forms eg: CN as opposed to commonName (shortnames
! 80: = false).
! 81:
! 82:
! 83: bool openssl_x509_checkpurpose(mixed x509cert, int purpose,
! 84: array cainfo[, string untrustedfile])
! 85:
! 86: Verifies if the certificate can be used for a specific purpose.
! 87: Purpose can be one of the following values:
! 88: X509_PURPOSE_SSL_CLIENT
! 89: X509_PURPOSE_SSL_SERVER
! 90: X509_PURPOSE_NS_SSL_SERVER
! 91: X509_PURPOSE_SMIME_SIGN
! 92: X509_PURPOSE_SMIME_ENCRYPT
! 93: X509_PURPOSE_CRL_SIGN
! 94: X509_PURPOSE_ANY
! 95:
! 96: cainfo is an array of CA information (as mentioned above).
! 97: untrusted file specifies a file containing a bunch of certs that
! 98: are not trusted but may be useful in validating the certificate.
! 99:
! 100:
! 101: resource openssl_read_x509(mixed cert)
! 102:
! 103: Parses the cert and returns a resource that can be used with the
! 104: other openssl functions
! 105:
! 106:
! 107: void openssl_free_x509(resource x509)
! 108:
! 109: Frees the resource given by the x509 resource identifier.
! 110: Note that this function does not accept the extended cert specification
! 111: syntax mentioned above, as it doesn't make sense in this case!
! 112:
! 113:
! 114: PKCS7 (S/MIME) Sign/Verify/Encrypt/Decrypt Functions:
! 115: -----------------------------------------------------
! 116:
! 117: These functions allow you to manipulate S/MIME messages!
! 118:
! 119: They are based on apps/smime.c from the openssl dist, so for information,
! 120: see the documentation for openssl.
! 121:
! 122: You may pass in some flags that affect how these functions work using
! 123: and array containing the following values:
! 124: "detached", "nodetached", "text", "nointern", "noverify", "nochain",
! 125: "nocerts", "noattr", "binary", "nosigs".
! 126: The options correspond to the options of the same name for the
! 127: "openssl smime" command (smime(1)).
! 128:
! 129:
! 130: bool openssl_pkcs7_verify(string filename, array flags[, string signerscerts][,
! 131: array cainfo])
! 132:
! 133: Verifies that the signature on the MIME message contained in the file
! 134: named by filename is valid. If signerscerts is passed in, it holds the
! 135: name of a file into which the certificates of those that signed the
! 136: message will be stored.
! 137: cainfo and flags are CA information and flag information as described
! 138: above.
! 139:
! 140:
! 141: bool openssl_pkcs7_encrypt(string infile, string outfile, array recipcerts,
! 142: array headers[, array flags])
! 143:
! 144: Encrypts the MIME message contained in the file named by infile using
! 145: the certificates held in recipcerts. The result is place in the file
! 146: named outfile.
! 147: recipcerts is an array of certificate identifiers representing the certs
! 148: of the intended recipients of the message.
! 149: headers is an array of headers to prepend to the message: they will
! 150: not be included in the encoded section.
! 151: flags is flag information as described above.
! 152: Hint: you will want to put "To", "From", and "Subject" headers in headers.
! 153: Headers can be either an assoc array keyed by header named, or can be
! 154: and indexed array containing a single header line per value.
! 155: The message will be encoded using a RC2-40 bit cipher.
! 156: TODO: allow user to specify cipher.
! 157:
! 158: bool openssl_pkcs7_sign(string infile, string outfile, mixed signcert, mixed
! 159: signkey, array headers[, array flags][, string extracertsfilename])
! 160:
! 161: Signs the MIME message contained in the file named by infile using the
! 162: certificate and key pair identified by signcert/signkey.
! 163: Signkey must be the private key corresponding to signcert.
! 164: The result is placed in the file named by outfile.
! 165: Headers and flags have the same effects as mentioned above.
! 166: extracertsfilename names a file containing a bunch of additional certificates
! 167: to include in the signature, in order to aid the recipient in verifying the
! 168: message.
! 169:
! 170:
! 171: bool openssl_pkcs7_decrypt(string infilename, string outfilename, mixed
! 172: recipcert, mixed recipkey)
! 173:
! 174: Decrypts the MIME message contained in the file named by infilename
! 175: using the certificate and private key pair recipcert/recipkey.
! 176: The descrypted result is placed in outfilename.
! 177: TODO: add flags parameter, if needed?
! 178:
! 179:
! 180: EVP Sign/Verify/Encrypt/Decrypt Functions:
! 181: ------------------------------------------
! 182:
! 183: bool openssl_sign(string data, &string signature, mixed key)
! 184:
! 185: Uses key to create signature for data, returns true on success and false
! 186: on failure. signature is passed by reference and contains the newly created
! 187: signature on success.
! 188:
! 189:
! 190: int openssl_verify(string data, string signature, mixed key)
! 191:
! 192: Uses key to verify that the signature is correct for the given data.
! 193: Returns 1 if correct, 0 if incorrect, and -1 on error.
! 194:
! 195:
! 196: int openssl_seal(string data, &string sealdata, &array ekeys, array pubkeys)
! 197:
! 198: Encrypts data using pubkeys, so that only owners of the respective private
! 199: keys and ekeys can decrypt and read the data. Returns the length of the
! 200: sealed data on success, else false. On success, sealdata and ekeys hold
! 201: the sealed data and envelope keys.
! 202:
! 203:
! 204: bool openssl_open(string data, &string opendata, string ekey, int privkey)
! 205:
! 206: Opens (decrypts) sealed data using a private key and the corresponding
! 207: envelope key. Returns true on success and false on failure. On success,
! 208: opendata will hold the descypted data.
! 209:
! 210:
! 211: See below for more details on usage. Also feel free to mail me at
! 212: venaas@php.net if you have questions. The OpenSSL documentation,
! 213: especially the EVP documentation at
! 214: http://www.openssl.org/docs/crypto/evp.html, might also be of help.
! 215:
! 216:
! 217: HOWTO:
! 218:
! 219: To do anything you need a private key and a certificate containing the
! 220: corresponding public key. This is similar to what you have using say an
! 221: Apache webserver with OpenSSL. For testing you could try keys that come
! 222: with OpenSSL, that's what the sample scripts below do. You can also get
! 223: keys from some CA, or you can create them yourself.
! 224:
! 225:
! 226: Creating private key
! 227:
! 228: To generate an unprotected 1024 bit RSA private key you can do
! 229:
! 230: openssl genrsa -out /tmp/test.key 1024
! 231:
! 232: Private keys should be protected by a passphrase though.
! 233:
! 234:
! 235: Creating a self signed certificate
! 236:
! 237: To generate a self signed certificate from the key that is valid for
! 238: 365 days, do
! 239:
! 240: openssl req -new -key /tmp/test.key -out /tmp/test.crt -days 365 -x509
! 241:
! 242:
! 243: Example usage
! 244:
! 245: These examples use keys that come with OpenSSL, you should perhaps test with
! 246: those first.
! 247:
! 248:
! 249: Seal and open
! 250:
! 251: <?php
! 252: $data = "Follow the white rabbit";
! 253:
! 254: // Get certificate into a string
! 255: // this file comes with OpenSSL 0.9.6
! 256: $fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
! 257: $cert = fread($fp, 8192);
! 258: fclose($fp);
! 259: // get public key from certificate
! 260: $pk1 = openssl_get_publickey($cert);
! 261: // $pk1 is an encryption key resource id if success, else false
! 262: // Repeat if want public keys for multiple parties
! 263:
! 264: $fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
! 265: $cert = fread($fp, 8192);
! 266: fclose($fp);
! 267: $pk2 = openssl_get_publickey($cert);
! 268:
! 269: // seal data, only owners of $pk1 and $pk2 can decrypt $sealed with keys
! 270: // $ekeys[0] and $ekeys[1] respectively.
! 271: openssl_seal($data, $sealed, $ekeys, array($pk1,$pk2));
! 272: openssl_free_key($pk1);
! 273: openssl_free_key($pk2);
! 274:
! 275: // now we try to decrypt data for one of the recipients
! 276: $fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
! 277: // Get PEM coded key into $pkey
! 278: $pkey = fread($fp, 8192);
! 279: fclose($fp);
! 280: // $key will be resource id for unpacked $pkey
! 281: $key = openssl_get_privatekey($pkey);
! 282:
! 283: openssl_open($sealed, $open, $ekeys[1], $key);
! 284: openssl_free_key($key);
! 285: echo "$open\n";
! 286: ?>
! 287:
! 288:
! 289: Sign and verify
! 290:
! 291: <?php
! 292: $data = "Follow the white rabbit";
! 293:
! 294: // First we need to have a string containing the private key in PEM format
! 295: // this file comes with OpenSSL 0.9.6
! 296: $fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
! 297: $pkey = fread($fp, 8192);
! 298: fclose($fp);
! 299:
! 300: // get private key from the PEM format
! 301: // $key is an encr key resource id if success, else false
! 302: $key = openssl_get_privatekey($pkey);
! 303:
! 304: // calculate signature
! 305: openssl_sign($data, $signature, $key);
! 306: openssl_free_key($key);
! 307:
! 308: // recipient verifies signature
! 309: // read certificate
! 310: $fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
! 311: $cert = fread($fp, 8192);
! 312: fclose($fp);
! 313:
! 314: // Get public key from the certificate
! 315: $pubkey = openssl_get_publickey($cert);
! 316:
! 317: // state whether signature is okay or not
! 318: echo openssl_verify($data, $signature, $pubkey) == 1 ? "ok\n" : "bad\n";
! 319:
! 320: // free key
! 321: openssl_free_key($pubkey);
! 322: ?>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / openssl