Return to README CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / openssl

php 5.4.3+patches

    1: OpenSSL extension for PHP
    2: 
    3: $Id: README,v 1.1.1.2 2012/05/29 12:34:36 misho Exp $
    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:      ?>