partial documentation update

1 files changed, 176 insertions, 18 deletions

diff --git a/doc/luaossl.tex b/doc/luaossl.tex
index 347c2fe..e7d4c2d 100644
--- a/doc/luaossl.tex
+++ b/doc/luaossl.tex
@@ -351,6 +351,22 @@ Returns a key-value iterator over the alternative names. The key is one of ``ema
 \end{Module}
 
 
+\begin{Module}{openssl.x509.extension}
+
+Binds the X.509 extension OpenSSL object.
+
+\subsubsection[\fn{extension.new}]{\fn{extension.new($name$, $value$ [, $conf$])}}
+
+Returns a new X.509 extension. $name$, $value$, and $conf$ are [currently] plain text strings.
+$value$ and $conf$ should use \href{https://www.openssl.org/docs/apps/x509v3_config.html#ARBITRARY_EXTENSIONS}{OpenSSL's arbitrary extension format}.
+
+\subsubsection[\fn{extension.interpose}]{\fn{extension.interpose($name$, $function$)}}
+
+Add or interpose an extension class method. Returns the previous method, if any.
+
+\end{Module}
+
+
 \begin{Module}{openssl.x509}
 
 Binds the X.509 certificate OpenSSL ASN.1 object.
@@ -455,6 +471,10 @@ Returns the basic constraints critical flag as a boolean.
 
 Sets the basic constraints critical flag.
 
+\subsubsection[\fn{x509:addExtension}]{\fn{x509:addExtension($ext$)}}
+
+Adds \module{x509.extension} object to the certificate. 
+
 \subsubsection[\fn{x509:isIssuedBy}]{\fn{x509:isIssuedBy($issuer$)}}
 
 Returns a boolean according to whether the specified issuer---an \module{openssl.x509.name} object---signed the instance certificate.
@@ -471,6 +491,10 @@ Sets the public key component referenced by the \module{openssl.pkey} object $ke
 
 Signs and updates the instance certificate using the \module{openssl.pkey} $key$. $type$ is an optional string describing the digest type. See \module{pkey:sign}, regarding which types of digests are valid. If $type$ is omitted than a default type is used---``sha1'' for RSA keys, ``dss1'' for DSA keys, and ``ecdsa-with-SHA1'' for EC keys.
 
+\subsubsection[\fn{x509:text}]{\fn{x509:text()}}
+
+Returns a human-readable textual representation of the X.509 certificate.
+
 \subsubsection[\fn{x509:\_\_tostring}]{\fn{x509:\_\_tostring}}
 
 Returns the PEM encoded representation of the instance certificate.
@@ -494,7 +518,7 @@ Add or interpose a request class method. Returns the previous method, if any.
 
 Returns the X.509 version of the request.
 
-\subsubsection[\fn{car:setVersion}]{\fn{csr:setVersion($number$)}}
+\subsubsection[\fn{csr:setVersion}]{\fn{csr:setVersion($number$)}}
 
 Sets the X.509 version of the request.
 
@@ -504,7 +528,7 @@ Returns the subject distinguished name as an \module{x509.name} object.
 
 \subsubsection[\fn{csr:setSubject}]{\fn{csr:setSubject($name$)}}
 
-Sets the subject distinguished name.
+Sets the subject distinguished name. $name$ should be an \module{x509.name} object.
 
 \subsubsection[\fn{csr:getPublicKey}]{\fn{csr:getPublicKey()}}
 
@@ -514,7 +538,7 @@ Returns the public key component as an \module{openssl.pkey} object.
 
 Sets the public key component referenced by the \module{openssl.pkey} object $key$.
 
-\subsubsection[\fn{car:sign}]{\fn{csr:sign($key$)}}
+\subsubsection[\fn{csr:sign}]{\fn{csr:sign($key$)}}
 
 Signs the instance request using the \module{openssl.pkey} $key$.
 
@@ -525,6 +549,69 @@ Returns the PEM encoded representation of the instance request.
 \end{Module}
 
 
+\begin{Module}{openssl.x509.crl}
+
+Binds the X.509 certificate revocation list OpenSSL ASN.1 object.
+
+\subsubsection[\fn{crl.new}]{\fn{crl.new([$string$[, $format$]])}}
+
+Returns a new CRL object, optionally initialized to the specified PEM- or DER-encoded CRL $string$. $format$ is as described in \fn{openssl.pkey.new}---``PEM'', ``DER'', or ``*'' (default).
+
+\subsubsection[\fn{crl.interpose}]{\fn{crl.interpose($name$, $function$)}}
+
+Add or interpose a request class method. Returns the previous method, if any.
+
+\subsubsection[\fn{crl:getVersion}]{\fn{crl:getVersion()}}
+
+Returns the CRL version.
+
+\subsubsection[\fn{crl:setVersion}]{\fn{crl:setVersion($number$)}}
+
+Sets the CRL version.
+
+\subsubsection[\fn{crl:getLastUpdate}]{\fn{crl:getLastUpdate()}}
+
+Returns the Last Update time of the CRL as a Unix timestamp, or $nil$ if not set.
+
+\subsubsection[\fn{crl:setLastUpdate}]{\fn{crl:setLastUpdate($time$)}}
+
+Sets the Last Update time of the CRL. $time$ should be a Unix timestamp.
+
+\subsubsection[\fn{crl:getNextUpdate}]{\fn{crl:getNextUpdate()}}
+
+Returns the Next Update time of the CRL as a Unix timestamp, or $nil$ if not set.
+
+\subsubsection[\fn{crl:setNextUpdate}]{\fn{crl:setNextUpdate($time$)}}
+
+Sets the Next Update time of the CRL. $time$ should be a Unix timestamp.
+
+\subsubsection[\fn{crl:getIssuer}]{\fn{crl:getIssuer()}}
+
+Returns the issuer distinguished name as an \module{x509.name} object.
+
+\subsubsection[\fn{crl:setIssuer}]{\fn{crl:setIssuer($name$)}}
+
+Sets the issuer distinguished name. $name$ should be an \module{x509.name} object.
+
+\subsubsection[\fn{crl:add}]{\fn{crl:add($serial$ [, $time$])}}
+
+Add the certificate identified by $serial$ to the revocation list. $serial$ should be a \module{openssl.bignum} object, as returned by \fn{x509:getSerial}. $time$ is the revocation date as a Unix timestamp. If unspecified $time$ defaults to the current time.
+
+\subsubsection[\fn{crl:sign}]{\fn{crl:sign($key$)}}
+
+Signs the instance CRL using the \module{openssl.pkey} $key$.
+
+\subsubsection[\fn{crl:text}]{\fn{crl:text()}}
+
+Returns a human-readable textual representation of the instance CRL.
+
+\subsubsection[\fn{crl:\_\_tostring}]{\fn{crl:\_\_tostring}}
+
+Returns the PEM encoded representation of the instance CRL.
+
+\end{Module}
+
+
 \begin{Module}{openssl.x509.chain}
 
 Binds the ``STACK\_OF(X509)'' OpenSSL object, principally used in the OpenSSL library for representing a validation chain.
@@ -571,23 +658,34 @@ Returns two values. The first is a boolean value for whether the specified certi
 \end{Module}
 
 
+\begin{Module}{openssl.pkcs12}
+
+Binds the PKCS \#12 container OpenSSL object.
+
+\subsubsection[\fn{pkcs12.new}]{\fn{pkcs12.new\{ $\ldots$ \}}}
+
+Returns a new PKCS12 object initialized according to the named parameters---$password$, $key$, $certs$.
+
+FIXME.
+
+\subsubsection[\fn{pkcs12.interpose}]{\fn{pkcs12.interpose($name$, $function$)}}
+
+Add or interpose a store class method. Returns the previous method, if any.
+
+\subsubsection[\fn{pkcs12:\_\_tostring}]{\fn{pkcs12:\_\_tostring()}}
+
+Returns a PKCS \#12 binary encoded string.
+
+\end{Module}
+
+
 \begin{Module}{openssl.ssl.context}
 
 Binds the ``SSL\_CTX'' OpenSSL object, used as a configuration prototype for SSL connection instances. See \method{socket.starttls}.
 
 \subsubsection[\fn{context[]}]{\fn{context[]}}
 
-A table mapping bitwise flags to names.
-
-\begin{tabular}{ c | l }
-name & description \\\hline
-VERIFY\_NONE & disable client peer certificate verification \\
-VERIFY\_PEER & enable client peer certificate verification \\
-VERIFY\_FAIL\_IF\_NO\_PEER\_CERT & require a peer certificate \\
-VERIFY\_CLIENT\_ONCE & do not request peer certificates after initial handshake
-\end{tabular}
-
-See the \href{http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html#NOTES}{NOTES section} in the OpenSSL documentation for \fn{SSL\_CTX\_set\_verify\_mode}.
+A table mapping OpenSSL named constants. The available constants are documented with the relevant method.
 
 \subsubsection[\fn{context.new}]{\fn{context.new([$protocol$][, $server$])}}
 
@@ -597,18 +695,70 @@ Returns a new context object. $protocol$ is an optional string identifier select
 
 Add or interpose a context class method. Returns the previous method, if any.
 
-\subsubsection[\fn{context:setStore}]{\fn{context:setStore($store$)}}
+\subsubsection[\fn{context:setOptions}]{\fn{context:setOptions($flags$)}}
 
-Sets the \module{openssl.x509.store} of the context instance.
+Sets the option flags of the context instance. $flags$ is a bit-wise set of option flags to be ORd with the current set. The resultant option flags of the context instance will be the union of the old and new flags.\footnote{This idiosyncratic union behavior is how the OpenSSL routine works.}
 
-\subsubsection[\fn{context:getVerify}]{\fn{context:getVerify()}}
+\begin{ctabular}{ c | p{8cm} }
+name & description \\\hline
+\small{\texttt{OP\_MICROSOFT\_SESS\_ID\_BUG}} & When talking SSLv2, if session-id reuse is performed, the session-id passed back in the server-finished message is different from the one decided upon. \\
+\small{\texttt{OP\_NETSCAPE\_CHALLENGE\_BUG}} & Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte challenge but then appears to only use 16 bytes when generating the encryption keys. According to the SSLv3 spec, one should use 32 bytes for the challenge when operating in SSLv2/v3 compatibility mode, but as mentioned above, this breaks this server so 16 bytes is the way to go. \\
+\small{\texttt{OP\_LEGACY\_SERVER\_CONNECT}} & $\ldots$ \\
+\small{\texttt{OP\_NETSCAPE\_REUSE\_CIPHER\_CHANGE\_BUG}} & As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. \\
+\small{\texttt{OP\_MICROSOFT\_BIG\_SSLV3\_BUFFER}} & $\ldots$ \\
+\small{\texttt{OP\_SSLEAY\_080\_CLIENT\_DH\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_TLS\_D5\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_TLS\_BLOCK\_PADDING\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_DONT\_INSERT\_EMPTY\_FRAGMENTS}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_QUERY\_MTU}} & $\ldots$ \\
+\small{\texttt{OP\_COOKIE\_EXCHANGE}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_TICKET}} & $\ldots$ \\
+\small{\texttt{OP\_CISCO\_ANYCONNECT}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_SESSION\_RESUMPTION\_ON\_RENEGOTIATION}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_COMPRESSION}} & $\ldots$ \\
+\small{\texttt{OP\_ALLOW\_UNSAFE\_LEGACY\_RENEGOTIATION}} & $\ldots$ \\
+\small{\texttt{OP\_SINGLE\_ECDH\_USE}} & $\ldots$ \\
+\small{\texttt{OP\_SINGLE\_DH\_USE}} & $\ldots$ \\
+\small{\texttt{OP\_EPHEMERAL\_RSA}} & $\ldots$ \\
+\small{\texttt{OP\_CIPHER\_SERVER\_PREFERENCE}} & $\ldots$ \\
+\small{\texttt{OP\_TLS\_ROLLBACK\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_SSLv2}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_SSLv3}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_TLSv1}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_TLSv1\_2}} & $\ldots$ \\
+\small{\texttt{OP\_NO\_TLSv1\_1}} & $\ldots$ \\
+\small{\texttt{OP\_NETSCAPE\_CA\_DN\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_NETSCAPE\_DEMO\_CIPHER\_CHANGE\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_CRYPTOPRO\_TLSEXT\_BUG}} & $\ldots$ \\
+\small{\texttt{OP\_ALL}} & $\ldots$ \\
+\end{ctabular}
 
-Returns two values: the bitwise verification mode flags, and the maximum validation depth.
+\subsubsection[\fn{context:getOptions}]{\fn{context:getOptions()}}
+
+Returns the option flags of the context instance as an integer.
+
+\subsubsection[\fn{context:clearOptions}]{\fn{context:clearOptions()}}
+
+Clears the option flags of the context instance.
 
 \subsubsection[\fn{context:setVerify}]{\fn{context:setVerify([$mode$][, $depth$])}}
 
 Sets the verification mode flags and maximum validation chain depth.
 
+\begin{tabular}{ c | l }
+name & description \\\hline
+VERIFY\_NONE & disable client peer certificate verification \\
+VERIFY\_PEER & enable client peer certificate verification \\
+VERIFY\_FAIL\_IF\_NO\_PEER\_CERT & require a peer certificate \\
+VERIFY\_CLIENT\_ONCE & do not request peer certificates after initial handshake
+\end{tabular}
+
+See the \href{http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html#NOTES}{NOTES section} in the OpenSSL documentation for \fn{SSL\_CTX\_set\_verify\_mode}.
+
+\subsubsection[\fn{context:getVerify}]{\fn{context:getVerify()}}
+
+Returns two values: the bitwise verification mode flags, and the maximum validation depth.
+
 \subsubsection[\fn{context:setCertificate}]{\fn{context:setCertificate($crt$)}}
 
 Sets the X.509 certificate \module{openssl.x509} object $crt$ to send during SSL connection instance handshakes.
@@ -621,6 +771,14 @@ Sets the private key \module{openssl.pkey} object $key$ for use during SSL conne
 
 Sets the allowed public key and private key algorithms. The string format is documented in the \href{http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT}{OpenSSL ciphers(1) utility documentation}.
 
+\subsubsection[\fn{context:setEphemeralKey}]{\fn{context:setEphemeralKey($key$)}}
+
+Sets \module{openssl.pkey} object $key$ as the ephemeral key during key exchanges which use that particular key type. Typically $key$ will be either a Diffie-Hellman or Elliptic Curve key.
+
+\emph{In order to configure an SSL server to support an ephemeral key exchange cipher suite (i.e. DHE-* and ECDHE-*), the application must explicitly set the ephemeral keys. Simply enabling the cipher suite is not sufficient. The application can statically generate Diffie-Hellman public key parameters, and many servers ship with such a key compiled into the software. Elliptic curve keys are necessarily static, and instantiated by curve name\footnote{\href{http://en.wikipedia.org/w/index.php?title=Comparison\_of\_TLS\_implementations&oldid=629779090\#Supported\_elliptic\_curves}{According to Wikipedia} the most widely supported curve is prime256v1, so to enable ECDHE-* applications can simply do \texttt{ctx:setEphemeralKey(pkey.new\{ type = ``EC'', curve = ``prime256v1'' \})}. To achieve Perfect Forward Secrecy for ECDHE-*, applications must also do \texttt{ctx:setOptions(context.OP\_SINGLE\_ECDH\_USE)}. The \texttt{ctx} object must then be used to configure each SSL session, such as by passing it to \fn{cqueues.socket:starttls()}.}.}
+
+\emph{In addition, to attain Perfect Forward Secrecy the options \texttt{OP\_SINGLE\_DH\_USE} and \texttt{OP\_SINGLE\_ECDH\_USE} must be set so that OpenSSL discards and regenerates the secret keying parameters for each key exchange.}
+
 \end{Module}