summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/luaossl.tex60
1 files changed, 30 insertions, 30 deletions
diff --git a/doc/luaossl.tex b/doc/luaossl.tex
index 94ee18e..347c2fe 100644
--- a/doc/luaossl.tex
+++ b/doc/luaossl.tex
@@ -232,19 +232,19 @@ Add or interpose a bignum class method. Returns the previous method, if any.
232\end{Module} 232\end{Module}
233 233
234 234
235\begin{Module}{openssl.pubkey} 235\begin{Module}{openssl.pkey}
236 236
237\module{openssl.pubkey} binds OpenSSL's libcrypto public-private key library. The \fn{\_\_tostring} metamethod generates a PEM encoded representation of the public key---excluding the private key. 237\module{openssl.pkey} binds OpenSSL's libcrypto public-private key library. The \fn{\_\_tostring} metamethod generates a PEM encoded representation of the public key---excluding the private key.
238 238
239\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new($string$[, $format$])}} 239\subsubsection[\fn{pkey.new}]{\fn{pkey.new($string$[, $format$])}}
240 240
241Initializes a new pubkey object from the PEM- or DER-encoded key in $string$. $format$ defaults to ``*'', which means to automatically test the input encoding. If $format$ is explicitly ``PEM'' or ``DER'', then only that decoding format is used. 241Initializes a new pkey object from the PEM- or DER-encoded key in $string$. $format$ defaults to ``*'', which means to automatically test the input encoding. If $format$ is explicitly ``PEM'' or ``DER'', then only that decoding format is used.
242 242
243On failure throws an error. 243On failure throws an error.
244 244
245\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new\{ $\ldots$ \}}} 245\subsubsection[\fn{pkey.new}]{\fn{pkey.new\{ $\ldots$ \}}}
246 246
247Generates a new pubkey object according to the specified parameters. 247Generates a new pkey object according to the specified parameters.
248 248
249\begin{ctabular}{ c | c | p{5in}} 249\begin{ctabular}{ c | c | p{5in}}
250field & type:default & description\\\hline 250field & type:default & description\\\hline
@@ -256,35 +256,35 @@ field & type:default & description\\\hline
256 256
257.curve & string:prime192v1 & for elliptic curve keys, the OpenSSL string identifier of the curve 257.curve & string:prime192v1 & for elliptic curve keys, the OpenSSL string identifier of the curve
258\end{ctabular} 258\end{ctabular}
259\subsubsection[\fn{pubkey.interpose}]{\fn{pubkey.interpose($name$, $function$)}} 259\subsubsection[\fn{pkey.interpose}]{\fn{pkey.interpose($name$, $function$)}}
260 260
261Add or interpose a pubkey class method. Returns the previous method, if any. 261Add or interpose a pkey class method. Returns the previous method, if any.
262 262
263\subsubsection[\fn{pubkey:type}]{\fn{pubkey:type()}} 263\subsubsection[\fn{pkey:type}]{\fn{pkey:type()}}
264 264
265Returns the OpenSSL string identifier for the type of key. 265Returns the OpenSSL string identifier for the type of key.
266 266
267\subsubsection[\fn{pubkey:setPublicKey}]{\fn{pubkey:setPublicKey($string$[, $format$])}} 267\subsubsection[\fn{pkey:setPublicKey}]{\fn{pkey:setPublicKey($string$[, $format$])}}
268 268
269Set the public key component to that described by the PEM- or DER-encoded public key in $string$. $format$ is as described in \fn{openssl.pubkey.new}---``PEM'', ``DER'', or ``*'' (default). 269Set the public key component to that described by the PEM- or DER-encoded public key in $string$. $format$ is as described in \fn{openssl.pkey.new}---``PEM'', ``DER'', or ``*'' (default).
270 270
271\subsubsection[\fn{pubkey:setPrivateKey}]{\fn{pubkey:setPrivateKey($string$[, $format$])}} 271\subsubsection[\fn{pkey:setPrivateKey}]{\fn{pkey:setPrivateKey($string$[, $format$])}}
272 272
273Set the private key component to that described by the PEM encoded private key in $string$. $format$ is as described in \fn{openssl.pubkey.new}. 273Set the private key component to that described by the PEM encoded private key in $string$. $format$ is as described in \fn{openssl.pkey.new}.
274 274
275\subsubsection[\fn{pubkey:sign}]{\fn{pubkey:sign($digest$)}} 275\subsubsection[\fn{pkey:sign}]{\fn{pkey:sign($digest$)}}
276 276
277Sign data which has been consumed by the specified \module{openssl.digest} $digest$. Digests and keys are not all interchangeable. For example, an elliptic curve key requires a digest of type ``ecdsa-with-SHA1'', while DSA requires ``dss1''. OpenSSL supports more varied digests for RSA. 277Sign data which has been consumed by the specified \module{openssl.digest} $digest$. Digests and keys are not all interchangeable. For example, an elliptic curve key requires a digest of type ``ecdsa-with-SHA1'', while DSA requires ``dss1''. OpenSSL supports more varied digests for RSA.
278 278
279Returns the signature as an opaque binary string\footnote{Elliptic curve signatures are two X.509 DER-encoded numbers, for example, while RSA signatures are encrypted DER structures.} on success, and throws an error otherwise. 279Returns the signature as an opaque binary string\footnote{Elliptic curve signatures are two X.509 DER-encoded numbers, for example, while RSA signatures are encrypted DER structures.} on success, and throws an error otherwise.
280 280
281\subsubsection[\fn{pubkey:verify}]{\fn{pubkey:verify($signature$, $digest$)}} 281\subsubsection[\fn{pkey:verify}]{\fn{pkey:verify($signature$, $digest$)}}
282 282
283Verify the string $signature$ as signing the document consumed by \module{openssl.digest} $digest$. See the :sign method for constraints on the format and type of the parameters. 283Verify the string $signature$ as signing the document consumed by \module{openssl.digest} $digest$. See the :sign method for constraints on the format and type of the parameters.
284 284
285Returns true on success, false for properly formatted but invalid signatures, and throws an error otherwise. Because the structure of the signature is opaque and not susceptible to sanity checking before passing to OpenSSL, an application should always be prepared for an error to be thrown when verifying untrusted signatures. OpenSSL, of course, should be able to handle all malformed inputs. But the module does not attempt to differentiate local system errors from errors triggered by malformed signatures because the set of such errors may change in the future. 285Returns true on success, false for properly formatted but invalid signatures, and throws an error otherwise. Because the structure of the signature is opaque and not susceptible to sanity checking before passing to OpenSSL, an application should always be prepared for an error to be thrown when verifying untrusted signatures. OpenSSL, of course, should be able to handle all malformed inputs. But the module does not attempt to differentiate local system errors from errors triggered by malformed signatures because the set of such errors may change in the future.
286 286
287\subsubsection[\fn{pubkey:toPEM}]{\fn{pubkey:toPEM($which$[, $which$])}} 287\subsubsection[\fn{pkey:toPEM}]{\fn{pkey:toPEM($which$[, $which$])}}
288 288
289Returns the PEM encoded string representation(s) of the specified key component. $which$ must be one of ``public'', ``PublicKey'', ``private'', or ``PrivateKey''. For the two argument form, returns two values. 289Returns the PEM encoded string representation(s) of the specified key component. $which$ must be one of ``public'', ``PublicKey'', ``private'', or ``PrivateKey''. For the two argument form, returns two values.
290 290
@@ -357,7 +357,7 @@ Binds the X.509 certificate OpenSSL ASN.1 object.
357 357
358\subsubsection[\fn{x509.new}]{\fn{x509.new([$string$[, $format$]])}} 358\subsubsection[\fn{x509.new}]{\fn{x509.new([$string$[, $format$]])}}
359 359
360Returns a new x509 object, optionally initialized to the PEM- or DER-encoded certificate specified by $string$. $format$ is as described in \fn{openssl.pubkey.new}--``PEM'', ``DER'', or ``*'' (default). 360Returns a new x509 object, optionally initialized to the PEM- or DER-encoded certificate specified by $string$. $format$ is as described in \fn{openssl.pkey.new}--``PEM'', ``DER'', or ``*'' (default).
361 361
362\subsubsection[\fn{x509.interpose}]{\fn{x509.interpose($name$, $function$)}} 362\subsubsection[\fn{x509.interpose}]{\fn{x509.interpose($name$, $function$)}}
363 363
@@ -461,15 +461,15 @@ Returns a boolean according to whether the specified issuer---an \module{openssl
461 461
462\subsubsection[\fn{x509:getPublicKey}]{\fn{x509:getPublicKey()}} 462\subsubsection[\fn{x509:getPublicKey}]{\fn{x509:getPublicKey()}}
463 463
464Returns the public key component as an \module{openssl.pubkey} object. 464Returns the public key component as an \module{openssl.pkey} object.
465 465
466\subsubsection[\fn{x509:setPublicKey}]{\fn{x509:setPublicKey($key$)}} 466\subsubsection[\fn{x509:setPublicKey}]{\fn{x509:setPublicKey($key$)}}
467 467
468Sets the public key component referenced by the \module{openssl.pubkey} object $key$. 468Sets the public key component referenced by the \module{openssl.pkey} object $key$.
469 469
470\subsubsection[\fn{x509:sign}]{\fn{x509:sign($key$ [, $type$])}} 470\subsubsection[\fn{x509:sign}]{\fn{x509:sign($key$ [, $type$])}}
471 471
472Signs and updates the instance certificate using the \module{openssl.pubkey} $key$. $type$ is an optional string describing the digest type. See \module{pubkey: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. 472Signs 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.
473 473
474\subsubsection[\fn{x509:\_\_tostring}]{\fn{x509:\_\_tostring}} 474\subsubsection[\fn{x509:\_\_tostring}]{\fn{x509:\_\_tostring}}
475 475
@@ -484,7 +484,7 @@ Binds the X.509 certificate signing request OpenSSL ASN.1 object.
484 484
485\subsubsection[\fn{csr.new}]{\fn{csr.new([$x509$|$string$[, $format$]])}} 485\subsubsection[\fn{csr.new}]{\fn{csr.new([$x509$|$string$[, $format$]])}}
486 486
487Returns a new request object, optionally initialized to the specified \module{openssl.x509} certificate $x509$ or the PEM- or DER-encoded certificate signing request $string$. $format$ is as described in \fn{openssl.pubkey.new}---``PEM'', ``DER'', or ``*'' (default). 487Returns a new request object, optionally initialized to the specified \module{openssl.x509} certificate $x509$ or the PEM- or DER-encoded certificate signing request $string$. $format$ is as described in \fn{openssl.pkey.new}---``PEM'', ``DER'', or ``*'' (default).
488 488
489\subsubsection[\fn{csr.interpose}]{\fn{csr.interpose($name$, $function$)}} 489\subsubsection[\fn{csr.interpose}]{\fn{csr.interpose($name$, $function$)}}
490 490
@@ -508,15 +508,15 @@ Sets the subject distinguished name.
508 508
509\subsubsection[\fn{csr:getPublicKey}]{\fn{csr:getPublicKey()}} 509\subsubsection[\fn{csr:getPublicKey}]{\fn{csr:getPublicKey()}}
510 510
511Returns the public key component as an \module{openssl.pubkey} object. 511Returns the public key component as an \module{openssl.pkey} object.
512 512
513\subsubsection[\fn{csr:setPublicKey}]{\fn{csr:setPublicKey($key$)}} 513\subsubsection[\fn{csr:setPublicKey}]{\fn{csr:setPublicKey($key$)}}
514 514
515Sets the public key component referenced by the \module{openssl.pubkey} object $key$. 515Sets the public key component referenced by the \module{openssl.pkey} object $key$.
516 516
517\subsubsection[\fn{car:sign}]{\fn{csr:sign($key$)}} 517\subsubsection[\fn{car:sign}]{\fn{csr:sign($key$)}}
518 518
519Signs the instance request using the \module{openssl.pubkey} $key$. 519Signs the instance request using the \module{openssl.pkey} $key$.
520 520
521\subsubsection[\fn{csr:\_\_tostring}]{\fn{csr:\_\_tostring}} 521\subsubsection[\fn{csr:\_\_tostring}]{\fn{csr:\_\_tostring}}
522 522
@@ -615,7 +615,7 @@ Sets the X.509 certificate \module{openssl.x509} object $crt$ to send during SSL
615 615
616\subsubsection[\fn{context:setPrivateKey}]{\fn{context:setPrivateKey($key$)}} 616\subsubsection[\fn{context:setPrivateKey}]{\fn{context:setPrivateKey($key$)}}
617 617
618Sets the private key \module{openssl.pubkey} object $key$ for use during SSL connection instance handshakes. 618Sets the private key \module{openssl.pkey} object $key$ for use during SSL connection instance handshakes.
619 619
620\subsubsection[\fn{context:setCipherList}]{\fn{context:setCipherList($string$)}} 620\subsubsection[\fn{context:setCipherList}]{\fn{context:setCipherList($string$)}}
621 621
@@ -773,13 +773,13 @@ These examples and others are made available under examples/ in the source tree.
773-- specifying subject DN and public key to CAs. See API documentation for 773-- specifying subject DN and public key to CAs. See API documentation for
774-- CSR generation. 774-- CSR generation.
775-- 775--
776local pubkey = require"openssl.pubkey" 776local pkey = require"openssl.pkey"
777local x509 = require"openssl.x509" 777local x509 = require"openssl.x509"
778local name = require"openssl.x509.name" 778local name = require"openssl.x509.name"
779local altname = require"openssl.x509.altname" 779local altname = require"openssl.x509.altname"
780 780
781-- generate our public/private key pair 781-- generate our public/private key pair
782local key = pubkey.new{ type = "EC", curve = "prime192v1" } 782local key = pkey.new{ type = "EC", curve = "prime192v1" }
783 783
784-- our Subject and Issuer DN (self-signed, so same) 784-- our Subject and Issuer DN (self-signed, so same)
785local dn = name.new() 785local dn = name.new()
@@ -828,11 +828,11 @@ io.popen("openssl x509 -text -noout", "w"):write(tostring(crt))
828-- 828--
829-- Example public-key signature verification. 829-- Example public-key signature verification.
830-- 830--
831local pubkey = require"openssl.pubkey" 831local pkey = require"openssl.pkey"
832local digest = require"openssl.digest" 832local digest = require"openssl.digest"
833 833
834-- generate a public/private key pair 834-- generate a public/private key pair
835local key = pubkey.new{ type = "EC", curve = "prime192v1" } 835local key = pkey.new{ type = "EC", curve = "prime192v1" }
836 836
837-- digest our message using an appropriate digest ("ecdsa-with-SHA1" for EC; 837-- digest our message using an appropriate digest ("ecdsa-with-SHA1" for EC;
838-- "dss1" for DSA; and "sha1", "sha256", etc for RSA). 838-- "dss1" for DSA; and "sha1", "sha256", etc for RSA).
@@ -844,7 +844,7 @@ local sig = key:sign(data)
844 844
845-- to prove verification works, instantiate a new object holding just 845-- to prove verification works, instantiate a new object holding just
846-- the public key 846-- the public key
847local pub = pubkey.new(key:toPEM"public") 847local pub = pkey.new(key:toPEM"public")
848 848
849-- a utility routine to output our signature 849-- a utility routine to output our signature
850local function tohex(b) 850local function tohex(b)