diff options
Diffstat (limited to 'doc/luaossl.tex')
| -rw-r--r-- | doc/luaossl.tex | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/doc/luaossl.tex b/doc/luaossl.tex index c63df57..c371dbd 100644 --- a/doc/luaossl.tex +++ b/doc/luaossl.tex @@ -597,6 +597,19 @@ Returns the type of signature used to sign the certificate as a string. e.g. ``R 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:verify}]{\fn{x509:verify\{ $\ldots$ \}}} + +Verifies the certificate against to the specified parameters. + +\begin{ctabular}{ c | c | p{9cm}} +field & type & description\\\hline +.store & \module{openssl.x509.store} & The certificate store to verify against, any custom settings from the store will be used. \\ +.chain & \module{openssl.x509.chain} & A collection of additional certificates to consider \\ +.params & \module{openssl.x509.verify\_param} & The verification parameters to use; overrides any parameters in $.store$ +\end{ctabular} + +Returns two values. The first is a boolean value for whether the specified certificate $crt$ was verified. If true, the second value is a \module{openssl.x509.chain} object validation chain. If false, the second value is a string describing why verification failed. + \subsubsection[\fn{x509:text}]{\fn{x509:text()}} Returns a human-readable textual representation of the X.509 certificate. @@ -787,6 +800,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 \fn{verify\_param} object to inherit from, or a string referring to one of the OpenSSL predefined 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} + +\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}{ 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([$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.\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()}} + +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 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 \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 the string $email$, overriding any previously specified email address. + +\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} @@ -1457,6 +1559,37 @@ Applies DES\_set\_odd\_parity to the string $key$. Only the first 8 bytes of $ke \end{Module} +\begin{Module}{openssl.kdf} + +Binds OpenSSL's Key Derivation Function interfaces. + +\subsubsection[\fn{kdf.derive}]{\fn{kdf.derive($options$)}} + +Derive a key given the table of $options$, different KDF types require different options. Accepted options are: + +\begin{ctabular}{ c | c | p{5in}} +field & type & description\\\hline +.type & string & key derivation algorithm---``PBKDF2'', ``id-scrypt'', ``hkdf'', ``TLS-PRF1'' or other depending on your version of OpenSSL \\ +.outlen & number & the desired output size \\ +.pass & string & password \\ +.salt & string & salt \\ +.iter & number & iteration count \\ +.md & string & digest to use \\ +.key & string & key \\ +.maxmem\_bytes & number & amount of RAM key derivation may maximally use (in bytes) \\ +.secret & string & TLS1-PRF secret \\ +.seed & string & TLS1-PRF seed \\ +.hkdf\_mode & string & the HKDF mode to use, one of ``extract\_and\_expand'', ``extract\_only'' or ``expand\_only'' \\ +.info & string & HKDF info value \\ +.N & number & scrypt ``N'' parameter to use \\ +.r & number & scrypt ``r'' parameter to use \\ +.p & number & scrypt ``p'' parameter to use +\end{ctabular} + + +\end{Module} + + \chapter{Examples} These examples and others are made available under examples/ in the source tree. |