summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/luaossl.pdfbin289975 -> 300041 bytes
-rw-r--r--doc/luaossl.tex162
2 files changed, 157 insertions, 5 deletions
diff --git a/doc/luaossl.pdf b/doc/luaossl.pdf
index 6a20f27..81142cb 100644
--- a/doc/luaossl.pdf
+++ b/doc/luaossl.pdf
Binary files differ
diff --git a/doc/luaossl.tex b/doc/luaossl.tex
index 76821a1..7bb85df 100644
--- a/doc/luaossl.tex
+++ b/doc/luaossl.tex
@@ -286,8 +286,13 @@ field & type:default & description\\\hline
286 286
287.exp & number:65537 & RSA or Diffie-Hellman exponent \\ 287.exp & number:65537 & RSA or Diffie-Hellman exponent \\
288 288
289.dhparam & string & PEM encoded string with precomputed DH parameters \\
290
289.curve & string:prime192v1 & for elliptic curve keys, the OpenSSL string identifier of the curve 291.curve & string:prime192v1 & for elliptic curve keys, the OpenSSL string identifier of the curve
290\end{ctabular} 292\end{ctabular}
293
294The DH parameters ``dhparam'' will be generated on the fly, ``bits'' wide. This is a slow process, and especially for larger sizes, you would precompute those; for example: ``openssl dhparam -2 -out dh-2048.pem -outform PEM 2048''. Using the field ``dhparam'' overrides the ``bits'' field.
295
291\subsubsection[\fn{pkey.interpose}]{\fn{pkey.interpose($name$, $function$)}} 296\subsubsection[\fn{pkey.interpose}]{\fn{pkey.interpose($name$, $function$)}}
292 297
293Add or interpose a pkey class method. Returns the previous method, if any. 298Add or interpose a pkey class method. Returns the previous method, if any.
@@ -389,7 +394,19 @@ Binds the X.509 extension OpenSSL object.
389 394
390\subsubsection[\fn{extension.new}]{\fn{extension.new($name$, $value$ [, $data$])}} 395\subsubsection[\fn{extension.new}]{\fn{extension.new($name$, $value$ [, $data$])}}
391 396
392Returns a new X.509 extension. If $value$ is the string ``DER'' or ``critical,DER'', then $data$ is an ASN.1-encoded octet string. Otherwise, $name$ and $value$ are plain text strings in \href{https://www.openssl.org/docs/apps/x509v3_config.html#ARBITRARY_EXTENSIONS}{OpenSSL's arbitrary extension format}; and if specified, $data$ is an OpenSSL configuration string defining any referenced identifiers in $value$. 397Returns a new X.509 extension.
398If $value$ is the string ``DER'' or ``critical,DER'', then $data$ is an ASN.1-encoded octet string.
399Otherwise, $name$ and $value$ are plain text strings in \href{https://www.openssl.org/docs/apps/x509v3_config.html#ARBITRARY_EXTENSIONS}{OpenSSL's arbitrary extension format}; and if specified, $data$ is either an OpenSSL configuration string defining any referenced identifiers in $value$, or a table with members:
400
401\begin{ctabular}{ l | l | p{8cm} }
402field & type:default & description\\\hline
403.db & string:$nil$ & OpenSSL configuration string\\
404.issuer & \module{openssl.x509}:$nil$ & issuer certificate\\
405.subject & \module{openssl.x509}:$nil$ & subject certificate\\
406.request & \module{openssl.x509.csr}:$nil$ & certificate signing request\\
407.crl & \module{openssl.x509.crl}:$nil$ & certificate revocation list\\
408.flags & integer:$0$ & a bitwise combination of flags
409\end{ctabular}
393 410
394\subsubsection[\fn{extension.interpose}]{\fn{extension.interpose($name$, $function$)}} 411\subsubsection[\fn{extension.interpose}]{\fn{extension.interpose($name$, $function$)}}
395 412
@@ -528,7 +545,7 @@ Sets the basic constraints critical flag.
528 545
529\subsubsection[\fn{x509:addExtension}]{\fn{x509:addExtension($ext$)}} 546\subsubsection[\fn{x509:addExtension}]{\fn{x509:addExtension($ext$)}}
530 547
531Adds a copy of the \module{x509.extension} object to the certificate. 548Adds a copy of the \module{x509.extension} object to the certificate.
532 549
533\subsubsection[\fn{x509:getExtension}]{\fn{x509:getExtension($key$)}} 550\subsubsection[\fn{x509:getExtension}]{\fn{x509:getExtension($key$)}}
534 551
@@ -538,6 +555,10 @@ Returns a copy of the \module{x509.extension} object identified by $key$ where $
538 555
539Returns the integer count of the number of extensions. 556Returns the integer count of the number of extensions.
540 557
558\subsubsection[\fn{x509:getOCSP}]{\fn{x509:getOCSP()}}
559
560Returns the OCSP urls for the certificate.
561
541\subsubsection[\fn{x509:isIssuedBy}]{\fn{x509:isIssuedBy($issuer$)}} 562\subsubsection[\fn{x509:isIssuedBy}]{\fn{x509:isIssuedBy($issuer$)}}
542 563
543Returns a boolean according to whether the specified issuer---an \module{openssl.x509.name} object---signed the instance certificate. 564Returns a boolean according to whether the specified issuer---an \module{openssl.x509.name} object---signed the instance certificate.
@@ -554,6 +575,10 @@ Sets the public key component referenced by the \module{openssl.pkey} object $ke
554 575
555Returns the digest of the public key as a binary string. $type$ is an optional string describing the digest type, and defaults to ``sha1''. 576Returns the digest of the public key as a binary string. $type$ is an optional string describing the digest type, and defaults to ``sha1''.
556 577
578\subsubsection[\fn{x509:getSignatureName}]{\fn{x509:getSignatureName()}}
579
580Returns the type of signature used to sign the certificate as a string. e.g. ``RSA-SHA1''
581
557\subsubsection[\fn{x509:sign}]{\fn{x509:sign($key$ [, $type$])}} 582\subsubsection[\fn{x509:sign}]{\fn{x509:sign($key$ [, $type$])}}
558 583
559Signs 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. 584Signs 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.
@@ -674,7 +699,7 @@ Add the certificate identified by $serial$ to the revocation list. $serial$ shou
674 699
675\subsubsection[\fn{crl:addExtension}]{\fn{crl:addExtension($ext$)}} 700\subsubsection[\fn{crl:addExtension}]{\fn{crl:addExtension($ext$)}}
676 701
677Adds a copy of the \module{x509.extension} object to the revocation list. 702Adds a copy of the \module{x509.extension} object to the revocation list.
678 703
679\subsubsection[\fn{crl:getExtension}]{\fn{crl:getExtension($key$)}} 704\subsubsection[\fn{crl:getExtension}]{\fn{crl:getExtension($key$)}}
680 705
@@ -688,6 +713,10 @@ Returns the integer count of the number of extensions.
688 713
689Signs the instance CRL using the \module{openssl.pkey} $key$. 714Signs the instance CRL using the \module{openssl.pkey} $key$.
690 715
716\subsubsection[\fn{crl:verify}]{\fn{crl:verify($publickey$)}}
717
718Verifies the instance CRL using a public key.
719
691\subsubsection[\fn{crl:text}]{\fn{crl:text()}} 720\subsubsection[\fn{crl:text}]{\fn{crl:text()}}
692 721
693Returns a human-readable textual representation of the instance CRL. 722Returns a human-readable textual representation of the instance CRL.
@@ -763,6 +792,10 @@ Add or interpose a store class method. Returns the previous method, if any.
763 792
764Returns a PKCS \#12 binary encoded string. 793Returns a PKCS \#12 binary encoded string.
765 794
795\subsubsection[\fn{pkcs12.parse}]{\fn{pkcs12.parse($bag$[, $passphrase$])}}
796
797Parses a PKCS\#12 bag, presented as a binary string $bag$. The second parameter $passphrase$ is the passphrase required to decrypt the PKCS\#12 bag. The function returns three items; namely the key, certificate and the CA chain, as their respective objects. If an item is absent, it will be substituted with nil.
798
766\end{Module} 799\end{Module}
767 800
768 801
@@ -781,7 +814,7 @@ Returns a new context object. $protocol$ is an optional string identifier select
781\begin{ctabular}{ c | p{14cm} } 814\begin{ctabular}{ c | p{14cm} }
782\multicolumn{2}{c}{$protocol$ identifiers}\\\hline\hline 815\multicolumn{2}{c}{$protocol$ identifiers}\\\hline\hline
783name & \href{https://www.openssl.org/docs/ssl/SSL_CTX_new.html}{description} \\\hline 816name & \href{https://www.openssl.org/docs/ssl/SSL_CTX_new.html}{description} \\\hline
784TLS & Supports TLS 1.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 and 817TLS & Supports TLS 1.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 and
785SSLv3 using \texttt{SSL\_OP\_NO\_SSLv2} and \texttt{SSL\_OP\_NO\_SSLv3}.\\ 818SSLv3 using \texttt{SSL\_OP\_NO\_SSLv2} and \texttt{SSL\_OP\_NO\_SSLv3}.\\
786 819
787SSL & Supports SSL 3.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 using \texttt{SSL\_OP\_NO\_SSLv2}.\\ 820SSL & Supports SSL 3.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 using \texttt{SSL\_OP\_NO\_SSLv2}.\\
@@ -853,6 +886,23 @@ Returns the option flags of the context instance as an integer.
853 886
854Clears the option flags of the context instance. 887Clears the option flags of the context instance.
855 888
889\subsubsection[\fn{context:setStore}]{\fn{context:setStore($store$)}}
890
891Associate the \module{openssl.x509.store} object $store$ with $context$. Replaces any existing store.
892
893\subsubsection[\fn{context:getStore}]{\fn{context:getStore()}}
894
895Returns the \module{openssl.x509.store} object associated with $context$.
896
897\subsubsection[\fn{context:setParam}]{\fn{context:setParam($params$)}}
898
899Causes $context$ to inherit the parameters from the \module{openssl.x509.verify\_param} object $params$.
900Only parameters set in $params$ will take effect (others will stay unchanged).
901
902\subsubsection[\fn{context:getParam}]{\fn{context:getParam()}}
903
904Returns an \module{openssl.x509.verify\_param} object containing a copy of $context$'s parameters.
905
856\subsubsection[\fn{context:setVerify}]{\fn{context:setVerify([$mode$][, $depth$])}} 906\subsubsection[\fn{context:setVerify}]{\fn{context:setVerify([$mode$][, $depth$])}}
857 907
858Sets the verification mode flags and maximum validation chain depth. 908Sets the verification mode flags and maximum validation chain depth.
@@ -903,6 +953,26 @@ Sets the advertised ALPN protocols. $table$ is an array of protocol string ident
903 953
904\emph{Only supported since OpenSSL 1.0.2.} 954\emph{Only supported since OpenSSL 1.0.2.}
905 955
956\subsubsection[\fn{context:setAlpnSelect}]{\fn{context:setAlpnSelect($cb$)}}
957
958Sets the callback used to select an ALPN protocol. $cb$ should be a function that takes two arguments: an \module{openssl.ssl} object and a table containing a sequence of ALPN protocol strings; it should return the ALPN protocol string it selected or $nil$ to select none of them.
959
960\emph{Only supported since OpenSSL 1.0.2.}
961
962\subsubsection[\fn{context:setTLSextStatusType}]{\fn{context:setTLSextStatusType($type$)}}
963
964Sets the default TLS extension status for SSL objects derived from this context.
965See \fn{ssl:setTLSextStatusType}
966
967\emph{Only supported since OpenSSL 1.1.0.}
968
969\subsubsection[\fn{context:getTLSextStatusType}]{\fn{context:getTLSextStatusType()}}
970
971Gets the default TLS extension status for SSL objects derived from this context as a string.
972See \fn{ssl:getTLSextStatusType}
973
974\emph{Only supported since OpenSSL 1.1.0.}
975
906\end{Module} 976\end{Module}
907 977
908 978
@@ -917,6 +987,10 @@ A table mapping OpenSSL named constants. Includes all constants provided by \mod
917\subsubsection[\fn{ssl.interpose}]{\fn{ssl.interpose($name$, $function$)}} 987\subsubsection[\fn{ssl.interpose}]{\fn{ssl.interpose($name$, $function$)}}
918Add or interpose an ssl class method. Returns the previous method, if any. 988Add or interpose an ssl class method. Returns the previous method, if any.
919 989
990\subsubsection[\fn{ssl:setContext}]{\fn{ssl:setContext($context$)}}
991
992Replaces the \module{openssl.ssl.context} used by $ssl$ with $context$.
993
920\subsubsection[\fn{ssl:setOptions}]{\fn{ssl:setOptions($flags$)}} 994\subsubsection[\fn{ssl:setOptions}]{\fn{ssl:setOptions($flags$)}}
921 995
922Adds the option flags of the SSL connection instance. See \fn{openssl.ssl.context:setOptions}. 996Adds the option flags of the SSL connection instance. See \fn{openssl.ssl.context:setOptions}.
@@ -929,6 +1003,30 @@ Returns the option flags of the SSL connection instance. See \fn{openssl.ssl.con
929 1003
930Clears the option flags of the SSL connection instance. See \fn{openssl.ssl.context:clearOptions}. 1004Clears the option flags of the SSL connection instance. See \fn{openssl.ssl.context:clearOptions}.
931 1005
1006\subsubsection[\fn{ssl:setVerify}]{\fn{ssl:setVerify([$mode$][, $depth$])}}
1007
1008Sets the verification mode flags and maximum validation chain depth.
1009See \fn{openssl.ssl.context:setVerify}.
1010
1011\subsubsection[\fn{ssl:getVerify}]{\fn{ssl:getVerify()}}
1012
1013Returns two values: the bitwise verification mode flags, and the maximum validation depth.
1014See \fn{openssl.ssl.context:getVerify}.
1015
1016\subsubsection[\fn{ssl:getVerifyResult}]{\fn{ssl:getVerifyResult()}}
1017
1018Returns two values: the integer verification result code and the string representation of that code.
1019
1020\subsubsection[\fn{ssl:setCertificate}]{\fn{ssl:setCertificate($crt$)}}
1021
1022Sets the X.509 certificate \module{openssl.x509} object $crt$ to send during SSL connection instance handshakes.
1023See \fn{openssl.ssl.context:setCertificate}.
1024
1025\subsubsection[\fn{ssl:setPrivateKey}]{\fn{ssl:setPrivateKey($key$)}}
1026
1027Sets the private key \module{openssl.pkey} object $key$ for use during SSL connection instance handshakes.
1028See \fn{openssl.ssl.context:setPrivateKey}.
1029
932\subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}} 1030\subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}}
933 1031
934Returns the X.509 peer certificate as an \module{openssl.x509} object. If no peer certificate is available, returns $nil$. 1032Returns the X.509 peer certificate as an \module{openssl.x509} object. If no peer certificate is available, returns $nil$.
@@ -939,7 +1037,7 @@ Similar to :getPeerCertifiate, but returns the entire chain sent by the peer as
939 1037
940\subsubsection[\fn{ssl:getCipherInfo}]{\fn{ssl:getCipherInfo()}} 1038\subsubsection[\fn{ssl:getCipherInfo}]{\fn{ssl:getCipherInfo()}}
941 1039
942Returns a table of information on the current cipher. 1040Returns a table of information on the current cipher.
943 1041
944\begin{tabular}{ c | l } 1042\begin{tabular}{ c | l }
945field & description\\\hline 1043field & description\\\hline
@@ -996,6 +1094,30 @@ Sets the advertised ALPN protocols. $table$ is an array of protocol string ident
996 1094
997\emph{Only supported since OpenSSL 1.0.2.} 1095\emph{Only supported since OpenSSL 1.0.2.}
998 1096
1097\subsubsection[\fn{ssl:setTLSextStatusType}]{\fn{ssl:setTLSextStatusType($type$)}}
1098
1099Sets the TLS extension status.
1100
1101Only the $type$ ``ocsp'' is currently supported, this is used by a client to request that a server sends a stapled OCSP response as part of the TLS handshake.
1102
1103See also: \fn{context:setTLSextStatusType()}
1104
1105\subsubsection[\fn{ssl:getTLSextStatusType}]{\fn{ssl:getTLSextStatusType()}}
1106
1107Gets the TLS extension status. As set by \fn{ssl:setTLSextStatusType} or \fn{context:setTLSextStatusType}.
1108
1109Only the type ``ocsp'' is currently known.
1110
1111\emph{Only supported since OpenSSL 1.1.0.}
1112
1113\subsubsection[\fn{ssl:setTLSextStatusOCSPResp}]{\fn{ssl:setTLSextStatusOCSPResp($or$)}}
1114
1115Sets an \module{openssl.ocsp.response}. Used by a server to staple an OCSP response into a TLS handshake.
1116
1117\subsubsection[\fn{ssl:getTLSextStatusOCSPResp}]{\fn{ssl:getTLSextStatusOCSPResp()}}
1118
1119Returns the \module{openssl.ocsp.response} associated with the ssl object (or $nil$ if one has not been set).
1120
999\end{Module} 1121\end{Module}
1000 1122
1001 1123
@@ -1078,6 +1200,36 @@ Update the cipher with the specified string(s). Returns the final output string
1078\end{Module} 1200\end{Module}
1079 1201
1080 1202
1203\begin{Module}{openssl.ocsp.response}
1204
1205Binds OpenSSL's \texttt{OCSP\_RESPONSE} object.
1206
1207\subsubsection[\fn{response:getBasic}]{\fn{response:getBasic()}}
1208
1209Returns a \module{openssl.ocsp.basic} representation of the object contained within the OCSP response.
1210
1211\subsubsection[\fn{response:tostring}]{\fn{response:tostring()}}
1212
1213Returns a human readable description of the OCSP response as a string.
1214
1215\subsubsection[\fn{response:toPEM}]{\fn{response:toPEM()}}
1216
1217Returns the OCSP response as a PEM encoded string.
1218
1219\end{Module}
1220
1221
1222\begin{Module}{openssl.ocsp.basic}
1223
1224Binds OpenSSL's \texttt{OCSP\_BASICRESP} object.
1225
1226\subsubsection[\fn{basic:verify}]{\fn{basic:verify([$certs$ [, $store$[, $flags$]]])}}
1227
1228Verifies that the OCSP response is signed by a certificate in the \module{openssl.x509.chain} $certs$ or a trusted certificate in \module{openssl.x509.store} $store$.
1229
1230\end{Module}
1231
1232
1081\begin{Module}{openssl.rand} 1233\begin{Module}{openssl.rand}
1082 1234
1083Binds OpenSSL's random number interfaces. 1235Binds OpenSSL's random number interfaces.