diff --git a/reference/openssl/functions/openssl-csr-export-to-file.xml b/reference/openssl/functions/openssl-csr-export-to-file.xml index b8c710cf78..54294c141a 100644 --- a/reference/openssl/functions/openssl-csr-export-to-file.xml +++ b/reference/openssl/functions/openssl-csr-export-to-file.xml @@ -1,5 +1,5 @@ - + @@ -14,14 +14,21 @@ stringoutfilename boolnotext - &warn.experimental.func; - openssl_csr_export_to_file takes the CSR represented by - csr and saves it into the file named by - outfilename. The optional notext affects + openssl_csr_export_to_file takes the Certificate + Signing Request represented by csr and saves it + as ascii-armoured text into the file named by outfilename. + &return.success; + The optional notext affects the verbosity of the output; if it is &false; then additional human-readable information is included - in the output. + in the output. The default value of notext is + &true; + + See also openssl_csr_export, + openssl_csr_new and + openssl_csr_sign. + diff --git a/reference/openssl/functions/openssl-csr-export.xml b/reference/openssl/functions/openssl-csr-export.xml index f97c331f3c..10210e4428 100644 --- a/reference/openssl/functions/openssl-csr-export.xml +++ b/reference/openssl/functions/openssl-csr-export.xml @@ -1,23 +1,35 @@ - + openssl_csr_export - Exports a CSR to file or a var + Exports a CSR as a string Description boolopenssl_csr_export resourcecsr - stringout + string&out boolnotext - &warn.experimental.func; - &warn.undocumented.func; + openssl_csr_export takes the Certificate Signing + Request represented by csr and stores it as + ascii-armoured text into out, which is passed by + reference. + &return.success; + The optional notext affects + the verbosity of the output; if it is &false; then additional human-readable information is included + in the output. The default value of notext is + &true; + + See also openssl_csr_export_to_file, + openssl_csr_new and + openssl_csr_sign. + diff --git a/reference/openssl/functions/openssl-csr-new.xml b/reference/openssl/functions/openssl-csr-new.xml index 853c658513..f9724ecbf9 100644 --- a/reference/openssl/functions/openssl-csr-new.xml +++ b/reference/openssl/functions/openssl-csr-new.xml @@ -1,10 +1,10 @@ - + openssl_csr_new - Generates a privkey and CSR + Generates a CSR Description @@ -12,15 +12,155 @@ boolopenssl_csr_new arraydn resourceprivkey - arrayextraattribs arrayconfigargs + arrayextraattribs - &warn.experimental.func; openssl_csr_new generates a new CSR (Certificate Signing Request) based on the information provided by dn, which represents the Distinguished Name to be used in the certificate. + + privkey should be set to a private key that was + previously generated by openssl_pkey_new (or + otherwise obtained from the other openssl_pkey family of functions). + The corresponding public portion of the key will be used to sign the + CSR. + + + extraattribs is used to specify additional + configuration options for the CSR. Both dn and + extraattribs are associative arrays whose keys are + converted to OIDs and applied to the relevant part of the request. + + + By default, the information in your system openssl.conf + is used to initialize the request; you can specify a configuration file + section by setting the config_section_section key of + configargs. You can also specify and alternative + openssl configuration file by setting the config key + to the path of the file you want to use. + The following keys, if present in configargs + behave as their equivalents in the openssl.conf, as + listed in the table below. + + + Configuration overrides + + + + configargs key + type + openssl.conf equivalent + description + + + + + digest_alg + string + default_md + Selects which digest method to use + + + x509_extensions + string + x509_extensions + Selects which extensions should be used when creating an x509 + certificate + + + req_extensions + string + req_extensions + Selects which extensions should be used when creating a CSR + + + private_key_bits + integer + default_bits + Specifies how many bits should be used to generate a private + key + + + private_key_type + integer + none + Specifies the type of private key to create. This can be one + of OPENSSL_KEYTYPE_DSA, + OPENSSL_KEYTYPE_DH or + OPENSSL_KEYTYPE_RSA. + The default value is OPENSSL_KEYTYPE_RSA which + is currently the only supported key type. + + + + encrypt_key + booean + encrypt_key + Should an exported key (with passphrase) be encrypted? + + + +
+ + + &return.success; + + + + <function>openssl_csr_new</function> example + + "UK", + "stateOrProvinceName" => "Somerset", + "localityName" => "Glastonbury", + "organizationName" => "The Brain Room Limited", + "organizationalUnitName" => "PHP Documentation Team", + "commonName" => "Wez Furlong", + "emailAddress" => "wez@php.net" +); + +// Generate a new private (and public) key pair +$privkey = openssl_pkey_new(); + +// Generate a certificate signing request +$csr = openssl_csr_new($dn, $privkey); + +// You will usually want to create a self-signed certificate at this +// point until your CA fulfills your request. +// This creates a self-signed cert that is valid for 365 days +$sscert = openssl_csr_sign($csr, null, $privkey, 365); + +// Now you will want to preserve your private key, CSR and self-signed +// cert so that they can be installed into your web server, mail server +// or mail client (depending on the intended use of the certificate). +// This example shows how to get those things into variables, but you +// can also store them directly into files. +// Typically, you will send the CSR on to your CA who will then issue +// you with the "real" certificate. +openssl_csr_export($csr, $csrout) and debug_zval_dump($csrout); +openssl_x509_export($sscert, $certout) and debug_zval_dump($certout); +openssl_pkey_export($privkey, $pkeyout, "mypassword") and debug_zval_dump($pkeyout); + +// Show any errors that occurred here +while (($e = openssl_error_string()) !== false) { + echo $e . "\n"; +} + +]]> + + + diff --git a/reference/openssl/functions/openssl-csr-sign.xml b/reference/openssl/functions/openssl-csr-sign.xml index e7c79742bf..6c004153c8 100644 --- a/reference/openssl/functions/openssl-csr-sign.xml +++ b/reference/openssl/functions/openssl-csr-sign.xml @@ -1,23 +1,34 @@ - + openssl_csr_sign - Signs a cert with another CERT + Sign a CSR with another certificate (or itself) and generate a certificate Description resourceopenssl_csr_sign mixedcsr - mixedx509 + mixedcacert mixedpriv_key longdays - &warn.experimental.func; - &warn.undocumented.func; + openssl_csr_sign generates an x509 certificate + resource from the csr previously generated by + openssl_csr_new. + The generated certificate will be signed by + cacert. If cacert is &null;, + the generated certificate will be a self-signed certificate. + priv_key is the private key that corresponds to + cacert. + days specifies the length of time for which the + generated certificate will be valid, in days. + + + Returns an x509 certificate resource on success, &false; on failure. diff --git a/reference/openssl/functions/openssl-error-string.xml b/reference/openssl/functions/openssl-error-string.xml index 5a2de30759..ebd0781ff9 100644 --- a/reference/openssl/functions/openssl-error-string.xml +++ b/reference/openssl/functions/openssl-error-string.xml @@ -1,5 +1,5 @@ - + @@ -12,7 +12,6 @@ mixedopenssl_error_string - &warn.experimental.func; Returns an error message string, or &false; if there are no more error messages to return. @@ -22,8 +21,6 @@ openSSL library. Error messages are stacked, so this function should be called multiple times to collect all of the information. - The parameters/return type of this function may change before - it appears in a release version of PHP <function>openssl_error_string</function> example diff --git a/reference/openssl/functions/openssl-free-key.xml b/reference/openssl/functions/openssl-free-key.xml index 2808171366..555f316d35 100644 --- a/reference/openssl/functions/openssl-free-key.xml +++ b/reference/openssl/functions/openssl-free-key.xml @@ -1,5 +1,5 @@ - + @@ -12,7 +12,6 @@ voidopenssl_free_key resourcekey_identifier - &warn.experimental.func; openssl_free_key frees the key associated with the specified key_identifier from memory. diff --git a/reference/openssl/functions/openssl-get-privatekey.xml b/reference/openssl/functions/openssl-get-privatekey.xml index 4bb724c677..d1ad1b83ff 100644 --- a/reference/openssl/functions/openssl-get-privatekey.xml +++ b/reference/openssl/functions/openssl-get-privatekey.xml @@ -1,10 +1,10 @@ - + openssl_get_privatekey - Prepare a PEM formatted private key for use + Get a private key Description @@ -13,16 +13,8 @@ mixedkey stringpassphrase - &warn.experimental.func; - Returns a positive key resource identifier on success, or &false; on error. - - - openssl_get_privatekey parses the PEM - formatted private key specified by key - and prepares it for use by other functions. - The optional parameter passphrase must be used if - the specified key is encrypted (protected by a passphrase). + This is an alias for openssl_pkey_get_private. diff --git a/reference/openssl/functions/openssl-get-publickey.xml b/reference/openssl/functions/openssl-get-publickey.xml index bd322f1c01..d6ab1564e6 100644 --- a/reference/openssl/functions/openssl-get-publickey.xml +++ b/reference/openssl/functions/openssl-get-publickey.xml @@ -1,5 +1,5 @@ - + @@ -12,15 +12,8 @@ resourceopenssl_get_publickey mixedcertificate - &warn.experimental.func; - Returns a positive key resource identifier on success, or &false; on error. - - - openssl_get_publickey extracts the - public key from an X.509 certificate specified by - certificate and prepares it for use by other - functions. + This is an alias for openssl_pkey_get_public. diff --git a/reference/openssl/functions/openssl-open.xml b/reference/openssl/functions/openssl-open.xml index 8fc73dec5a..93c6b1f18b 100644 --- a/reference/openssl/functions/openssl-open.xml +++ b/reference/openssl/functions/openssl-open.xml @@ -1,5 +1,5 @@ - + @@ -15,7 +15,6 @@ stringenv_key mixedpriv_key_id - &warn.experimental.func; &return.success; If successful the opened data is returned in open_data. diff --git a/reference/openssl/functions/openssl-pkcs7-decrypt.xml b/reference/openssl/functions/openssl-pkcs7-decrypt.xml index ba7f88c542..f9f4535735 100644 --- a/reference/openssl/functions/openssl-pkcs7-decrypt.xml +++ b/reference/openssl/functions/openssl-pkcs7-decrypt.xml @@ -1,5 +1,5 @@ - + @@ -13,9 +13,8 @@ stringinfilename stringoutfilename mixedrecipcert - mixedrecipkey + mixedrecipkey - &warn.experimental.func; Decrypts the S/MIME encrypted message contained in the file specified by infilename using the certificate and it's diff --git a/reference/openssl/functions/openssl-pkcs7-encrypt.xml b/reference/openssl/functions/openssl-pkcs7-encrypt.xml index 800a45f159..86d2f005bc 100644 --- a/reference/openssl/functions/openssl-pkcs7-encrypt.xml +++ b/reference/openssl/functions/openssl-pkcs7-encrypt.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,6 @@ arrayheaders longflags - &warn.experimental.func; openssl_pkcs7_encrypt takes the contents of the file named infile and encrypts them using an RC2 @@ -52,7 +51,7 @@ HQ EOD; // load key -$key = implode("", file("nighthawk.pem")); +$key = file_get_contents("nighthawk.pem"); // save message to file $fp = fopen("msg.txt", "w"); @@ -61,8 +60,7 @@ fclose($fp); // encrypt it if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key, - array("To" => "nighthawk@example.com", // keyed -syntax + array("To" => "nighthawk@example.com", // keyed syntax "From: HQ ", // indexed syntax "Subject" => "Eyes only"))) { diff --git a/reference/openssl/functions/openssl-pkcs7-sign.xml b/reference/openssl/functions/openssl-pkcs7-sign.xml index 7dedf62c22..c4b7e4a794 100644 --- a/reference/openssl/functions/openssl-pkcs7-sign.xml +++ b/reference/openssl/functions/openssl-pkcs7-sign.xml @@ -1,5 +1,5 @@ - + @@ -18,7 +18,6 @@ longflags stringextracertsfilename - &warn.experimental.func; openssl_pkcs7_sign takes the contents of the file named infilename and signs them using the diff --git a/reference/openssl/functions/openssl-pkcs7-verify.xml b/reference/openssl/functions/openssl-pkcs7-verify.xml index 13a0dd655c..b04bf2b281 100644 --- a/reference/openssl/functions/openssl-pkcs7-verify.xml +++ b/reference/openssl/functions/openssl-pkcs7-verify.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,6 @@ arraycainfo stringextracerts - &warn.experimental.func; openssl_pkcs7_verify reads the S/MIME message contained in the filename specified by filename and diff --git a/reference/openssl/functions/openssl-pkey-export-to-file.xml b/reference/openssl/functions/openssl-pkey-export-to-file.xml index 928f88f058..6e1b8213eb 100644 --- a/reference/openssl/functions/openssl-pkey-export-to-file.xml +++ b/reference/openssl/functions/openssl-pkey-export-to-file.xml @@ -1,5 +1,5 @@ - + @@ -13,11 +13,18 @@ mixedkey stringoutfilename stringpassphrase - arrayconfig_args + arrayconfigargs - &warn.experimental.func; - &warn.undocumented.func; + openssl_pkey_export_to_file saves an ascii-armoured + (PEM encoded) rendition of key into the file named + by outfilename. The key can be optionally + protected by a passphrase. + configargs can be used to fine-tune the export + process by specifying and/or overriding options for the openssl + configuration file. See openssl_csr_new for more + information about configargs. + &return.success; diff --git a/reference/openssl/functions/openssl-pkey-export.xml b/reference/openssl/functions/openssl-pkey-export.xml index 887064df2c..f6b332759b 100644 --- a/reference/openssl/functions/openssl-pkey-export.xml +++ b/reference/openssl/functions/openssl-pkey-export.xml @@ -1,23 +1,30 @@ - + openssl_pkey_export - Gets an exportable representation of a key into a string or file + Gets an exportable representation of a key into a string Description boolopenssl_pkey_export mixedkey - mixedout + string&out stringpassphrase - arrayconfig_args + arrayconfigargs - &warn.experimental.func; - &warn.undocumented.func; + openssl_pkey_export exports + key as a PEM encoded string and stores it into + out (which is passed by reference). + The key is optionally protected by passphrase. + configargs can be used to fine-tune the export + process by specifying and/or overriding options for the openssl + configuration file. See openssl_csr_new for more + information about configargs. + &return.success; diff --git a/reference/openssl/functions/openssl-pkey-get-private.xml b/reference/openssl/functions/openssl-pkey-get-private.xml new file mode 100644 index 0000000000..d67ab106d4 --- /dev/null +++ b/reference/openssl/functions/openssl-pkey-get-private.xml @@ -0,0 +1,60 @@ + + + + + + openssl_pkey_get_private + Get a private key + + + Description + + resourceopenssl_get_privatekey + mixedkey + stringpassphrase + + + Returns a positive key resource identifier on success, or &false; on error. + + + openssl_get_privatekey parses + key and prepares it for use by other functions. + + key can be one of the following: + + a string having the format + file://path/to/file.pem. The named file must + contain a PEM encoded certificate/private key (it may contain both). + + + A PEM formatted private key. + + + + + The optional parameter passphrase must be used if + the specified key is encrypted (protected by a passphrase). + + + + + diff --git a/reference/openssl/functions/openssl-pkey-get-public.xml b/reference/openssl/functions/openssl-pkey-get-public.xml new file mode 100644 index 0000000000..c100d65e6f --- /dev/null +++ b/reference/openssl/functions/openssl-pkey-get-public.xml @@ -0,0 +1,55 @@ + + + + + + openssl_pkey_get_public + Extract public key from certificate and prepare it for use + + + Description + + resourceopenssl_pkey_get_public + mixedcertificate + + + Returns a positive key resource identifier on success, or &false; on error. + + + openssl_get_publickey extracts the + public key from certificate and + prepares it for use by other functions. + certificate can be one of the following: + + an X.509 certificate resource + a string having the format + file://path/to/file.pem. The named file must + contain a PEM encoded certificate/private key (it may contain both). + + + A PEM formatted private key. + + + + + + diff --git a/reference/openssl/functions/openssl-pkey-new.xml b/reference/openssl/functions/openssl-pkey-new.xml index a40cffb67a..8073667c02 100644 --- a/reference/openssl/functions/openssl-pkey-new.xml +++ b/reference/openssl/functions/openssl-pkey-new.xml @@ -1,5 +1,5 @@ - + @@ -12,9 +12,14 @@ resourceopenssl_pkey_new arrayconfigargs - &warn.experimental.func; - &warn.undocumented.func; + openssl_pkey_new generates a new private and public + key pair. The public component of the key can be obtained using + openssl_pkey_get_public. + You can finetune the key generation (such as specifying the number of + bits) using configargs. See + openssl_csr_new for more information about + configargs. diff --git a/reference/openssl/functions/openssl-private-decrypt.xml b/reference/openssl/functions/openssl-private-decrypt.xml index 1bf1684d00..fcdb7d5da4 100644 --- a/reference/openssl/functions/openssl-private-decrypt.xml +++ b/reference/openssl/functions/openssl-private-decrypt.xml @@ -1,5 +1,5 @@ - + @@ -11,13 +11,19 @@ boolopenssl_private_decrypt stringdata - stringcrypted + string&decrypted mixedkey intpadding - &warn.experimental.func; - &warn.undocumented.func; + openssl_private_decrypt decrypts + data that was previous encrypted via + openssl_private_encrypt and stores the result into + decrypted. key must be the + private key corresponding that was used to encrypt the + data. padding defaults to OPENSSL_PKCS1_PADDING, + but can also be one of OPENSSL_SSLV23_PADDING, OPENSSL_PKCS1_OAEP_PADDING + OPENSSL_NO_PADDING. diff --git a/reference/openssl/functions/openssl-x509-check-private-key.xml b/reference/openssl/functions/openssl-x509-check-private-key.xml index 2679242deb..5acd6edfc6 100644 --- a/reference/openssl/functions/openssl-x509-check-private-key.xml +++ b/reference/openssl/functions/openssl-x509-check-private-key.xml @@ -1,10 +1,10 @@ - + openssl_x509_check_private_key - Checks if a private key corresponds to a CERT + Checks if a private key corresponds to a certificate Description @@ -13,9 +13,10 @@ mixedcert mixedkey - &warn.experimental.func; - &warn.undocumented.func; + openssl_x509_check_private_key returns &true; if + key is the private key that corresponds to + cert, or &false; otherwise. diff --git a/reference/openssl/functions/openssl-x509-checkpurpose.xml b/reference/openssl/functions/openssl-x509-checkpurpose.xml index 609184a973..dd8379baea 100644 --- a/reference/openssl/functions/openssl-x509-checkpurpose.xml +++ b/reference/openssl/functions/openssl-x509-checkpurpose.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,6 @@ arraycainfo stringuntrustedfile - &warn.experimental.func; Returns &true; if the certificate can be used for the intended purpose, &false; if it cannot, or -1 on error. diff --git a/reference/openssl/functions/openssl-x509-export-to-file.xml b/reference/openssl/functions/openssl-x509-export-to-file.xml index 4d5ef68ee7..b78ec0924e 100644 --- a/reference/openssl/functions/openssl-x509-export-to-file.xml +++ b/reference/openssl/functions/openssl-x509-export-to-file.xml @@ -1,10 +1,10 @@ - + openssl_x509_export_to_file - Exports a CERT to file or a var + Exports a certificate to file Description @@ -14,9 +14,14 @@ stringoutfilename boolnotext - &warn.experimental.func; - &warn.undocumented.func; + openssl_x509_export_to_file stores + x509 into a file named by + outfilename in a PEM encoded format. + The optional parameter notext default to &true;. + If set to &false;, additional human readable text will also be stored + into the output file. + &return.success; diff --git a/reference/openssl/functions/openssl-x509-export.xml b/reference/openssl/functions/openssl-x509-export.xml index 28b198d0ba..dfd132f550 100644 --- a/reference/openssl/functions/openssl-x509-export.xml +++ b/reference/openssl/functions/openssl-x509-export.xml @@ -1,22 +1,27 @@ - + openssl_x509_export - Exports a CERT to file or a var + Exports a certificate as a string Description boolopenssl_x509_export mixedx509 - stringoutfilename + string&output boolnotext - &warn.experimental.func; - &warn.undocumented.func; + openssl_x509_export stores + x509 into a file named by + outfilename in a PEM encoded format. + The optional parameter notext default to &true;. + If set to &false;, additional human readable text will also be stored + into output. + &return.success; diff --git a/reference/openssl/functions/openssl-x509-free.xml b/reference/openssl/functions/openssl-x509-free.xml index 51a9606206..114206640a 100644 --- a/reference/openssl/functions/openssl-x509-free.xml +++ b/reference/openssl/functions/openssl-x509-free.xml @@ -1,5 +1,5 @@ - + @@ -12,7 +12,6 @@ voidopenssl_x509_free resourcex509cert - &warn.experimental.func; openssl_x509_free frees the certificate associated with the specified x509cert resource from memory. diff --git a/reference/openssl/functions/openssl-x509-parse.xml b/reference/openssl/functions/openssl-x509-parse.xml index 3d9e63ba13..74b56fd496 100644 --- a/reference/openssl/functions/openssl-x509-parse.xml +++ b/reference/openssl/functions/openssl-x509-parse.xml @@ -1,5 +1,5 @@ - + @@ -14,7 +14,7 @@ mixedx509cert boolshortnames - &warn.experimental.func; + &warn.experimental.func; openssl_x509_parse returns information about the supplied x509cert, including fields such as subject diff --git a/reference/openssl/functions/openssl-x509-read.xml b/reference/openssl/functions/openssl-x509-read.xml index e58eac39f6..f24acbdfec 100644 --- a/reference/openssl/functions/openssl-x509-read.xml +++ b/reference/openssl/functions/openssl-x509-read.xml @@ -1,5 +1,5 @@ - + @@ -13,7 +13,6 @@ resourceopenssl_x509_read mixedx509certdata - &warn.experimental.func; openssl_x509_read parses the certificate supplied by x509certdata and returns a resource identifier for diff --git a/reference/openssl/reference.xml b/reference/openssl/reference.xml index 4f70974c19..1a1115ebf9 100644 --- a/reference/openssl/reference.xml +++ b/reference/openssl/reference.xml @@ -1,10 +1,9 @@ - + OpenSSL functions OpenSSL - &warn.experimental;
&reftitle.intro;