diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/luaossl.pdf | bin | 289975 -> 300041 bytes | |||
-rw-r--r-- | doc/luaossl.tex | 162 |
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 | |||
294 | The 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 | ||
293 | Add or interpose a pkey class method. Returns the previous method, if any. | 298 | Add 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 | ||
392 | Returns 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$. | 397 | Returns a new X.509 extension. |
398 | If $value$ is the string ``DER'' or ``critical,DER'', then $data$ is an ASN.1-encoded octet string. | ||
399 | 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 either an OpenSSL configuration string defining any referenced identifiers in $value$, or a table with members: | ||
400 | |||
401 | \begin{ctabular}{ l | l | p{8cm} } | ||
402 | field & 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 | ||
531 | Adds a copy of the \module{x509.extension} object to the certificate. | 548 | Adds 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 | ||
539 | Returns the integer count of the number of extensions. | 556 | Returns the integer count of the number of extensions. |
540 | 557 | ||
558 | \subsubsection[\fn{x509:getOCSP}]{\fn{x509:getOCSP()}} | ||
559 | |||
560 | Returns 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 | ||
543 | Returns a boolean according to whether the specified issuer---an \module{openssl.x509.name} object---signed the instance certificate. | 564 | Returns 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 | ||
555 | Returns the digest of the public key as a binary string. $type$ is an optional string describing the digest type, and defaults to ``sha1''. | 576 | Returns 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 | |||
580 | Returns 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 | ||
559 | 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. | 584 | 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. |
@@ -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 | ||
677 | Adds a copy of the \module{x509.extension} object to the revocation list. | 702 | Adds 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 | ||
689 | Signs the instance CRL using the \module{openssl.pkey} $key$. | 714 | Signs the instance CRL using the \module{openssl.pkey} $key$. |
690 | 715 | ||
716 | \subsubsection[\fn{crl:verify}]{\fn{crl:verify($publickey$)}} | ||
717 | |||
718 | Verifies 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 | ||
693 | Returns a human-readable textual representation of the instance CRL. | 722 | Returns 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 | ||
764 | Returns a PKCS \#12 binary encoded string. | 793 | Returns a PKCS \#12 binary encoded string. |
765 | 794 | ||
795 | \subsubsection[\fn{pkcs12.parse}]{\fn{pkcs12.parse($bag$[, $passphrase$])}} | ||
796 | |||
797 | Parses 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 |
783 | name & \href{https://www.openssl.org/docs/ssl/SSL_CTX_new.html}{description} \\\hline | 816 | name & \href{https://www.openssl.org/docs/ssl/SSL_CTX_new.html}{description} \\\hline |
784 | TLS & Supports TLS 1.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 and | 817 | TLS & Supports TLS 1.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 and |
785 | SSLv3 using \texttt{SSL\_OP\_NO\_SSLv2} and \texttt{SSL\_OP\_NO\_SSLv3}.\\ | 818 | SSLv3 using \texttt{SSL\_OP\_NO\_SSLv2} and \texttt{SSL\_OP\_NO\_SSLv3}.\\ |
786 | 819 | ||
787 | SSL & Supports SSL 3.0 \emph{and above}. Internally uses \fn{SSLv23\_method} and disables SSLv2 using \texttt{SSL\_OP\_NO\_SSLv2}.\\ | 820 | SSL & 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 | ||
854 | Clears the option flags of the context instance. | 887 | Clears the option flags of the context instance. |
855 | 888 | ||
889 | \subsubsection[\fn{context:setStore}]{\fn{context:setStore($store$)}} | ||
890 | |||
891 | Associate the \module{openssl.x509.store} object $store$ with $context$. Replaces any existing store. | ||
892 | |||
893 | \subsubsection[\fn{context:getStore}]{\fn{context:getStore()}} | ||
894 | |||
895 | Returns the \module{openssl.x509.store} object associated with $context$. | ||
896 | |||
897 | \subsubsection[\fn{context:setParam}]{\fn{context:setParam($params$)}} | ||
898 | |||
899 | Causes $context$ to inherit the parameters from the \module{openssl.x509.verify\_param} object $params$. | ||
900 | Only parameters set in $params$ will take effect (others will stay unchanged). | ||
901 | |||
902 | \subsubsection[\fn{context:getParam}]{\fn{context:getParam()}} | ||
903 | |||
904 | Returns 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 | ||
858 | Sets the verification mode flags and maximum validation chain depth. | 908 | Sets 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 | |||
958 | Sets 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 | |||
964 | Sets the default TLS extension status for SSL objects derived from this context. | ||
965 | See \fn{ssl:setTLSextStatusType} | ||
966 | |||
967 | \emph{Only supported since OpenSSL 1.1.0.} | ||
968 | |||
969 | \subsubsection[\fn{context:getTLSextStatusType}]{\fn{context:getTLSextStatusType()}} | ||
970 | |||
971 | Gets the default TLS extension status for SSL objects derived from this context as a string. | ||
972 | See \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$)}} |
918 | Add or interpose an ssl class method. Returns the previous method, if any. | 988 | Add or interpose an ssl class method. Returns the previous method, if any. |
919 | 989 | ||
990 | \subsubsection[\fn{ssl:setContext}]{\fn{ssl:setContext($context$)}} | ||
991 | |||
992 | Replaces 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 | ||
922 | Adds the option flags of the SSL connection instance. See \fn{openssl.ssl.context:setOptions}. | 996 | Adds 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 | ||
930 | Clears the option flags of the SSL connection instance. See \fn{openssl.ssl.context:clearOptions}. | 1004 | Clears 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 | |||
1008 | Sets the verification mode flags and maximum validation chain depth. | ||
1009 | See \fn{openssl.ssl.context:setVerify}. | ||
1010 | |||
1011 | \subsubsection[\fn{ssl:getVerify}]{\fn{ssl:getVerify()}} | ||
1012 | |||
1013 | Returns two values: the bitwise verification mode flags, and the maximum validation depth. | ||
1014 | See \fn{openssl.ssl.context:getVerify}. | ||
1015 | |||
1016 | \subsubsection[\fn{ssl:getVerifyResult}]{\fn{ssl:getVerifyResult()}} | ||
1017 | |||
1018 | Returns 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 | |||
1022 | Sets the X.509 certificate \module{openssl.x509} object $crt$ to send during SSL connection instance handshakes. | ||
1023 | See \fn{openssl.ssl.context:setCertificate}. | ||
1024 | |||
1025 | \subsubsection[\fn{ssl:setPrivateKey}]{\fn{ssl:setPrivateKey($key$)}} | ||
1026 | |||
1027 | Sets the private key \module{openssl.pkey} object $key$ for use during SSL connection instance handshakes. | ||
1028 | See \fn{openssl.ssl.context:setPrivateKey}. | ||
1029 | |||
932 | \subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}} | 1030 | \subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}} |
933 | 1031 | ||
934 | Returns the X.509 peer certificate as an \module{openssl.x509} object. If no peer certificate is available, returns $nil$. | 1032 | Returns 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 | ||
942 | Returns a table of information on the current cipher. | 1040 | Returns a table of information on the current cipher. |
943 | 1041 | ||
944 | \begin{tabular}{ c | l } | 1042 | \begin{tabular}{ c | l } |
945 | field & description\\\hline | 1043 | field & 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 | |||
1099 | Sets the TLS extension status. | ||
1100 | |||
1101 | Only 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 | |||
1103 | See also: \fn{context:setTLSextStatusType()} | ||
1104 | |||
1105 | \subsubsection[\fn{ssl:getTLSextStatusType}]{\fn{ssl:getTLSextStatusType()}} | ||
1106 | |||
1107 | Gets the TLS extension status. As set by \fn{ssl:setTLSextStatusType} or \fn{context:setTLSextStatusType}. | ||
1108 | |||
1109 | Only 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 | |||
1115 | Sets 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 | |||
1119 | Returns 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 | |||
1205 | Binds OpenSSL's \texttt{OCSP\_RESPONSE} object. | ||
1206 | |||
1207 | \subsubsection[\fn{response:getBasic}]{\fn{response:getBasic()}} | ||
1208 | |||
1209 | Returns a \module{openssl.ocsp.basic} representation of the object contained within the OCSP response. | ||
1210 | |||
1211 | \subsubsection[\fn{response:tostring}]{\fn{response:tostring()}} | ||
1212 | |||
1213 | Returns a human readable description of the OCSP response as a string. | ||
1214 | |||
1215 | \subsubsection[\fn{response:toPEM}]{\fn{response:toPEM()}} | ||
1216 | |||
1217 | Returns the OCSP response as a PEM encoded string. | ||
1218 | |||
1219 | \end{Module} | ||
1220 | |||
1221 | |||
1222 | \begin{Module}{openssl.ocsp.basic} | ||
1223 | |||
1224 | Binds OpenSSL's \texttt{OCSP\_BASICRESP} object. | ||
1225 | |||
1226 | \subsubsection[\fn{basic:verify}]{\fn{basic:verify([$certs$ [, $store$[, $flags$]]])}} | ||
1227 | |||
1228 | Verifies 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 | ||
1083 | Binds OpenSSL's random number interfaces. | 1235 | Binds OpenSSL's random number interfaces. |