Annotation of embedaddon/php/ext/openssl/README, revision 1.1.1.2

1.1       misho       1: OpenSSL extension for PHP
                      2: 
1.1.1.2 ! misho       3: $Id$
1.1       misho       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>