rfc:add-cms-support

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
Last revisionBoth sides next revision
rfc:add-cms-support [2020/05/11 12:18] – created elearrfc:add-cms-support [2020/05/13 19:45] – Move into discussion. elear
Line 1: Line 1:
 ====== PHP RFC: Add CMS Support ====== ====== PHP RFC: Add CMS Support ======
   * Version: 0.9   * Version: 0.9
-  * Date: 2020-05-11+  * Date: 2020-05-13
   * Author: Eliot Lear, lear@lear.ch   * Author: Eliot Lear, lear@lear.ch
-  * Status: Draft+  * Status: In Discussion
   * First Published at: http://wiki.php.net/rfc/add-cms-support   * First Published at: http://wiki.php.net/rfc/add-cms-support
  
Line 28: Line 28:
 As currently stands, the CMS sign and verify functions now can take as an argument the encoding method (DER/CMS/PEM). As currently stands, the CMS sign and verify functions now can take as an argument the encoding method (DER/CMS/PEM).
  
-The calling interface is as follows:+=== Calling Interface ===
  
 <code php> <code php>
-function openssl_cms_verify(string $filename, int $flags = 0, string $signerscerts = UNKNOWN, +function openssl_cms_sign(string $infile, string $outfile, $signcert, $signkey, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_SMIME, ?string $extracertsfilename = null): bool {} 
-array $cainfo = UNKNOWN, string $extracerts = UNKNOWN, string $content = UNKNOWN, string $pk7 = UNKNOWN, string $sigfile = UNKNOWN, $encoding = ENCODING_CMS ): bool {}+</code>
  
-function openssl_cms_encrypt(string $infile, string $outfile, $recipcerts, ?array $headers, int $flags = 0, int $cipher = OPENSSL_CIPHER_RC2_40): bool {} +This function signs a file with an X.509 certificate and key. 
-function openssl_cms_sign(string $infile, string $outfile, $signcert, $signkey, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_CMS, ?string $extracertsfilename = null): bool {} + 
-function openssl_cms_decrypt(string $infilename, string $outfilename, $recipcert, $recipkey = UNKNOWN): bool {}+Arguments: 
 +  * $infile - the name of the file to be signed 
 +  * $outfile - the name of the file to deposit the results 
 +  * $signcert - the name of the file containing the signing certificate 
 +  * $signkey - the name of file containing the key associated with $signcert 
 +  * $headers - an array of headers to be included in S/MIME output 
 +  * $flags - flags to be passed to cms_sign() 
 +  * $encoding - the encoding of the output file 
 +  * $extracertsfilename - intermediate certificates to be included in the signature 
 + 
 +<code php> 
 +function openssl_cms_verify(string $filename, int $flags = 0, string $signerscerts = UNKNOWN, array $cainfo = UNKNOWN, string $extracerts = UNKNOWN, string $content = UNKNOWN, string $pk7 = UNKNOWN, string $sigfile = UNKNOWN, $encoding = OPENSSL_ENCODING_SMIME ): bool {} 
 +</code> 
 + 
 +This function verifies a CMS signature, either attached or detached, with the specified encoding. 
 + 
 +Arguments:  
 +  * $filename - the input file 
 +  * $flags - flags that would be passed to cms_verify 
 +  * $signercerts - a file that the signer certificate and optionally intermediate certificates 
 +  * $cainfo - an array containing self-signed certificate authority certificates 
 +  * $extracerts - a file containing additional intermediarte certificates 
 +  * $content - a file pointing to the content when signatures are detached 
 +  * $pk7 - a file to save the signature to 
 +  * $encoding - one of three supported encodings (PEM/DER/SMIME). 
 + 
 +Returns TRUE on success and FALSE on failure. 
 +<code php> 
 +function openssl_cms_encrypt(string $infile, string $outfile, $recipcerts, ?array $headers, int $flags = 0, int $encoding = OPENSSL_ENCODING_SMIME,  int $cipher = OPENSSL_CIPHER_RC2_40): bool {} 
 +</code> 
 + 
 +This function encrypts content to one or more recipients, based on the certificates that are passed to it. 
 + 
 +Arguments: 
 + 
 +  * $infile - the file to be encrypted 
 +  * $outfile - the output file 
 +  * $recipcerts - recipients to encrypt to 
 +  * $headers - headers to include when S/MIME is usd 
 +  * $flags - Flags to be passed to CMS_sign 
 +  * $encoding - an encoding to output 
 +  * $cipher - a cypher to use 
 + 
 +Return values: TRUE on success or FALSE on failure. 
 + 
 +<code php> 
 +function openssl_cms_decrypt(string $infilename, string $outfilename, $recipcert, $recipkey = UNKNOWN, int $encoding = OPENSSL_ENCODING_SMIME): bool {} 
 +</code> 
 +Decrypts a CMS message. 
 + 
 +Arguments: 
 +  * $infilename - the name of a file containing encrypted content 
 +  * $outfilename - the name of the file to deposit the decrypted content 
 +  * $recipcert - the name of the file containing a certificate of the recipient 
 +  * $recipkey - the name of the file containing a PKCS#8 key 
 +  * $encoding - the encoding of the input file. 
 + 
 +Returns TRUE on success and FALSE on failure. 
 + 
 +<code php>
 function openssl_cms_read(string $infilename, &$certs): bool {} function openssl_cms_read(string $infilename, &$certs): bool {}
 </code> </code>
 +
 +Performs the exact analog to openssl_pkcs7_read().
 +
  
 This is **nearly** identical to the PKCS#7 calling interface, the only exception being $encoding. This is **nearly** identical to the PKCS#7 calling interface, the only exception being $encoding.
Line 53: Line 115:
  
 ==== To Existing Extensions ==== ==== To Existing Extensions ====
-openssl code is extended.  No existing functions are changed.+New functions are added to ext/openssl.  No existing functions are changed.
  
 ==== To Opcache ==== ==== To Opcache ====
-These are entirely file operations.+ 
 +No known impact.
  
  
Line 66: Line 129:
   OPENSSL_ENCODING_PEM /* encoding is PEM (Privacy-Enhanced Mail) */   OPENSSL_ENCODING_PEM /* encoding is PEM (Privacy-Enhanced Mail) */
  
 +The following analogs to PKCS#7 are also added:
  
 +  OPENSSL_CMS_DETACHED
 +  OPENSSL_CMS_TEXT
 +  OPENSSL_CMS_NOINTERN
 +  OPENSSL_CMS_NOVERIFY
 +  OPENSSL_CMS_NOCERTS
 +  OPENSSL_CMS_NOATTR
 +  OPENSSL_CMS_BINARY
 +  OPENSSL_CMS_NOSIGS
 +  
 ==== php.ini Defaults ==== ==== php.ini Defaults ====
  
Line 72: Line 145:
  
 ===== Open Issues ===== ===== Open Issues =====
-Currently encoding isn't passed to the encrypt, decrypt, and read operations.+No known issues.
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
Line 80: Line 153:
 ===== Future Scope ===== ===== Future Scope =====
  
-Currently, as with the PKCS#7 calls, these calls take files as arguments.  It may make sense to take +Currently, as with the PKCS#7 calls, these calls take files as arguments.  Future work should 
-strings as input and deliver strings as output.  However, existing use cases do not require this, and +focus on in-memory signing/encrypting/verifying/decrypting operations.
-any such change could be backward compatible with a new flag.+
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 89: Line 161:
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-This capability is available for inspection as [[https://github.com/php/php-src/pull/5251|PR5251]].+This capability is available for inspection as [[https://github.com/php/php-src/pull/5251|PR #5251]].
 Tests are available in that PR.  This PR is subject to change of course, based on community feedback. Tests are available in that PR.  This PR is subject to change of course, based on community feedback.
  
 +===== Proposed Voting Choices =====
 +
 +Yes/No.
  
 ===== Implementation ===== ===== Implementation =====
Line 104: Line 179:
   - [[https://www.rfc-editor.org/rfc/rfc5652.html|RFC 5652]]   - [[https://www.rfc-editor.org/rfc/rfc5652.html|RFC 5652]]
   - [[https://www.rfc-editor.org/rfc/rfc8520.html|RFC 8520]]   - [[https://www.rfc-editor.org/rfc/rfc8520.html|RFC 8520]]
 +  - [[https://github.com/php/php-src/pull/5251|Git Pull Request 5251]]
  
 ===== Rejected Features ===== ===== Rejected Features =====
 Keep this updated with features that were discussed on the mail lists. Keep this updated with features that were discussed on the mail lists.
rfc/add-cms-support.txt · Last modified: 2020/07/22 17:40 by carusogabriel

Page Tools