Annotation of embedaddon/php/ext/openssl/README, revision 1.1.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