README.rst 6.04 KB
Newer Older
1 2 3
..
.. NB:  This file is machine generated, DO NOT EDIT!
..
Nils Goroll's avatar
Nils Goroll committed
4
.. Edit ./vmod_crypto.vcc and run make instead
5 6 7 8 9 10 11 12
..

.. role:: ref(emphasis)

===========
vmod_crypto
===========

Nils Goroll's avatar
Nils Goroll committed
13 14 15
------------------------------------------------------------------
Public Key signature generation and verification for Varnish-Cache
------------------------------------------------------------------
16 17 18 19 20 21

:Manual section: 3

SYNOPSIS
========

Nils Goroll's avatar
Nils Goroll committed
22
.. parsed-literal::
23

Nils Goroll's avatar
Nils Goroll committed
24 25 26 27 28
  import crypto [as name] [from "path"]
  
  new xkey = crypto.key()
  
      BLOB xkey.use()
29
   
Nils Goroll's avatar
Nils Goroll committed
30 31 32 33 34 35 36
      VOID xkey.pem_pubkey(STRING)
   
      VOID xkey.pem_privkey(STRING, STRING password)
   
      VOID xkey.rsa(BLOB n, BLOB e, [BLOB d])
   
  new xverifier = crypto.verifier(ENUM digest, [STRING pem], [BLOB key])
37 38
  
      BOOL xverifier.update(STRING)
Nils Goroll's avatar
Nils Goroll committed
39
   
40
      BOOL xverifier.update_blob(BLOB)
Nils Goroll's avatar
Nils Goroll committed
41
   
42
      BOOL xverifier.reset()
Nils Goroll's avatar
Nils Goroll committed
43
   
44
      BOOL xverifier.valid(BLOB signature)
Nils Goroll's avatar
Nils Goroll committed
45 46
   
  new xsigner = crypto.signer(ENUM digest, [STRING pem], [BLOB key])
47
  
Nils Goroll's avatar
Nils Goroll committed
48 49 50 51 52 53 54 55
      BOOL xsigner.update(STRING)
   
      BOOL xsigner.update_blob(BLOB)
   
      BOOL xsigner.reset()
   
      BLOB xsigner.final()
   
56 57 58 59 60 61 62 63 64 65 66 67 68 69

DESCRIPTION
===========

This vmod provides VCL access to cryptographic functions from the
_crypt_ library.

Example
    ::

	import crypto;

	sub vcl_init {
	    new v = crypto.verifier(sha256, {"
Nils Goroll's avatar
Nils Goroll committed
70 71 72 73
	-----BEGIN PUBLIC KEY-----
	...
	-----END PUBLIC KEY-----
	"});
74 75 76 77 78 79 80 81 82 83
	}
	sub vcl_deliver {
	    if (! v.update("data")) {
		return (synth(500, "vmod_crypto error"));
	    }
	    if (! v.valid(blob.encode(BASE64URLNOPAD, "base64"))) {
		return (synth(400, "invalid signature"));
	    }
	}

Nils Goroll's avatar
Nils Goroll committed
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
.. _crypto.key():

new xkey = crypto.key()
-----------------------

Create a generic key object. The algorithm gets defined by the method
called upon it.

Any methods on `crypto.key()`_ may only be used in ``sub vcl_init {}``.

.. _xkey.use():

BLOB xkey.use()
---------------

Wrap the key in a blob to be passed to `crypto.verifier()`_

.. _xkey.pem_pubkey():

VOID xkey.pem_pubkey(STRING)
----------------------------

Create a key from the PEM-encoded public key.

The cryptographic method to be used and the key length are
automatically determined from _pem_. Typically supported methods
comprise RSA and DSA.

Any error is fatal to vcl initialization.

.. _xkey.pem_privkey():

VOID xkey.pem_privkey(STRING, STRING password=0)
------------------------------------------------
118

Nils Goroll's avatar
Nils Goroll committed
119 120
Create a key from the PEM-encoded private key, optionally decrypting
it using `password`.
121

Nils Goroll's avatar
Nils Goroll committed
122 123 124 125 126 127 128 129 130 131
The cryptographic method to be used and the key length are
automatically determined from _pem_. Typically supported methods
comprise RSA and DSA.

Any error is fatal to vcl initialization.

.. _xkey.rsa():

VOID xkey.rsa(BLOB n, BLOB e, [BLOB d])
---------------------------------------
132

Nils Goroll's avatar
Nils Goroll committed
133
Create an RSA key from the parameters n, e, and optionally d.
134

Nils Goroll's avatar
Nils Goroll committed
135 136 137 138 139 140
Any error is fatal to vcl initialization.

.. _crypto.verifier():

new xverifier = crypto.verifier(ENUM digest, [STRING pem], [BLOB key])
----------------------------------------------------------------------
141 142 143

::

Nils Goroll's avatar
Nils Goroll committed
144
   new xverifier = crypto.verifier(
145
      ENUM {md_null, md4, md5, sha1, sha224, sha256, sha384, sha512, ripemd160, rmd160, whirlpool} digest,
Nils Goroll's avatar
Nils Goroll committed
146 147
      [STRING pem],
      [BLOB key]
148 149 150 151 152
   )

Create an object to verify signatures created using _digest_ and
_key_.

Nils Goroll's avatar
Nils Goroll committed
153 154
The _key_ argument should be a call to `xkey.use()`_ on the respective
`crypto.key()`_ object.
155

Nils Goroll's avatar
Nils Goroll committed
156 157 158
Alternatively to _key_, the _pem_ argument may be used to pass a
PEM-encoded public key specification. Use of the _pem_ argument is
deprecated.
159

Nils Goroll's avatar
Nils Goroll committed
160 161 162
Either the _key_ or the _pem_ argument must be given.

.. _xverifier.update():
163 164 165 166 167 168

BOOL xverifier.update(STRING)
-----------------------------

Add strings to the data to be verfied with the verifier object.

Nils Goroll's avatar
Nils Goroll committed
169
.. _xverifier.update_blob():
170 171 172 173 174 175

BOOL xverifier.update_blob(BLOB)
--------------------------------

Add a blob to the data to be verified with the verifier object.

Nils Goroll's avatar
Nils Goroll committed
176
.. _xverifier.reset():
177 178 179 180 181 182 183

BOOL xverifier.reset()
----------------------

Reset the verfication state as if previous calls to the update methods
had not happened.

Nils Goroll's avatar
Nils Goroll committed
184
.. _xverifier.valid():
185 186 187 188 189 190 191 192 193 194 195

BOOL xverifier.valid(BLOB signature)
------------------------------------

Check if _signature_ is a valid signature for the _verifier_ object
given the previous updates.

Note that after calling .valid(), .update can be called again to add
additional data, which can then be validated against a (different)
signature using another call to .valid().

Nils Goroll's avatar
Nils Goroll committed
196
.. _crypto.signer():
197

Nils Goroll's avatar
Nils Goroll committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
new xsigner = crypto.signer(ENUM digest, [STRING pem], [BLOB key])
------------------------------------------------------------------

::

   new xsigner = crypto.signer(
      ENUM {md_null, md4, md5, sha1, sha224, sha256, sha384, sha512, ripemd160, rmd160, whirlpool} digest,
      [STRING pem],
      [BLOB key]
   )

Create an object to create signatures using _digest_ and _key_.

The _key_ argument should be a call to `xkey.use()`_ on the respective
`crypto.key()`_ private key object.

Alternatively to _key_, the _pem_ argument may be used to pass a
PEM-encoded private key specification. Password protection is not
supported with a _pem_ argument. Use of the _pem_ argument is
deprecated.

Either the _key_ or the _pem_ argument must be given.

.. _xsigner.update():

BOOL xsigner.update(STRING)
---------------------------

Add strings to the data to be signed.
227

Nils Goroll's avatar
Nils Goroll committed
228
.. _xsigner.update_blob():
229

Nils Goroll's avatar
Nils Goroll committed
230 231
BOOL xsigner.update_blob(BLOB)
------------------------------
232

Nils Goroll's avatar
Nils Goroll committed
233
Add a blob to the data to be signed.
234

Nils Goroll's avatar
Nils Goroll committed
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
.. _xsigner.reset():

BOOL xsigner.reset()
--------------------

Reset the signer state as if previous calls to the update methods had
not happened.

.. _xsigner.final():

BLOB xsigner.final()
--------------------

Return the signature for data added using `xsigner.update()` and
`xsigner.update_blob()`.

Note that after calling `xsigner.final()`,
`xsigner.update()`/`xsigner.update_blob()` can be called again to add
additional data, and more signatures can be generated with
`xsigner.final()`.

SEE ALSO
========vcl\(7),varnishd\(1)
258 259 260 261 262 263

COPYRIGHT
=========

::

Nils Goroll's avatar
Nils Goroll committed
264
  Copyright 2018,2021 UPLEX Nils Goroll Systemoptimierung
265 266 267 268 269 270
  All rights reserved
 
  Author: Nils Goroll <nils.goroll@uplex.de>
 
  See LICENSE