summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorwilliam <william@25tandclement.com>2014-03-27 21:39:36 -0700
committerwilliam <william@25tandclement.com>2014-03-27 21:39:36 -0700
commitb2ca9062bc95ff7bc822a330f1d9f597ec95b770 (patch)
tree3737fab9590d55b9e0ea78063069c688c89ac065 /doc
parentc417a815cacfbe832ed27a997934dfd06a5ca44a (diff)
downloadluaossl-b2ca9062bc95ff7bc822a330f1d9f597ec95b770.tar.gz
luaossl-b2ca9062bc95ff7bc822a330f1d9f597ec95b770.tar.bz2
luaossl-b2ca9062bc95ff7bc822a330f1d9f597ec95b770.zip
update user guide to document DER support, GEN_DIRNAME, and return value changes for :all, digest:update, and hmac:update
Diffstat (limited to 'doc')
-rw-r--r--doc/luaossl.tex222
1 files changed, 112 insertions, 110 deletions
diff --git a/doc/luaossl.tex b/doc/luaossl.tex
index 0aac6c3..5bdc67d 100644
--- a/doc/luaossl.tex
+++ b/doc/luaossl.tex
@@ -221,11 +221,11 @@ Install Lua 5.3 module.
221 221
222\module{openssl.bignum} binds OpenSSL's libcrypto bignum library. It supports all the standard arithmetic operations. Regular number operands in a mixed arithmetic expression are upgraded as-if \method{bignum.new} was used explicitly. The \fn{\_\_tostring} metamethod generates a decimal encoded represention. 222\module{openssl.bignum} binds OpenSSL's libcrypto bignum library. It supports all the standard arithmetic operations. Regular number operands in a mixed arithmetic expression are upgraded as-if \method{bignum.new} was used explicitly. The \fn{\_\_tostring} metamethod generates a decimal encoded represention.
223 223
224\subsubsection[\fn{bignum.new}]{\fn{bignum.new(number)}} 224\subsubsection[\fn{bignum.new}]{\fn{bignum.new($number$)}}
225 225
226Wraps the sign and integral part of `number' as a bignum object, discarding any fractional part. 226Wraps the sign and integral part of $number$ as a bignum object, discarding any fractional part.
227 227
228\subsubsection[\fn{bignum.interpose}]{\fn{bignum.interpose(name, function)}} 228\subsubsection[\fn{bignum.interpose}]{\fn{bignum.interpose($name$, $function$)}}
229 229
230Add or interpose a bignum class method. Returns the previous method, if any. 230Add or interpose a bignum class method. Returns the previous method, if any.
231 231
@@ -234,11 +234,13 @@ Add or interpose a bignum class method. Returns the previous method, if any.
234 234
235\begin{Module}{openssl.pubkey} 235\begin{Module}{openssl.pubkey}
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.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.
238 238
239\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new(string)}} 239\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new($string$[, $format$])}}
240 240
241Initializes a new pubkey object from the PEM-encoded key in `string'. 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.
242
243On failure throws an error.
242 244
243\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new\{ $\ldots$ \}}} 245\subsubsection[\fn{pubkey.new}]{\fn{pubkey.new\{ $\ldots$ \}}}
244 246
@@ -254,7 +256,7 @@ field & type:default & description\\\hline
254 256
255.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
256\end{ctabular} 258\end{ctabular}
257\subsubsection[\fn{pubkey.interpose}]{\fn{pubkey.interpose(name, function)}} 259\subsubsection[\fn{pubkey.interpose}]{\fn{pubkey.interpose($name$, $function$)}}
258 260
259Add or interpose a pubkey class method. Returns the previous method, if any. 261Add or interpose a pubkey class method. Returns the previous method, if any.
260 262
@@ -262,29 +264,29 @@ Add or interpose a pubkey class method. Returns the previous method, if any.
262 264
263Returns the OpenSSL string identifier for the type of key. 265Returns the OpenSSL string identifier for the type of key.
264 266
265\subsubsection[\fn{pubkey:setPublicKey}]{\fn{pubkey:setPublicKey(string)}} 267\subsubsection[\fn{pubkey:setPublicKey}]{\fn{pubkey:setPublicKey($string$[, $format$])}}
266 268
267Set the public key component to that described by the PEM encoded public key in `string'. 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).
268 270
269\subsubsection[\fn{pubkey:setPrivateKey}]{\fn{pubkey:setPrivateKey(string)}} 271\subsubsection[\fn{pubkey:setPrivateKey}]{\fn{pubkey:setPrivateKey($string$[, $format$])}}
270 272
271Set the private key component to that described by the PEM encoded private key in `string'. 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}.
272 274
273\subsubsection[\fn{pubkey:sign}]{\fn{pubkey:sign(digest)}} 275\subsubsection[\fn{pubkey:sign}]{\fn{pubkey:sign($digest$)}}
274 276
275Sign 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.
276 278
277Returns 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.
278 280
279\subsubsection[\fn{pubkey:verify}]{\fn{pubkey:verify(signature, digest)}} 281\subsubsection[\fn{pubkey:verify}]{\fn{pubkey:verify($signature$, $digest$)}}
280 282
281Verify 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.
282 284
283Returns 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.
284 286
285\subsubsection[\fn{pubkey:toPEM}]{\fn{pubkey:toPEM(which[, which])}} 287\subsubsection[\fn{pubkey:toPEM}]{\fn{pubkey:toPEM($which$[, $which$])}}
286 288
287Returns 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.
288 290
289\end{Module} 291\end{Module}
290 292
@@ -297,13 +299,13 @@ Binds the X.509 distinguished name OpenSSL ASN.1 object, used for representing c
297 299
298Returns an empty name object. 300Returns an empty name object.
299 301
300\subsubsection[\fn{name.interpose}]{\fn{name.interpose(name, function)}} 302\subsubsection[\fn{name.interpose}]{\fn{name.interpose($name$, $function$)}}
301 303
302Add or interpose a name class method. Returns the previous method, if any. 304Add or interpose a name class method. Returns the previous method, if any.
303 305
304\subsubsection[\fn{name:add}]{\fn{name:add(type, value)}} 306\subsubsection[\fn{name:add}]{\fn{name:add($type$, $value$)}}
305 307
306Add a distinguished name component. `type' is the OpenSSL string identifier of the component type---short, long, or OID forms. `value' is the string value of the component. DN components are free-form, and are encoded raw. 308Add a distinguished name component. $type$ is the OpenSSL string identifier of the component type---short, long, or OID forms. $value$ is the string value of the component. DN components are free-form, and are encoded raw.
307 309
308\subsubsection[\fn{name:all}]{\fn{name:all()}} 310\subsubsection[\fn{name:all}]{\fn{name:all()}}
309 311
@@ -332,19 +334,19 @@ Binds the X.509 alternative names (a.k.a ``general names'') OpenSSL ASN.1 object
332 334
333Returns an empty altname object. 335Returns an empty altname object.
334 336
335\subsubsection[\fn{altname.interpose}]{\fn{altname.interpose(name, function)}} 337\subsubsection[\fn{altname.interpose}]{\fn{altname.interpose($name$, $function$)}}
336 338
337Add or interpose an altname class method. Returns the previous method, if any. 339Add or interpose an altname class method. Returns the previous method, if any.
338 340
339\subsubsection[\fn{altname:add}]{\fn{altname:add(type, value)}} 341\subsubsection[\fn{altname:add}]{\fn{altname:add($type$, $value$)}}
340 342
341Add an alternative name. `type' must specify one of the four basic types identified by ``RFC822Name'', ``RFC822'', ``email'', ``UniformResourceIdentifier'', ``URI'', ``DNSName'', ``DNS'', ``IPAddress'', and ``IP''. 343Add an alternative name. $type$ must specify one of the five basic types identified by ``RFC822Name'', ``RFC822'', ``email'', ``UniformResourceIdentifier'', ``URI'', ``DNSName'', ``DNS'', ``IPAddress'', ``IP'', or ``DirName''.
342 344
343`value' is a string acceptable to OpenSSL's sanity checks. For an IP address, `value' must be parseable by the system's \fn{inet\_pton} routine, as IP addresses are stored as raw 4- or 16-byte octets. 345For all types except ``DirName'', $value$ is a string acceptable to OpenSSL's sanity checks. For an IP address, $value$ must be parseable by the system's \fn{inet\_pton} routine, as IP addresses are stored as raw 4- or 16-byte octets. ``DirName'' takes an \module{openssl.x509.name} object.
344 346
345\subsubsection[\fn{name:\_\_pairs}]{\fn{name:\_\_pairs()}} 347\subsubsection[\fn{name:\_\_pairs}]{\fn{name:\_\_pairs()}}
346 348
347Returns a key-value iterator over the alternative names. The key is one of ``email'', ``URI'', ``DNS'', or ``IP''. The value is the string representation of the name. 349Returns a key-value iterator over the alternative names. The key is one of ``email'', ``URI'', ``DNS'', ``IP'', or ``DirName''. The value is the string representation of the name.
348 350
349\end{Module} 351\end{Module}
350 352
@@ -353,11 +355,11 @@ Returns a key-value iterator over the alternative names. The key is one of ``ema
353 355
354Binds the X.509 certificate OpenSSL ASN.1 object. 356Binds the X.509 certificate OpenSSL ASN.1 object.
355 357
356\subsubsection[\fn{x509.new}]{\fn{x509.new([string])}} 358\subsubsection[\fn{x509.new}]{\fn{x509.new([$string$[, $format$]])}}
357 359
358Returns a new x509 object, optionally initialized to the PEM encoded certificate specified by `string'. 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).
359 361
360\subsubsection[\fn{x509.interpose}]{\fn{x509.interpose(name, function)}} 362\subsubsection[\fn{x509.interpose}]{\fn{x509.interpose($name$, $function$)}}
361 363
362Add or interpose an x509 class method. Returns the previous method, if any. 364Add or interpose an x509 class method. Returns the previous method, if any.
363 365
@@ -365,7 +367,7 @@ Add or interpose an x509 class method. Returns the previous method, if any.
365 367
366Returns the X.509 version of the certificate. 368Returns the X.509 version of the certificate.
367 369
368\subsubsection[\fn{x509:setVersion}]{\fn{x509:setVersion(number)}} 370\subsubsection[\fn{x509:setVersion}]{\fn{x509:setVersion($number$)}}
369 371
370Sets the X.509 version of the certificate. 372Sets the X.509 version of the certificate.
371 373
@@ -373,27 +375,27 @@ Sets the X.509 version of the certificate.
373 375
374Returns the serial of the certificate as an \module{openssl.bignum}. 376Returns the serial of the certificate as an \module{openssl.bignum}.
375 377
376\subsubsection[\fn{x509:setSerial}]{\fn{x509:setSerial(number)}} 378\subsubsection[\fn{x509:setSerial}]{\fn{x509:setSerial($number$)}}
377 379
378Sets the serial of the certificate. `number' is a Lua or \module{openssl.bignum} number. 380Sets the serial of the certificate. $number$ is a Lua or \module{openssl.bignum} number.
379 381
380\subsubsection[\fn{x509:digest}]{\fn{x509:digest([type[, format]])}} 382\subsubsection[\fn{x509:digest}]{\fn{x509:digest([$type$[, $format$]])}}
381 383
382Returns the cryptographic one-way message digest of the certificate. `type' is the OpenSSL string identifier of the hash type---e.g. ``md5'', ``sha1'' (default), ``sha256'', etc. `format' specifies the representation of the digest---``s'' for an octet string, ``x'' for a hexadecimal string (default), and ``n'' for an \module{openssl.bignum} number. 384Returns the cryptographic one-way message digest of the certificate. $type$ is the OpenSSL string identifier of the hash type---e.g. ``md5'', ``sha1'' (default), ``sha256'', etc. $format$ specifies the representation of the digest---``s'' for an octet string, ``x'' for a hexadecimal string (default), and ``n'' for an \module{openssl.bignum} number.
383 385
384\subsubsection[\fn{x509:getLifetime}]{\fn{x509:getLifetime()}} 386\subsubsection[\fn{x509:getLifetime}]{\fn{x509:getLifetime()}}
385 387
386Returns the certificate validity ``Not Before'' and ``Not After'' dates as two Unix timestamp numbers. 388Returns the certificate validity ``Not Before'' and ``Not After'' dates as two Unix timestamp numbers.
387 389
388\subsubsection[\fn{x509:setLifetime}]{\fn{x509:setLifetime([notbefore][, notafter])}} 390\subsubsection[\fn{x509:setLifetime}]{\fn{x509:setLifetime([$notbefore$][, $notafter$])}}
389 391
390Sets the certificate validity dates. A nil value leaves the particular date unchanged. 392Sets the certificate validity dates. $notbefore$ and $notafter$ should be UNIX timestamps. A nil value leaves the particular date unchanged.
391 393
392\subsubsection[\fn{x509:getIssuer}]{\fn{x509:getIssuer()}} 394\subsubsection[\fn{x509:getIssuer}]{\fn{x509:getIssuer()}}
393 395
394Returns the issuer distinguished name as an \module{x509.name} object. 396Returns the issuer distinguished name as an \module{x509.name} object.
395 397
396\subsubsection[\fn{x509:setIssuer}]{\fn{x509:setIssuer(name)}} 398\subsubsection[\fn{x509:setIssuer}]{\fn{x509:setIssuer($name$)}}
397 399
398Sets the issuer distinguished name. 400Sets the issuer distinguished name.
399 401
@@ -401,7 +403,7 @@ Sets the issuer distinguished name.
401 403
402Returns the subject distinguished name as an \module{x509.name} object. 404Returns the subject distinguished name as an \module{x509.name} object.
403 405
404\subsubsection[\fn{x509:setSubject}]{\fn{x509:setSubject(name)}} 406\subsubsection[\fn{x509:setSubject}]{\fn{x509:setSubject($name$)}}
405 407
406Sets the subject distinguished name. 408Sets the subject distinguished name.
407 409
@@ -409,7 +411,7 @@ Sets the subject distinguished name.
409 411
410Returns the issuer alternative names as an \module{x509.altname} object. 412Returns the issuer alternative names as an \module{x509.altname} object.
411 413
412\subsubsection[\fn{x509:setIssuerAlt}]{\fn{x509:setIssuer(altname)}} 414\subsubsection[\fn{x509:setIssuerAlt}]{\fn{x509:setIssuer($altname$)}}
413 415
414Sets the issuer alternative names. 416Sets the issuer alternative names.
415 417
@@ -417,7 +419,7 @@ Sets the issuer alternative names.
417 419
418Returns the subject alternative names as an \module{x509.name} object. 420Returns the subject alternative names as an \module{x509.name} object.
419 421
420\subsubsection[\fn{x509:setSubjectAlt}]{\fn{x509:setSubjectAlt(name)}} 422\subsubsection[\fn{x509:setSubjectAlt}]{\fn{x509:setSubjectAlt($name$)}}
421 423
422Sets the subject alternative names. 424Sets the subject alternative names.
423 425
@@ -425,7 +427,7 @@ Sets the subject alternative names.
425 427
426Returns the issuer alternative names critical flag as a boolean. 428Returns the issuer alternative names critical flag as a boolean.
427 429
428\subsubsection[\fn{x509:setIssuerAltCritical}]{\fn{x509:setIssuerAltCritical(boolean)}} 430\subsubsection[\fn{x509:setIssuerAltCritical}]{\fn{x509:setIssuerAltCritical($boolean$)}}
429 431
430Sets the issuer alternative names critical flag. 432Sets the issuer alternative names critical flag.
431 433
@@ -433,13 +435,13 @@ Sets the issuer alternative names critical flag.
433 435
434Returns the subject alternative names critical flag as a boolean. 436Returns the subject alternative names critical flag as a boolean.
435 437
436\subsubsection[\fn{x509:setSubjectAltCritical}]{\fn{x509:setSubjectAltCritical(boolean)}} 438\subsubsection[\fn{x509:setSubjectAltCritical}]{\fn{x509:setSubjectAltCritical($boolean$)}}
437 439
438Sets the subject alternative names critical flag. 440Sets the subject alternative names critical flag.
439 441
440\subsubsection[\fn{x509:getBasicConstraints}]{\fn{x509:getBasicConstraints([which[, which $\ldots$ ]])}} 442\subsubsection[\fn{x509:getBasicConstraints}]{\fn{x509:getBasicConstraints([$which$[, $which$ $\ldots$ ]])}}
441 443
442Returns the X.509 ``basic constraint'' flags. If specified, `which' should be one of ``CA'' or ``pathLen'', which returns the specified constraint---respectively, a boolean and a number. If no parameters are specified, returns a table with fields ``CA'' and ``pathLen''. 444Returns the X.509 `basic constraint' flags. If specified, $which$ should be one of ``CA'' or ``pathLen'', which returns the specified constraint---respectively, a boolean and a number. If no parameters are specified, returns a table with fields ``CA'' and ``pathLen''.
443 445
444\subsubsection[\fn{x509:setBasicConstraints}]{\fn{x509:setBasicConstraints\{ $\ldots$ \}}} 446\subsubsection[\fn{x509:setBasicConstraints}]{\fn{x509:setBasicConstraints\{ $\ldots$ \}}}
445 447
@@ -449,25 +451,25 @@ Sets the basic constraint flag according to the defined field values for ``CA''
449 451
450Returns the basic constraints critical flag as a boolean. 452Returns the basic constraints critical flag as a boolean.
451 453
452\subsubsection[\fn{x509:setBasicConstraintsCritical}]{\fn{x509:setBasicConstraintsCritical(boolean)}} 454\subsubsection[\fn{x509:setBasicConstraintsCritical}]{\fn{x509:setBasicConstraintsCritical($boolean$)}}
453 455
454Sets the basic constraints critical flag. 456Sets the basic constraints critical flag.
455 457
456\subsubsection[\fn{x509:isIssuedBy}]{\fn{x509:isIssuedBy(issuer)}} 458\subsubsection[\fn{x509:isIssuedBy}]{\fn{x509:isIssuedBy($issuer$)}}
457 459
458Returns a boolean according to whether the specified issuer---an \module{openssl.x509} object---signed the instance certificate. 460Returns a boolean according to whether the specified issuer---an \module{openssl.x509.name} object---signed the instance certificate.
459 461
460\subsubsection[\fn{x509:getPublicKey}]{\fn{x509:getPublicKey()}} 462\subsubsection[\fn{x509:getPublicKey}]{\fn{x509:getPublicKey()}}
461 463
462Returns the public key component as an \module{openssl.pubkey} object. 464Returns the public key component as an \module{openssl.pubkey} object.
463 465
464\subsubsection[\fn{x509:setPublicKey}]{\fn{x509:setPublicKey(key)}} 466\subsubsection[\fn{x509:setPublicKey}]{\fn{x509:setPublicKey($key$)}}
465 467
466Sets the public key component referenced by the \module{openssl.pubkey} object `key'. 468Sets the public key component referenced by the \module{openssl.pubkey} object $key$.
467 469
468\subsubsection[\fn{x509:sign}]{\fn{x509:sign(key [, type])}} 470\subsubsection[\fn{x509:sign}]{\fn{x509:sign($key$ [, $type$])}}
469 471
470Signs 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.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.
471 473
472\subsubsection[\fn{x509:\_\_tostring}]{\fn{x509:\_\_tostring}} 474\subsubsection[\fn{x509:\_\_tostring}]{\fn{x509:\_\_tostring}}
473 475
@@ -480,11 +482,11 @@ Returns the PEM encoded representation of the instance certificate.
480 482
481Binds the X.509 certificate signing request OpenSSL ASN.1 object. 483Binds the X.509 certificate signing request OpenSSL ASN.1 object.
482 484
483\subsubsection[\fn{csr.new}]{\fn{csr.new([x509|string])}} 485\subsubsection[\fn{csr.new}]{\fn{csr.new([$x509$|$string$[, $format$]])}}
484 486
485Returns a new request object, optionally initialized to the specified \module{openssl.x509} certificate `x509' or the the PEM encoded certificate signing request `string'. 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).
486 488
487\subsubsection[\fn{csr.interpose}]{\fn{csr.interpose(name, function)}} 489\subsubsection[\fn{csr.interpose}]{\fn{csr.interpose($name$, $function$)}}
488 490
489Add or interpose a request class method. Returns the previous method, if any. 491Add or interpose a request class method. Returns the previous method, if any.
490 492
@@ -492,7 +494,7 @@ Add or interpose a request class method. Returns the previous method, if any.
492 494
493Returns the X.509 version of the request. 495Returns the X.509 version of the request.
494 496
495\subsubsection[\fn{car:setVersion}]{\fn{csr:setVersion(number)}} 497\subsubsection[\fn{car:setVersion}]{\fn{csr:setVersion($number$)}}
496 498
497Sets the X.509 version of the request. 499Sets the X.509 version of the request.
498 500
@@ -500,7 +502,7 @@ Sets the X.509 version of the request.
500 502
501Returns the subject distinguished name as an \module{x509.name} object. 503Returns the subject distinguished name as an \module{x509.name} object.
502 504
503\subsubsection[\fn{csr:setSubject}]{\fn{csr:setSubject(name)}} 505\subsubsection[\fn{csr:setSubject}]{\fn{csr:setSubject($name$)}}
504 506
505Sets the subject distinguished name. 507Sets the subject distinguished name.
506 508
@@ -508,13 +510,13 @@ Sets the subject distinguished name.
508 510
509Returns the public key component as an \module{openssl.pubkey} object. 511Returns the public key component as an \module{openssl.pubkey} object.
510 512
511\subsubsection[\fn{csr:setPublicKey}]{\fn{csr:setPublicKey(key)}} 513\subsubsection[\fn{csr:setPublicKey}]{\fn{csr:setPublicKey($key$)}}
512 514
513Sets the public key component referenced by the \module{openssl.pubkey} object `key'. 515Sets the public key component referenced by the \module{openssl.pubkey} object $key$.
514 516
515\subsubsection[\fn{car:sign}]{\fn{csr:sign(key)}} 517\subsubsection[\fn{car:sign}]{\fn{csr:sign($key$)}}
516 518
517Signs the instance request using the \module{openssl.pubkey} `key'. 519Signs the instance request using the \module{openssl.pubkey} $key$.
518 520
519\subsubsection[\fn{csr:\_\_tostring}]{\fn{csr:\_\_tostring}} 521\subsubsection[\fn{csr:\_\_tostring}]{\fn{csr:\_\_tostring}}
520 522
@@ -531,13 +533,13 @@ Binds the ``STACK\_OF(X509)'' OpenSSL object, principally used in the OpenSSL li
531 533
532Returns a new chain object. 534Returns a new chain object.
533 535
534\subsubsection[\fn{chain.interpose}]{\fn{chain.interpose(name, function)}} 536\subsubsection[\fn{chain.interpose}]{\fn{chain.interpose($name$, $function$)}}
535 537
536Add or interpose a chain class method. Returns the previous method, if any. 538Add or interpose a chain class method. Returns the previous method, if any.
537 539
538\subsubsection[\fn{chain:add}]{\fn{chain:add(x509)}} 540\subsubsection[\fn{chain:add}]{\fn{chain:add($crt$)}}
539 541
540Append the X.509 certificate `x509'. 542Append the X.509 certificate $crt$.
541 543
542\subsubsection[\fn{chain:\_\_ipairs}]{\fn{chain:\_\_ipairs()}} 544\subsubsection[\fn{chain:\_\_ipairs}]{\fn{chain:\_\_ipairs()}}
543 545
@@ -554,17 +556,17 @@ Binds the X.509 certificate ``X509\_STORE'' OpenSSL object, principally used for
554 556
555Returns a new store object. 557Returns a new store object.
556 558
557\subsubsection[\fn{store.interpose}]{\fn{store.interpose(name, function)}} 559\subsubsection[\fn{store.interpose}]{\fn{store.interpose($name$, $function$)}}
558 560
559Add or interpose a store class method. Returns the previous method, if any. 561Add or interpose a store class method. Returns the previous method, if any.
560 562
561\subsubsection[\fn{store:add}]{\fn{store:add(x509|filepath|dirpath)}} 563\subsubsection[\fn{store:add}]{\fn{store:add($crt$|$filepath$|$dirpath$)}}
562 564
563Add the X.509 certificate `x509' to the store, load the certificates from the file `filepath', or set the OpenSSL ``hash dir'' certificate path `dirpath'. 565Add the X.509 certificate $crt$ to the store, load the certificates from the file $filepath$, or set the OpenSSL `hashdir' certificate path $dirpath$.
564 566
565\subsubsection[\fn{store:verify}]{\fn{store:verify(x509[, chain])}} 567\subsubsection[\fn{store:verify}]{\fn{store:verify($crt$[, $chain$])}}
566 568
567Returns two values. The first is a boolean value for whether the specified certificate `x509' 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. The optional parameter `chain' is an \module{openssl.x509.chain} object of untrusted certificates linking the certificate `x509' to one of the trusted certificates in the instance store. 569Returns 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. The optional parameter $chain$ is an \module{openssl.x509.chain} object of untrusted certificates linking the certificate $crt$ to one of the trusted certificates in the instance store.
568 570
569\end{Module} 571\end{Module}
570 572
@@ -587,35 +589,35 @@ VERIFY\_CLIENT\_ONCE & do not request peer certificates after initial handshake
587 589
588See the \href{http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html#NOTES}{NOTES section} in the OpenSSL documentation for \fn{SSL\_CTX\_set\_verify\_mode}. 590See the \href{http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html#NOTES}{NOTES section} in the OpenSSL documentation for \fn{SSL\_CTX\_set\_verify\_mode}.
589 591
590\subsubsection[\fn{context.new}]{\fn{context.new([protocol][, server])}} 592\subsubsection[\fn{context.new}]{\fn{context.new([$protocol$][, $server$])}}
591 593
592Returns a new context object. `protocol' is an optional string identifier selecting the SSL mode---TLSv1 (default), SSLv3, SSLv23, or SSLv2. If `server' is true, then SSL connections instantiated using this context will be placed into server mode, otherwise they behave as clients. 594Returns a new context object. $protocol$ is an optional string identifier selecting the SSL mode---``TLSv1'' (default), ``SSLv3'', ``SSLv23'', or ``SSLv2''. If $server$ is true, then SSL connections instantiated using this context will be placed into server mode, otherwise they behave as clients.
593 595
594\subsubsection[\fn{context.interpose}]{\fn{context.interpose(name, function)}} 596\subsubsection[\fn{context.interpose}]{\fn{context.interpose($name$, $function$)}}
595 597
596Add or interpose a context class method. Returns the previous method, if any. 598Add or interpose a context class method. Returns the previous method, if any.
597 599
598\subsubsection[\fn{context:setStore}]{\fn{context:setStore(store)}} 600\subsubsection[\fn{context:setStore}]{\fn{context:setStore($store$)}}
599 601
600Sets the \module{x509.store} of the context instance. 602Sets the \module{openssl.x509.store} of the context instance.
601 603
602\subsubsection[\fn{context:getVerify}]{\fn{context:getVerify()}} 604\subsubsection[\fn{context:getVerify}]{\fn{context:getVerify()}}
603 605
604Returns two values: the bitwise verification mode flags, and the maximum validation depth. 606Returns two values: the bitwise verification mode flags, and the maximum validation depth.
605 607
606\subsubsection[\fn{context:setVerify}]{\fn{context:setVerify([mode][, depth])}} 608\subsubsection[\fn{context:setVerify}]{\fn{context:setVerify([$mode$][, $depth$])}}
607 609
608Sets the verification mode flags and maximum validation chain depth. 610Sets the verification mode flags and maximum validation chain depth.
609 611
610\subsubsection[\fn{context:setCertificate}]{\fn{context:setCertificate(x509)}} 612\subsubsection[\fn{context:setCertificate}]{\fn{context:setCertificate($crt$)}}
611 613
612Sets the X.509 certificate \module{openssl.x509} object `x509' to send during SSL connection instance handshakes. 614Sets the X.509 certificate \module{openssl.x509} object $crt$ to send during SSL connection instance handshakes.
613 615
614\subsubsection[\fn{context:setPrivateKey}]{\fn{context:setPrivateKey(key)}} 616\subsubsection[\fn{context:setPrivateKey}]{\fn{context:setPrivateKey($key$)}}
615 617
616Sets the private key \module{openssl.pubkey} object `key' for use during SSL connection instance handshakes. 618Sets the private key \module{openssl.pubkey} object $key$ for use during SSL connection instance handshakes.
617 619
618\subsubsection[\fn{context:setCipherList}]{\fn{context:setCipherList(string)}} 620\subsubsection[\fn{context:setCipherList}]{\fn{context:setCipherList($string$)}}
619 621
620Sets the allowed public key and private key algorithms. The string format is documented in the \href{http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT}{OpenSSL ciphers(1) utility documentation}. 622Sets the allowed public key and private key algorithms. The string format is documented in the \href{http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT}{OpenSSL ciphers(1) utility documentation}.
621 623
@@ -626,17 +628,17 @@ Sets the allowed public key and private key algorithms. The string format is doc
626 628
627Binds the ``SSL'' OpenSSL object, which represents an SSL connection instance. See \method{socket.checktls}. 629Binds the ``SSL'' OpenSSL object, which represents an SSL connection instance. See \method{socket.checktls}.
628 630
629\subsubsection[\fn{ssl.interpose}]{\fn{ssl.interpose(name, function)}} 631\subsubsection[\fn{ssl.interpose}]{\fn{ssl.interpose($name$, $function$)}}
630 632
631Add or interpose an ssl class method. Returns the previous method, if any. 633Add or interpose an ssl class method. Returns the previous method, if any.
632 634
633\subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}} 635\subsubsection[\fn{ssl:getPeerCertificate}]{\fn{ssl:getPeerCertificate()}}
634 636
635Returns the X.509 peer certificate as a \module{cqueues.openssl.x509} object. If no peer certificate is available, returns nil. 637Returns the X.509 peer certificate as an \module{openssl.x509} object. If no peer certificate is available, returns nil.
636 638
637\subsubsection[\fn{ssl:getPeerChain}]{\fn{ssl:getPeerChain()}} 639\subsubsection[\fn{ssl:getPeerChain}]{\fn{ssl:getPeerChain()}}
638 640
639Similar to :getPeerCertifiate, but returns the entire chain sent by the peer as a \module{cqueues.openssl.x509.chain} object. 641Similar to :getPeerCertifiate, but returns the entire chain sent by the peer as an \module{openssl.x509.chain} object.
640 642
641\subsubsection[\fn{ssl:getCipherInfo}]{\fn{ssl:getCipherInfo()}} 643\subsubsection[\fn{ssl:getCipherInfo}]{\fn{ssl:getCipherInfo()}}
642 644
@@ -657,21 +659,21 @@ field & description\\\hline
657 659
658Binds the ``EVP\_MD\_CTX'' OpenSSL object, which represents a cryptographic message digest (i.e. hashing) algorithm instance. 660Binds the ``EVP\_MD\_CTX'' OpenSSL object, which represents a cryptographic message digest (i.e. hashing) algorithm instance.
659 661
660\subsubsection[\fn{digest.interpose}]{\fn{digest.interpose(name, function)}} 662\subsubsection[\fn{digest.interpose}]{\fn{digest.interpose($name$, $function$)}}
661 663
662Add or interpose a digest class method. Returns the previous method, if any. 664Add or interpose a digest class method. Returns the previous method, if any.
663 665
664\subsubsection[\fn{digest.new}]{\fn{digest.new([type])}} 666\subsubsection[\fn{digest.new}]{\fn{digest.new([$type$])}}
665 667
666Return a new digest instance using the specified algorithm `type'. `type' is a string suitable for passing to the OpenSSL routine EVP\_get\_digestbyname, and defaults to ``sha1''. 668Return a new digest instance using the specified algorithm $type$. $type$ is a string suitable for passing to the OpenSSL routine EVP\_get\_digestbyname, and defaults to ``sha1''.
667 669
668\subsubsection[\fn{digest:update}]{\fn{digest:update([string [, ...]])}} 670\subsubsection[\fn{digest:update}]{\fn{digest:update([$string$ [, ...]])}}
669 671
670Update the digest with the specified strings. Returns true. 672Update the digest with the specified string(s). Returns the digest object.
671 673
672\subsubsection[\fn{digest:final}]{\fn{digest:final([string [, ...]])}} 674\subsubsection[\fn{digest:final}]{\fn{digest:final([$string$ [, ...]])}}
673 675
674Update the digest with the specified strings. Returns the final message digest as a binary string. 676Update the digest with the specified string(s). Returns the final message digest as a binary string.
675 677
676\end{Module} 678\end{Module}
677 679
@@ -680,21 +682,21 @@ Update the digest with the specified strings. Returns the final message digest a
680 682
681Binds the ``HMAC\_CTX'' OpenSSL object, which represents a cryptographic HMAC algorithm instance. 683Binds the ``HMAC\_CTX'' OpenSSL object, which represents a cryptographic HMAC algorithm instance.
682 684
683\subsubsection[\fn{hmac.interpose}]{\fn{hmac.interpose(name, function)}} 685\subsubsection[\fn{hmac.interpose}]{\fn{hmac.interpose($name$, $function$)}}
684 686
685Add or interpose an HMAC class method. Returns the previous method, if any. 687Add or interpose an HMAC class method. Returns the previous method, if any.
686 688
687\subsubsection[\fn{hmac.new}]{\fn{hmac.new(key [, type])}} 689\subsubsection[\fn{hmac.new}]{\fn{hmac.new($key$ [, $type$])}}
688 690
689Return a new HMAC instance using the specified `key' and `type'. `key' is the secret used for HMAC authentication. `type' is a string suitable for passing to the OpenSSL routine EVP\_get\_digestbyname, and defaults to ``sha1''. 691Return a new HMAC instance using the specified $key$ and $type$. $key$ is the secret used for HMAC authentication. $type$ is a string suitable for passing to the OpenSSL routine EVP\_get\_digestbyname, and defaults to ``sha1''.
690 692
691\subsubsection[\fn{hmac:update}]{\fn{hmac:update([string [, ...]])}} 693\subsubsection[\fn{hmac:update}]{\fn{hmac:update([$string$ [, ...]])}}
692 694
693Update the HMAC with the specified strings. Returns true. 695Update the HMAC with the specified string(s). Returns the HMAC object.
694 696
695\subsubsection[\fn{hmac:final}]{\fn{hmac:final([string [, ...]])}} 697\subsubsection[\fn{hmac:final}]{\fn{hmac:final([$string$ [, ...]])}}
696 698
697Update the HMAC with the specified strings. Returns the final HMAC checksum as a binary string. 699Update the HMAC with the specified string(s). Returns the final HMAC checksum as a binary string.
698 700
699\end{Module} 701\end{Module}
700 702
@@ -703,31 +705,31 @@ Update the HMAC with the specified strings. Returns the final HMAC checksum as a
703 705
704Binds the ``EVP\_CIPHER\_CTX'' OpenSSL object, which represents a cryptographic cipher instance. 706Binds the ``EVP\_CIPHER\_CTX'' OpenSSL object, which represents a cryptographic cipher instance.
705 707
706\subsubsection[\fn{cipher.interpose}]{\fn{cipher.interpose(name, function)}} 708\subsubsection[\fn{cipher.interpose}]{\fn{cipher.interpose($name$, $function$)}}
707 709
708Add or interpose a cipher class method. Returns the previous method, if any. 710Add or interpose a cipher class method. Returns the previous method, if any.
709 711
710\subsubsection[\fn{cipher.new}]{\fn{cipher.new(type)}} 712\subsubsection[\fn{cipher.new}]{\fn{cipher.new($type$)}}
711 713
712Return a new, uninitialized cipher instance. `type' is a string suitable for passing to the OpenSSL routine EVP\_get\_cipherbyname, typically of a form similar to ``AES-128-CBC''. 714Return a new, uninitialized cipher instance. $type$ is a string suitable for passing to the OpenSSL routine EVP\_get\_cipherbyname, typically of a form similar to ``AES-128-CBC''.
713 715
714The cipher is uninitialized because some algorithms support or require additional \textit{ad hoc} parameters before key initialization. The API still allows one-shot encryption like ``cipher.new(type):encrypt(key, iv):final(plaintext)''. 716The cipher is uninitialized because some algorithms support or require additional \textit{ad hoc} parameters before key initialization. The API still allows one-shot encryption like ``cipher.new(type):encrypt(key, iv):final(plaintext)''.
715 717
716\subsubsection[\fn{cipher:encrypt}]{\fn{cipher:encrypt(key [, iv] [, padding])}} 718\subsubsection[\fn{cipher:encrypt}]{\fn{cipher:encrypt($key$ [, $iv$] [, $padding$])}}
717 719
718Initialize the cipher in encryption mode. `key' and `iv' are binary strings with lengths equal to that required by the cipher instance as configured. In other words, key stretching and other transformations must be done explicitly. If the mode does not take an IV or equivalent, such as in ECB mode, then it may be nil. `padding' is a boolean which controls whether PKCS padding is applied, and defaults to true. Returns the cipher instance. 720Initialize the cipher in encryption mode. $key$ and $iv$ are binary strings with lengths equal to that required by the cipher instance as configured. In other words, key stretching and other transformations must be done explicitly. If the mode does not take an IV or equivalent, such as in ECB mode, then it may be nil. $padding$ is a boolean which controls whether PKCS padding is applied, and defaults to true. Returns the cipher instance.
719 721
720\subsubsection[\fn{cipher:decrypt}]{\fn{cipher:decrypt(key [, iv] [, padding])}} 722\subsubsection[\fn{cipher:decrypt}]{\fn{cipher:decrypt($key$ [, $iv$] [, $padding$])}}
721 723
722Initialize the cipher in decryption mode. `key', `iv', and `padding' are as described in :encrypt. Returns the cipher instance. 724Initialize the cipher in decryption mode. $key$, $iv$, and $padding$ are as described in \fn{:encrypt}. Returns the cipher instance.
723 725
724\subsubsection[\fn{cipher:update}]{\fn{cipher:update([string [, ...]])}} 726\subsubsection[\fn{cipher:update}]{\fn{cipher:update([$string$ [, ...]])}}
725 727
726Update the cipher instance with the specified strings. Returns a string on success, or nil and an error message on failure. The returned string may be empty if no blocks can be flushed. 728Update the cipher instance with the specified string(s). Returns a string on success, or nil and an error message on failure. The returned string may be empty if no blocks can be flushed.
727 729
728\subsubsection[\fn{cipher:final}]{\fn{cipher:final([string [, ...]])}} 730\subsubsection[\fn{cipher:final}]{\fn{cipher:final([$string$ [, ...]])}}
729 731
730Update the cipher with the specified strings. Returns the final output string on success, or nil and an error message on failure. The returned string may be empty if all blocks have already been flushed in prior :update calls. 732Update the cipher with the specified string(s). Returns the final output string on success, or nil and an error message on failure. The returned string may be empty if all blocks have already been flushed in prior \fn{:update} calls.
731 733
732\end{Module} 734\end{Module}
733 735
@@ -738,9 +740,9 @@ Binds OpenSSL's random number interfaces.
738 740
739OpenSSL will automatically attempt to seed itself from the system. The only time this could theoretically fail is if /dev/urandom (or similar) were not visible or could not be opened. This might happen if within a chroot jail, or if a file descriptor limit were reached. 741OpenSSL will automatically attempt to seed itself from the system. The only time this could theoretically fail is if /dev/urandom (or similar) were not visible or could not be opened. This might happen if within a chroot jail, or if a file descriptor limit were reached.
740 742
741\subsubsection[\fn{rand.bytes}]{\fn{rand.bytes(count)}} 743\subsubsection[\fn{rand.bytes}]{\fn{rand.bytes($count$)}}
742 744
743Returns `count' cryptographically-strong bytes as a single string. Throws an error if OpenSSL could not complete the request---e.g. because the CSPRNG could not be seeded. 745Returns $count$ cryptographically-strong bytes as a single string. Throws an error if OpenSSL could not complete the request---e.g. because the CSPRNG could not be seeded.
744 746
745\subsubsection[\fn{rand.ready}]{\fn{rand.ready()}} 747\subsubsection[\fn{rand.ready}]{\fn{rand.ready()}}
746 748
@@ -748,9 +750,9 @@ Returns a boolean describing whether the CSPRNG has been properly seeded.
748 750
749In the default CSPRNG engine this routine will also attempt to seed the system if not already. Because seeding only needs to happen once per process to ensure a successful RAND\_bytes invocation\footnote{At least this appeared to be the case when examining the source code of OpenSSL 1.0.1. See md\_rand.c near line 407---``Once we've had enough initial seeding we don't bother to adjust the entropy count, though, because we're not ambitious to provide *information-theoretic* randomness.''}, it may be prudent to assert on rand:ready() at application startup. 751In the default CSPRNG engine this routine will also attempt to seed the system if not already. Because seeding only needs to happen once per process to ensure a successful RAND\_bytes invocation\footnote{At least this appeared to be the case when examining the source code of OpenSSL 1.0.1. See md\_rand.c near line 407---``Once we've had enough initial seeding we don't bother to adjust the entropy count, though, because we're not ambitious to provide *information-theoretic* randomness.''}, it may be prudent to assert on rand:ready() at application startup.
750 752
751\subsubsection[\fn{rand.uniform}]{\fn{rand.uniform([n])}} 753\subsubsection[\fn{rand.uniform}]{\fn{rand.uniform([$n$])}}
752 754
753Returns a cryptographically strong uniform random integer in the interval $[0, n-1]$. If `n' is omitted, the interval is $[0, 2^{64}-1]$. 755Returns a cryptographically strong uniform random integer in the interval $[0, n-1]$. If $n$ is omitted, the interval is $[0, 2^{64}-1]$.
754 756
755The routine operates internally on 64-bit unsigned integers.\footnote{Actually, \texttt{unsigned long long}.} Because neither Lua 5.1 nor 5.2 support 64-bit integers, it's probably best to generate numbers that fit the integral range of your Lua implementation. Lua 5.3 is expected to add a new arithmetic type for 64-bit signed integers in two's-complement representation. This new arithmetic type will be used for return values when available. 757The routine operates internally on 64-bit unsigned integers.\footnote{Actually, \texttt{unsigned long long}.} Because neither Lua 5.1 nor 5.2 support 64-bit integers, it's probably best to generate numbers that fit the integral range of your Lua implementation. Lua 5.3 is expected to add a new arithmetic type for 64-bit signed integers in two's-complement representation. This new arithmetic type will be used for return values when available.
756 758