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