digest(data text, type text) returns bytea
digest(data bytea, type text) returns bytea

Computes a binary hash of the given <parameter>data</parameter>. <parameter>type</parameter> is the algorithm to use. Standard algorithms are <literal>md5</literal>, <literal>sha1</literal>, <literal>sha224</literal>, <literal>sha256</literal>, <literal>sha384</literal> and <literal>sha512</literal>. Moreover, any digest algorithm <productname>OpenSSL</productname> supports is automatically picked up. 与えられたdataのバイナリハッシュを計算します。 typeは使用するアルゴリズムです。 標準アルゴリズムはmd5、sha1、sha224、sha256、sha384、およびsha512です。 さらに、OpenSSLがサポートするダイジェストアルゴリズムが自動的に選択されます。

If you want the digest as a hexadecimal string, use <function>encode()</function> on the result. For example: ダイジェストを16進数表記の文字列としたい場合は、結果に対してencode()を使用してください。 以下に例を示します。

CREATE OR REPLACE FUNCTION sha1(bytea) returns text AS $$
    SELECT encode(digest($1, 'sha1'), 'hex')
$$ LANGUAGE SQL STRICT IMMUTABLE;

hmac(data text, key text, type text) returns bytea
hmac(data bytea, key bytea, type text) returns bytea

Calculates hashed MAC for <parameter>data</parameter> with key <parameter>key</parameter>. <parameter>type</parameter> is the same as in <function>digest()</function>. keyをキーとしたdataのハッシュ化MACを計算します。 typeはdigest()の場合と同じです。

This is similar to <function>digest()</function> but the hash can only be recalculated knowing the key. This prevents the scenario of someone altering data and also changing the hash to match. digest()と似ていますが、ハッシュはキーを知っている場合にのみ再計算できます。 これは、誰かがデータを変更し、同時に一致するようにハッシュを変更するという状況を防ぎます。

If the key is larger than the hash block size it will first be hashed and the result will be used as key. キーがハッシュブロックサイズより大きい場合、まずハッシュ化され、その結果をキーとして使用します。

crypt(password text, salt text) returns text

Calculates a crypt(3)-style hash of <parameter>password</parameter>. When storing a new password, you need to use <function>gen_salt()</function> to generate a new <parameter>salt</parameter> value. To check a password, pass the stored hash value as <parameter>salt</parameter>, and test whether the result matches the stored value. passwordのcrypt(3)形式のハッシュを計算します。 新しいパスワードを保管する時には、gen_salt()を使用して新しいsaltを生成する必要があります。 パスワードを検査する時、既存のハッシュ値をsaltとして渡し、結果が格納された値と一致するかどうかを確認します。

Example of setting a new password: 新しいパスワードの設定例を以下に示します。

UPDATE ... SET pswhash = crypt('new password', gen_salt('md5'));

Example of authentication: 認証の例です。

SELECT (pswhash = crypt('entered password', pswhash)) AS pswmatch FROM ... ;

This returns <literal>true</literal> if the entered password is correct. 入力パスワードが正しければtrueを返します。

gen_salt(type text [, iter_count integer ]) returns text

Generates a new random salt string for use in <function>crypt()</function>. The salt string also tells <function>crypt()</function> which algorithm to use. crypt()で使用するランダムなソルト文字列を新規に生成します。 また、このソルト文字列はcrypt()にどのアルゴリズムを使用するかを通知します。

The <parameter>type</parameter> parameter specifies the hashing algorithm. The accepted types are: <literal>des</literal>, <literal>xdes</literal>, <literal>md5</literal> and <literal>bf</literal>. typeパラメータはハッシュ化アルゴリズムを指定します。 受付可能な種類は、des、xdes、md5、bfです。

The <parameter>iter_count</parameter> parameter lets the user specify the iteration count, for algorithms that have one. The higher the count, the more time it takes to hash the password and therefore the more time to break it. Although with too high a count the time to calculate a hash may be several years &mdash; which is somewhat impractical. If the <parameter>iter_count</parameter> parameter is omitted, the default iteration count is used. Allowed values for <parameter>iter_count</parameter> depend on the algorithm and are shown in <xref linkend="pgcrypto-icfc-table"/>. 繰り返し回数を持つアルゴリズムでは、ユーザはiter_countパラメータを使用して繰り返し回数を指定できます。 指定する回数を高くすれば、パスワードのハッシュ化にかかる時間が長くなり、それを破るための時間も長くなります。 しかし、あまりに多くの回数を指定すると、ハッシュ計算にかかる時間は数年に渡ってしまう可能性があります。 これは実用的ではありません。 iter_countパラメータを省略した場合、デフォルトの繰り返し回数が使用されます。 iter_countで受け付けられる値はアルゴリズムに依存し、表 F.18に示す通りです。

For <literal>xdes</literal> there is an additional limitation that the iteration count must be an odd number. xdesの場合は他にも、回数が奇数でなければならないという制限があります。

To pick an appropriate iteration count, consider that the original DES crypt was designed to have the speed of 4 hashes per second on the hardware of that time. Slower than 4 hashes per second would probably dampen usability. Faster than 100 hashes per second is probably too fast. 適切な繰り返し回数を選択するために、元々のDES暗号は当時のハードウェアで1秒あたり4個のハッシュを持つことができるように設計されたことを考えてください。 毎秒4ハッシュより遅いと、おそらく使い勝手が悪いでしょう。 毎秒100ハッシュより速いというのは、十中八九、あまりにも速すぎるでしょう。

<xref linkend="pgcrypto-hash-speed-table"/> gives an overview of the relative slowness of different hashing algorithms. The table shows how much time it would take to try all combinations of characters in an 8-character password, assuming that the password contains either only lower case letters, or upper- and lower-case letters and numbers. In the <literal>crypt-bf</literal> entries, the number after a slash is the <parameter>iter_count</parameter> parameter of <function>gen_salt</function>. ハッシュ化アルゴリズム別に相対的な速度に関する概要を表 F.19にまとめました。 この表は、8文字のパスワード内のすべての文字の組合せを取るためにかかる時間を示します。 また、すべて小文字の英字のみのパスワードである場合と大文字小文字が混在した英字と数字のパスワードの場合を仮定します。 crypt-bfの項では、スラッシュの後の数値はgen_saltのiter_countです。

Notes: 注意：

Note that <quote>try all combinations</quote> is not a realistic exercise. Usually password cracking is done with the help of dictionaries, which contain both regular words and various mutations of them. So, even somewhat word-like passwords could be cracked much faster than the above numbers suggest, while a 6-character non-word-like password may escape cracking. Or not. 「すべての組み合わせを試行する」ことは現実的な行使ではありません。 通常パスワード推定は、普通の単語とその変形の両方を含む辞書を使用して行われます。 ですので、いささかなりとも言葉に似たパスワードは上で示した数値よりも速く推定されます。 また6文字の単語に似ていないパスワードは推定を免れるかもしれませんし、免れないかもしれません。

pgp_sym_encrypt(data text, psw text [, options text ]) returns bytea
pgp_sym_encrypt_bytea(data bytea, psw text [, options text ]) returns bytea

Encrypt <parameter>data</parameter> with a symmetric PGP key <parameter>psw</parameter>. The <parameter>options</parameter> parameter can contain option settings, as described below. 対称PGPキーpswでdataを暗号化します。 optionsパラメータには後述のオプション設定を含めることができます。

pgp_sym_decrypt(msg bytea, psw text [, options text ]) returns text
pgp_sym_decrypt_bytea(msg bytea, psw text [, options text ]) returns bytea

Decrypt a symmetric-key-encrypted PGP message. 対称鍵で暗号化されたPGPメッセージを復号します。

Decrypting <type>bytea</type> data with <function>pgp_sym_decrypt</function> is disallowed. This is to avoid outputting invalid character data. Decrypting originally textual data with <function>pgp_sym_decrypt_bytea</function> is fine. pgp_sym_decryptでbytea型のデータを復号することはできません。 これは無効な文字データの出力を防止するためです。 元のテキストのデータをpgp_sym_decrypt_byteaで復号することが正しい方法です。

The <parameter>options</parameter> parameter can contain option settings, as described below. optionsパラメータには後述のオプション設定を含めることができます。

pgp_pub_encrypt(data text, key bytea [, options text ]) returns bytea
pgp_pub_encrypt_bytea(data bytea, key bytea [, options text ]) returns bytea

Encrypt <parameter>data</parameter> with a public PGP key <parameter>key</parameter>. Giving this function a secret key will produce an error. 公開PGPキーkeyでdataを暗号化します。 この関数に秘密キーを与えるとエラーになります。

The <parameter>options</parameter> parameter can contain option settings, as described below. optionsパラメータには後述のオプション設定を含めることができます。

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. <parameter>key</parameter> must be the secret key corresponding to the public key that was used to encrypt. If the secret key is password-protected, you must give the password in <parameter>psw</parameter>. If there is no password, but you want to specify options, you need to give an empty password. 公開鍵で暗号化されたメッセージを復号します。 keyは、暗号化に使用した公開鍵に対応する秘密鍵でなければなりません。 秘密鍵がパスワードで保護されている場合は、そのパスワードをpswで指定しなければなりません。 パスワードはないが、オプションを指定したい場合は空のパスワードを指定する必要があります。

Decrypting <type>bytea</type> data with <function>pgp_pub_decrypt</function> is disallowed. This is to avoid outputting invalid character data. Decrypting originally textual data with <function>pgp_pub_decrypt_bytea</function> is fine. pgp_pub_decryptでbytea型のデータを復号することはできません。 これは無効な文字データの出力を防止するためです。 元のテキストのデータをpgp_pub_decrypt_byteaで復号することが正しい方法です。

The <parameter>options</parameter> parameter can contain option settings, as described below. optionsパラメータには後述のオプション設定を含めることができます。

pgp_key_id(bytea) returns text

<function>pgp_key_id</function> extracts the key ID of a PGP public or secret key. Or it gives the key ID that was used for encrypting the data, if given an encrypted message. pgp_key_idはPGP公開鍵または秘密鍵のキーIDを取り出します。 暗号化されたメッセージが指定された場合は、データの暗号化に使用されたキーIDを与えます。

It can return 2 special key IDs: 2つの特殊なキーIDを返すことがあります。

Note that different keys may have the same ID. This is rare but a normal event. The client application should then try to decrypt with each one, to see which fits &mdash; like handling <literal>ANYKEY</literal>. 異なるキーが同一IDを持つ場合があることに注意してください。 これは稀ですが、正常なイベントです。 この場合クライアントアプリケーションはどちらが当てはまるかを調べるために、ANYKEYの場合と同様に、それぞれのキーで復号を試行しなければなりません。

armor(data bytea [ , keys text[], values text[] ]) returns text
dearmor(data text) returns bytea

These functions wrap/unwrap binary data into PGP ASCII-armor format, which is basically Base64 with CRC and additional formatting. PGPのASCIIアーマー形式にデータを隠す、または、データを取り出します。 ASCIIアーマーは基本的にCRC付きのBASE64という形式で、追加のフォーマットがあります。

If the <parameter>keys</parameter> and <parameter>values</parameter> arrays are specified, an <firstterm>armor header</firstterm> is added to the armored format for each key/value pair. Both arrays must be single-dimensional, and they must be of the same length. The keys and values cannot contain any non-ASCII characters. keysとvaluesの配列が指定された場合には、各キーと値の対に対してアーマーヘッダがアーマー形式に追加されます。 どちらの配列も1次元で、同じ長さでなければなりません。 keysとvaluesに非ASCII文字を含めることはできません。

pgp_armor_headers(data text, key out text, value out text) returns setof record

<function>pgp_armor_headers()</function> extracts the armor headers from <parameter>data</parameter>. The return value is a set of rows with two columns, key and value. If the keys or values contain any non-ASCII characters, they are treated as UTF-8. pgp_armor_headers()はdataからアーマーヘッダを取り出します。 戻り値はキーと値の2つの列からなる行の集合です。 もしキーや値に非アスキー文字が含まれていれば、UTF-8として扱われます。

Options are named to be similar to GnuPG. An option's value should be given after an equal sign; separate options from each other with commas. For example: オプションはGnuPGに似せて命名しています。 オプションの値は等号記号の後に指定しなければなりません。 複数のオプションはカンマで区切ってください。 以下に例を示します。

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

All of the options except <literal>convert-crlf</literal> apply only to encrypt functions. Decrypt functions get the parameters from the PGP data. convert-crlfを除くすべてのオプションは暗号化関数にのみ適用可能です。 復号関数はPGPデータからこうしたパラメータを入手します。

The most interesting options are probably <literal>compress-algo</literal> and <literal>unicode-mode</literal>. The rest should have reasonable defaults. もっとも興味深いオプションはおそらくcompress-algoとunicode-modeでしょう。 残りはデフォルトで問題ないはずです。

To generate a new key: 新しいキーを生成します。

gpg --gen-key

The preferred key type is <quote>DSA and Elgamal</quote>. 推奨するキー種類は「DSAとElgamal」です。

For RSA encryption you must create either DSA or RSA sign-only key as master and then add an RSA encryption subkey with <literal>gpg &#45;-edit-key</literal>. RSA暗号化のためには、マスタとしてDSAまたはRSAで署名のみのキーを作成し、そしてgpg --edit-keyを使用してRSAで暗号化された副キーを追加しなければなりません。

To list keys: キーを列挙します。

gpg --list-secret-keys

To export a public key in ASCII-armor format: ASCIIアーマー形式で公開鍵をエクスポートします。

gpg -a --export KEYID > public.key

To export a secret key in ASCII-armor format: ASCIIアーマー形式の秘密鍵をエクスポートします。

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

You need to use <function>dearmor()</function> on these keys before giving them to the PGP functions. Or if you can handle binary data, you can drop <literal>-a</literal> from the command. PGP関数にこれらのキーを渡す前にdearmor()を使用する必要があります。 バイナリデータを扱うことができる場合、コマンドから-aフラグを省略することができます。

For more details see <literal>man gpg</literal>, <ulink url="https://www.gnupg.org/gph/en/manual.html">The GNU Privacy Handbook</ulink> and other documentation on <ulink url="https://www.gnupg.org/"></ulink>. 詳細はman gpg、The GNU Privacy Handbook、https://www.gnupg.org/サイトの各種文書を参照してください。

<filename>pgcrypto</filename> configures itself according to the findings of the main PostgreSQL <literal>configure</literal> script. The options that affect it are <literal>&#45;-with-zlib</literal> and <literal>&#45;-with-ssl=openssl</literal>. pgcryptoは自身で主PostgreSQLのconfigureスクリプトの検出結果に従って構築します。 構築に影響するオプションは--with-zlibと--with-opensslです。

When compiled with zlib, PGP encryption functions are able to compress data before encrypting. ZLIB付きでコンパイルされた場合、PGP暗号化関数は暗号化前にデータを圧縮することができます。

<filename>pgcrypto</filename> requires <productname>OpenSSL</productname>. Otherwise, it will not be built or installed. pgcryptoはOpenSSLを必要とします。 そうでなければ、構築もインストールもされません。

When compiled against <productname>OpenSSL</productname> 3.0.0 and later versions, the legacy provider must be activated in the <filename>openssl.cnf</filename> configuration file in order to use older ciphers like DES or Blowfish. OpenSSL 3.0.0とそれ以降に対してコンパイルされた場合、DESやBlowfishのような古い暗号を使うためにはopenssl.cnf設定ファイルでレガシープロバイダを有効にしなければなりません。

As is standard in SQL, all functions return NULL, if any of the arguments are NULL. This may create security risks on careless usage. 標準SQLの通り、引数のいずれかがNULLの場合、すべての関数はNULLを返します。 注意せずに使用すると、これがセキュリティ上の問題になるかもしれません。

All <filename>pgcrypto</filename> functions run inside the database server. That means that all the data and passwords move between <filename>pgcrypto</filename> and client applications in clear text. Thus you must: pgcryptoの関数はすべてデータベースサーバ内部で実行されます。 これは、pgcryptoとクライアントアプリケーションとの間でやり取りされるデータはすべて平文であることを意味します。 したがって、以下を行う必要があります。

If you cannot, then better do crypto inside client application. これらが不可能であれば、クライアントアプリケーション内で暗号化する方が望まれます。

The implementation does not resist <ulink url="https://en.wikipedia.org/wiki/Side-channel_attack">side-channel attacks</ulink>. For example, the time required for a <filename>pgcrypto</filename> decryption function to complete varies among ciphertexts of a given size. 実装はサイドチャネル攻撃に耐えられません。 例えば、pgcrypto復号関数が完了するのに掛かる時間は、一定の長さの暗号文に対して一様ではありません。