doc/luaossl.tex: Document the `x509.verify_param` object. closes #168

1 files changed, 89 insertions, 0 deletions

diff --git a/doc/luaossl.tex b/doc/luaossl.tex
index 8561957..0a4ecf4 100644
--- a/doc/luaossl.tex
+++ b/doc/luaossl.tex
@@ -787,6 +787,95 @@ Returns two values. The first is a boolean value for whether the specified certi
 
 \end{Module}
 
+\begin{Module}{openssl.x509.verify\_param}
+
+Binds the ``X509\_VERIFY\_PARAM'' OpenSSL object, principally used for setting parameters to be used during certificate verification operations.
+
+\subsubsection[\fn{verify\_param.new}]{\fn{verify\_param.new()}}
+
+Returns a new verify param object.
+
+\subsubsection[\fn{verify\_param.interpose}]{\fn{verify\_param.interpose($name$, $function$)}}
+
+Add or interpose a verify param class method. Returns the previous method, if any.
+
+\subsubsection[\fn{verify\_param:inherit}]{\fn{verify\_param:inherit($src$)}}
+
+Inherit flags from $src$. $src$ can be either another ``X509\_VERIFY\_PARAM'' object to inherit from, or a string referring to one of the OpenSSL predefined parameters:
+
+\begin{ctabular}{ c | p{12cm} }
+name & description\\\hline
+default & X509 default parameters\\
+smime\_sign & S/MIME sign parameters\\
+pkcs7 & Identical to $smime\_sign$\\
+ssl\_client & SSL/TLS client parameters\\
+ssl\_server & SSL/TLS server parameters
+\end{ctabular}
+
+\subsubsection[\fn{verify\_param:setPurpose}]{\fn{verify\_param:setPurpose($id\_or\_name$)}}
+
+Sets the verification purpose of the $verify\_param$. Valid argument can be either an integer which corresponds to OpenSSL's internal purpose ID, or string indicating predefined purposes:
+
+\begin{ctabular}{ c | p{12cm} }
+name & description\\\hline
+sslclient & SSL/TLS client\\
+sslserver & SSL/TLS server\\
+nssslserver & Netscape SSL server\\
+smimeencrypt & S/MIME encryption\\
+any & Any Purpose\\
+ocsphelper & OCSP helper\\
+timestampsign & Time Stamp signing
+\end{ctabular}
+
+\subsubsection[\fn{verify\_param:setTime}]{\fn{verify\_param:setTime($unix\_timestamp$)}}
+
+Sets the verification time in $verify\_param$ to the provided Unix timestamp. By default the current system time is used.
+
+\subsubsection[\fn{verify\_param:setDepth}]{\fn{verify\_param:setDepth($depth$)}}
+
+Sets the maximum verification depth to $depth$. That is the maximum number of untrusted CA certificates that can appear in a chain.
+
+\subsubsection[\fn{verify\_param:getDepth}]{\fn{verify\_param:getDepth()}}
+
+Returns the current maximum verification depth.
+
+\subsubsection[\fn{verify\_param:setAuthLevel}]{\fn{verify\_param:setAuthLevel($auth\_level$)}}
+
+Sets the authentication security level to $auth\_level$. The authentication security level determines the acceptable signature and public key strength when verifying certificate chains. For a certificate chain to validate, the public keys of all the certificates must meet the specified security level. The signature algorithm security level is not enforced for the chain's trust anchor certificate, which is either directly trusted or validated by means other than its signature. See \href{https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html}{$SSL\_CTX\_set\_security\_level(3)$} for the definitions of the available levels. The default security level is -1, or "not set". At security level 0 or lower all algorithms are acceptable. Security level 1 requires at least 80-bit-equivalent security and is broadly interoperable, though it will, for example, reject MD5 signatures or RSA keys shorter than 1024 bits.
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\subsubsection[\fn{verify\_param:getAuthLevel}]{\fn{verify\_param:getAuthLevel()}}
+
+Returns the current authentication security level.
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\subsubsection[\fn{verify\_param:setHost}]{\fn{verify\_param:setHost($name$)}}
+
+Sets the expected DNS hostname to $name$ and overriding any previously specified host name or names. If $name$ is absent then name checks will not be performed on the peer certificate.
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\subsubsection[\fn{verify\_param:addHost}]{\fn{verify\_param:addHost($name$)}}
+
+Adds $name$ as an additional reference identifier that can match the peer's certificate. Any previous names set via $verify\_param:setHost$ or $verify\_param:addHost$ are retained. When multiple names are configured, the peer is considered verified when any name matches.
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\subsubsection[\fn{verify\_param:setEmail}]{\fn{verify\_param:setEmail($email$)}}
+
+Sets the expected RFC822 email address to $email$ and overriding previously specified email address (if any).
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\subsubsection[\fn{verify\_param:setIP}]{\fn{verify\_param:setIP($address$)}}
+
+Sets the expected IP address to $address$. Can be dotted decimal quad for IPv4 and colon-separated hexadecimal for IPv6. The condensed "::" notation is supported for IPv6 addresses.
+
+\emph{Only supported since OpenSSL 1.1.0.}
+
+\end{Module}
 
 \begin{Module}{openssl.pkcs12}