1
OpenSSL extension for PHP
3
$Id: README,v 1.4 2004/01/17 12:59:41 sniper Exp $
5
The functions implemented so far make it possible to seal and open data, and
6
also create and verify signatures.
8
NEW: support for S/MIME encrypt/decrypt/sign/verify, as well as more
9
flexibility for specifying certificates/keys.
11
To enable the extension, configure PHP with --with-openssl.
13
Specifying keys/certificates
14
----------------------------
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:
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
25
Similarly, you can use the following methods of specifying a public key:
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
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
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.
47
mixed openssl_error_string()
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.
53
General Key/Cert Functions:
54
---------------------------
56
resource openssl_get_privatekey(mixed key [, string passphrase])
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.
62
resource openssl_get_publickey(mixed cert)
64
Extracts the public key from the given certificate or public key and returns
65
a key resource identifier.
68
void openssl_free_key(resource key)
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!
74
array openssl_x509_parse(mixed x509[, bool shortnames=true])
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
83
bool openssl_x509_checkpurpose(mixed x509cert, int purpose,
84
array cainfo[, string untrustedfile])
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
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.
101
resource openssl_read_x509(mixed cert)
103
Parses the cert and returns a resource that can be used with the
104
other openssl functions
107
void openssl_free_x509(resource x509)
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!
114
PKCS7 (S/MIME) Sign/Verify/Encrypt/Decrypt Functions:
115
-----------------------------------------------------
117
These functions allow you to manipulate S/MIME messages!
119
They are based on apps/smime.c from the openssl dist, so for information,
120
see the documentation for openssl.
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)).
130
bool openssl_pkcs7_verify(string filename, array flags[, string signerscerts][,
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
141
bool openssl_pkcs7_encrypt(string infile, string outfile, array recipcerts,
142
array headers[, array flags])
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
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.
158
bool openssl_pkcs7_sign(string infile, string outfile, mixed signcert, mixed
159
signkey, array headers[, array flags][, string extracertsfilename])
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
171
bool openssl_pkcs7_decrypt(string infilename, string outfilename, mixed
172
recipcert, mixed recipkey)
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?
180
EVP Sign/Verify/Encrypt/Decrypt Functions:
181
------------------------------------------
183
bool openssl_sign(string data, &string signature, mixed key)
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.
190
int openssl_verify(string data, string signature, mixed key)
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.
196
int openssl_seal(string data, &string sealdata, &array ekeys, array pubkeys)
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.
204
bool openssl_open(string data, &string opendata, string ekey, int privkey)
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.
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.
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.
228
To generate an unprotected 1024 bit RSA private key you can do
230
openssl genrsa -out /tmp/test.key 1024
232
Private keys should be protected by a passphrase though.
235
Creating a self signed certificate
237
To generate a self signed certificate from the key that is valid for
240
openssl req -new -key /tmp/test.key -out /tmp/test.crt -days 365 -x509
245
These examples use keys that come with OpenSSL, you should perhaps test with
252
$data = "Follow the white rabbit";
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);
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
264
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
265
$cert = fread($fp, 8192);
267
$pk2 = openssl_get_publickey($cert);
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);
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);
280
// $key will be resource id for unpacked $pkey
281
$key = openssl_get_privatekey($pkey);
283
openssl_open($sealed, $open, $ekeys[1], $key);
284
openssl_free_key($key);
292
$data = "Follow the white rabbit";
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);
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);
304
// calculate signature
305
openssl_sign($data, $signature, $key);
306
openssl_free_key($key);
308
// recipient verifies signature
310
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
311
$cert = fread($fp, 8192);
314
// Get public key from the certificate
315
$pubkey = openssl_get_publickey($cert);
317
// state whether signature is okay or not
318
echo openssl_verify($data, $signature, $pubkey) == 1 ? "ok\n" : "bad\n";
321
openssl_free_key($pubkey);
added
removed
ext/openssl/README
