readme.pgcrypto

来自「PostgreSQL 8.2中增加了很多企业用户所需要的功能和性能上的提高,其开」· PGCRYPTO 代码 · 共 711 行 · 第 1/2 页

5.5.  pgp_pub_decrypt(msg, sec_key [, psw])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  pgp_pub_decrypt(msg bytea, key bytea [, psw text [, options text]] ) \
  RETURNS text
  pgp_pub_decrypt_bytea(msg bytea, key bytea [,psw text [, options text]] ) \
  RETURNS bytea

Decrypt a public-key encrypted message with secret key.  If the secret
key is password-protected, you must give the password in `psw`.  If
there is no password, but you want to specify option for function, you
need to give empty password.

Decrypting bytea data with `pgp_pub_decrypt` is disallowed.
This is to avoid outputting invalid character data.  Decrypting
originally textual data with `pgp_pub_decrypt_bytea` is fine.

Options are described in section 5.8.


5.6.  pgp_key_id(key / msg)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  pgp_key_id(key or msg bytea) RETURNS text

It shows you either key ID if given PGP public or secret key.  Or it
gives the key ID that was used for encrypting the data, if given
encrypted message.

It can return 2 special key IDs:

SYMKEY::
   The data is encrypted with symmetric key.

ANYKEY::
   The data is public-key encrypted, but the key ID is cleared.
   That means you need to try all your secret keys on it to see
   which one decrypts it.  pgcrypto itself does not produce such
   messages.

Note that different keys may have same ID.   This is rare but normal
event.  Client application should then try to decrypt with each one,
to see which fits - like handling ANYKEY.


5.7.  armor / dearmor
~~~~~~~~~~~~~~~~~~~~~~

  armor(data bytea) RETURNS text
  dearmor(data text) RETURNS bytea

Those wrap/unwrap data into PGP Ascii Armor which is basically Base64
with CRC and additional formatting.


5.8.  Options for PGP functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Options are named to be similar to GnuPG.  Values should be given after
an equal sign; separate options from each other with commas.  Example:

  pgp_sym_encrypt(data, psw, 'compress-algo=1, cipher-algo=aes256')

All of the options except `convert-crlf` apply only to encrypt
functions.  Decrypt functions get the parameters from PGP data.

Most interesting options are probably `compression-algo` and
`unicode-mode`.  The rest should have reasonable defaults.


cipher-algo::
  What cipher algorithm to use.

  Values: bf, aes128, aes192, aes256 (OpenSSL-only: `3des`, `cast5`)
  Default: aes128
  Applies: pgp_sym_encrypt, pgp_pub_encrypt

compress-algo::
  Which compression algorithm to use.  Needs building with zlib.

  Values:
    0 - no compression
    1 - ZIP compression
    2 - ZLIB compression [=ZIP plus meta-data and block-CRC's]
  Default: 0
  Applies: pgp_sym_encrypt, pgp_pub_encrypt

compress-level::
  How much to compress.  Bigger level compresses smaller but is slower.
  0 disables compression.

  Values: 0, 1-9
  Default: 6
  Applies: pgp_sym_encrypt, pgp_pub_encrypt

convert-crlf::
  Whether to convert `\n` into `\r\n` when encrypting and `\r\n` to `\n`
  when decrypting.  RFC2440 specifies that text data should be stored
  using `\r\n` line-feeds.  Use this to get fully RFC-compliant
  behavior.

  Values: 0, 1
  Default: 0
  Applies: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt

disable-mdc::
  Do not protect data with SHA-1.  Only good reason to use this
  option is to achieve compatibility with ancient PGP products, as the
  SHA-1 protected packet is from upcoming update to RFC2440.  (Currently
  at version RFC2440bis-14.) Recent gnupg.org and pgp.com software
  supports it fine.

  Values: 0, 1
  Default: 0
  Applies: pgp_sym_encrypt, pgp_pub_encrypt

enable-session-key::
  Use separate session key.  Public-key encryption always uses separate
  session key, this is for symmetric-key encryption, which by default
  uses S2K directly.

  Values: 0, 1
  Default: 0
  Applies: pgp_sym_encrypt

s2k-mode::
  Which S2K algorithm to use.

  Values:
    0 - Without salt.  Dangerous!
    1 - With salt but with fixed iteration count.
    3 - Variable iteration count.
  Default: 3
  Applies: pgp_sym_encrypt

s2k-digest-algo::
  Which digest algorithm to use in S2K calculation.

  Values: md5, sha1
  Default: sha1
  Applies: pgp_sym_encrypt

s2k-cipher-algo::
  Which cipher to use for encrypting separate session key.

  Values: bf, aes, aes128, aes192, aes256
  Default: use cipher-algo.
  Applies: pgp_sym_encrypt

unicode-mode::
  Whether to convert textual data from database internal encoding to
  UTF-8 and back.  If your database already is UTF-8, no conversion will
  be done, only the data will be tagged as UTF-8.  Without this option
  it will not be.

  Values: 0, 1
  Default: 0
  Applies: pgp_sym_encrypt, pgp_pub_encrypt


5.9.  Generating keys with GnuPG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generate a new key:

    gpg --gen-key

The preferred key type is "DSA and Elgamal".

For RSA encryption you must create either DSA or RSA sign-only key
as master and then add RSA encryption subkey with `gpg --edit-key`.

List keys:

    gpg --list-secret-keys

Export ascii-armored public key:

    gpg -a --export KEYID > public.key

Export ascii-armored secret key:

    gpg -a --export-secret-keys KEYID > secret.key

You need to use `dearmor()` on them before giving them to
pgp_pub_* functions.  Or if you can handle binary data, you can drop
"-a" from gpg.

For more details see `man gpg`, http://www.gnupg.org/gph/en/manual.html[
The GNU Privacy Handbook] and other docs on http://www.gnupg.org[] site.


5.10.  Limitations of PGP code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- No support for signing.  That also means that it is not checked
  whether the encryption subkey belongs to master key.

- No support for encryption key as master key.  As such practice
  is generally discouraged, it should not be a problem.

- No support for several subkeys.  This may seem like a problem, as this
  is common practice.  On the other hand, you should not use your regular
  GPG/PGP keys with pgcrypto, but create new ones, as the usage scenario
  is rather different.


6.  Raw encryption
-------------------

Those functions only run a cipher over data, they don't have any advanced
features of PGP encryption.  Therefore they have some major problems:

1. They use user key directly as cipher key.
2. They don't provide any integrity checking, to see
   if the encrypted data was modified.
3. They expect that users manage all encryption parameters
   themselves, even IV.
4. They don't handle text.

So, with the introduction of PGP encryption, usage of raw
encryption functions is discouraged.


    encrypt(data bytea, key bytea, type text) RETURNS bytea
    decrypt(data bytea, key bytea, type text) RETURNS bytea

    encrypt_iv(data bytea, key bytea, iv bytea, type text) RETURNS bytea
    decrypt_iv(data bytea, key bytea, iv bytea, type text) RETURNS bytea

Encrypt/decrypt data with cipher, padding data if needed.

`type` parameter description in pseudo-noteup:

    algo ['-' mode] ['/pad:' padding]

Supported algorithms:

* `bf`		- Blowfish
* `aes`		- AES (Rijndael-128)

Modes:

* `cbc` - next block depends on previous. (default)
* `ecb` - each block is encrypted separately.
          (for testing only)

Padding:

* `pkcs` - data may be any length (default)
* `none` - data must be multiple of cipher block size.

IV is initial value for mode, defaults to all zeroes.  It is ignored for
ECB.  It is clipped or padded with zeroes if not exactly block size.

So, example:

	encrypt(data, 'fooz', 'bf')

is equal to

	encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')


7.  Random bytes
-----------------

    gen_random_bytes(count integer)

Returns `count` cryptographically strong random bytes as bytea value.
There can be maximally 1024 bytes extracted at a time.  This is to avoid
draining the randomness generator pool.


8.  Credits
------------

I have used code from following sources:

`--------------------`-------------------------`-------------------------------
  Algorithm            Author                    Source origin
-------------------------------------------------------------------------------
  DES crypt()          David Burren and others   FreeBSD libcrypt
  MD5 crypt()          Poul-Henning Kamp         FreeBSD libcrypt
  Blowfish crypt()     Solar Designer            www.openwall.com
  Blowfish cipher      Niels Provos              OpenBSD sys/crypto
  Rijndael cipher      Brian Gladman             OpenBSD sys/crypto
  MD5 and SHA1         WIDE Project              KAME kame/sys/crypto
  SHA256/384/512       Aaron D. Gifford          OpenBSD sys/crypto
  BIGNUM math          Michael J. Fromberger     dartmouth.edu/~sting/sw/imath
-------------------------------------------------------------------------------


9.  Legalese
-------------

* I owe a beer to Poul-Henning.
* This product includes software developed by Niels Provos.


10.  References/Links
----------------------

10.1.  Useful reading
~~~~~~~~~~~~~~~~~~~~~~

http://www.gnupg.org/gph/en/manual.html[]::
	The GNU Privacy Handbook

http://www.openwall.com/crypt/[]::
	Describes the crypt-blowfish algorithm.

http://www.stack.nl/~galactus/remailers/passphrase-faq.html[]::
	How to choose good password.

http://world.std.com/~reinhold/diceware.html[]::
	Interesting idea for picking passwords.

http://www.interhack.net/people/cmcurtin/snake-oil-faq.html[]::
	Describes good and bad cryptography.


10.2.  Technical references
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

http://www.ietf.org/rfc/rfc2440.txt[]::
	OpenPGP message format

http://www.imc.org/draft-ietf-openpgp-rfc2440bis[]::
	New version of RFC2440.

http://www.ietf.org/rfc/rfc1321.txt[]::
	The MD5 Message-Digest Algorithm

http://www.ietf.org/rfc/rfc2104.txt[]::
	HMAC: Keyed-Hashing for Message Authentication

http://www.usenix.org/events/usenix99/provos.html[]::
	Comparison of crypt-des, crypt-md5 and bcrypt algorithms.

http://csrc.nist.gov/cryptval/des.htm[]::
	Standards for DES, 3DES and AES.

http://en.wikipedia.org/wiki/Fortuna_(PRNG)[]::
	Description of Fortuna CSPRNG.

http://jlcooke.ca/random/[]::
	Jean-Luc Cooke Fortuna-based /dev/random driver for Linux.

http://www.cs.ut.ee/~helger/crypto/[]::
	Collection of cryptology pointers.


// $PostgreSQL: pgsql/contrib/pgcrypto/README.pgcrypto,v 1.18 2006/09/05 21:26:48 tgl Exp $