From 4545e9f1a6586682c11c2f22ec7a42ee19252c64 Mon Sep 17 00:00:00 2001 From: Datong Sun Date: Tue, 11 Jun 2019 15:59:24 -0700 Subject: doc/luaossl.tex: Document the `x509.verify_param` object. closes #168 --- doc/luaossl.tex | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) 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} -- cgit v1.2.3-59-g8ed1b From 41f15ab7e3402be82f17b0d8db0792180adb3c8c Mon Sep 17 00:00:00 2001 From: daurnimator Date: Wed, 12 Jun 2019 13:39:23 +1000 Subject: doc/luaossl.tex: minor fixups --- doc/luaossl.tex | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/luaossl.tex b/doc/luaossl.tex index 0a4ecf4..7aa1e00 100644 --- a/doc/luaossl.tex +++ b/doc/luaossl.tex @@ -793,22 +793,22 @@ Binds the ``X509\_VERIFY\_PARAM'' OpenSSL object, principally used for setting p \subsubsection[\fn{verify\_param.new}]{\fn{verify\_param.new()}} -Returns a new verify param object. +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. +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: +Inherit flags from $src$. $src$ can be either another \fn{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\\ +\begin{ctabular}{ l | p{5cm} } +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} @@ -816,24 +816,24 @@ ssl\_server & SSL/TLS server parameters 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\\ +\begin{ctabular}{ l | p{4cm} } +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$)}} +\subsubsection[\fn{verify\_param:setTime}]{\fn{verify\_param:setTime([$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. +Sets the maximum verification depth to $depth$. That is the maximum number of untrusted CA certificates that can appear in a chain.\footnote{OpenSSL's behaviour in regards to depth changed between OpenSSL 1.0.1 and OpenSSL 1.0.2; similarly for LibreSSL} \subsubsection[\fn{verify\_param:getDepth}]{\fn{verify\_param:getDepth()}} @@ -853,19 +853,19 @@ Returns the current authentication security level. \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. +Sets the expected DNS hostname to the string $name$, overriding any previously specified host name or names. If $name$ is $nil$ 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. +Adds $name$ as an additional reference identifier that can match the peer's certificate. Any previous names set via \fn{verify\_param:setHost} or \fn{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). +Sets the expected RFC822 email address to the string $email$, overriding any previously specified email address. \emph{Only supported since OpenSSL 1.1.0.} -- cgit v1.2.3-59-g8ed1b