Skip to content

Commit 62afb42

Browse files
bmomjianbmomjian
committed
Add pg_alterckey utility to change the cluster key
This can change the key that encrypts the data encryption keys used for cluster file encryption. Discussion: https://postgr.es/m/20201202213814.GG20285@momjian.us Backpatch-through: master
1 parent f234899 commit 62afb42

File tree

5 files changed

+925
-0
lines changed

5 files changed

+925
-0
lines changed

‎doc/src/sgml/ref/pg_alterkey.sgml

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
<!--
2+
doc/src/sgml/ref/pg_alterckey.sgml
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="app-pg_alterckey">
7+
<indexterm zone="app-pg_alterckey">
8+
<primary>pg_alterckey</primary>
9+
</indexterm>
10+
11+
<refmeta>
12+
<refentrytitle><application>pg_alterckey</application></refentrytitle>
13+
<manvolnum>1</manvolnum>
14+
<refmiscinfo>Application</refmiscinfo>
15+
</refmeta>
16+
17+
<refnamediv>
18+
<refname>pg_alterckey</refname>
19+
<refpurpose>alter the <productname>PostgreSQL</productname> cluster key</refpurpose>
20+
</refnamediv>
21+
22+
<refsynopsisdiv>
23+
<cmdsynopsis>
24+
<command>pg_alterckey</command>
25+
<group choice="opt">
26+
<arg choice="plain"><option>-R</option></arg>
27+
<arg choice="plain"><option>--authprompt</option></arg>
28+
</group>
29+
<replaceable class="parameter">old_cluster_key_command</replaceable>
30+
<replaceable class="parameter">new_cluster_key_command</replaceable>
31+
<group choice="opt">
32+
<group choice="opt">
33+
<arg choice="plain"><option>-D</option></arg>
34+
<arg choice="plain"><option>--pgdata</option></arg>
35+
</group>
36+
<replaceable class="parameter">datadir</replaceable>
37+
</group>
38+
</cmdsynopsis>
39+
40+
<cmdsynopsis>
41+
<command>pg_alterckey</command>
42+
<group choice="opt">
43+
<arg choice="plain"><option>-R</option></arg>
44+
<arg choice="plain"><option>--authprompt</option></arg>
45+
</group>
46+
<group choice="plain">
47+
<arg choice="plain"><option>-r</option></arg>
48+
<arg choice="plain"><option>--repair</option></arg>
49+
</group>
50+
<group choice="opt">
51+
<group choice="opt">
52+
<arg choice="plain"><option>-D</option></arg>
53+
<arg choice="plain"><option>--pgdata</option></arg>
54+
</group>
55+
<replaceable class="parameter">datadir</replaceable>
56+
</group>
57+
</cmdsynopsis>
58+
</refsynopsisdiv>
59+
60+
<refsect1 id="r1-app-pg_alterckey-1">
61+
<title>Description</title>
62+
<para>
63+
<command>pg_alterckey</command> alters the cluster key used
64+
for cluster file encryption. The cluster key is initially set
65+
during <xref linkend="app-initdb"/>. The command can be run while the
66+
server is running or stopped. The new password must be used the next
67+
time the server is started.
68+
</para>
69+
70+
<para>
71+
Technically, <command>pg_alterckey</command> changes the key
72+
encryption key (<acronym>KEK</acronym>) which encrypts the data
73+
encryption keys; it does not change the data encryption keys. It does
74+
this by decrypting each data encryption key using the <replaceable
75+
class="parameter">old_cluster_key_command</replaceable>,
76+
re-encrypting it using the <replaceable
77+
class="parameter">new_cluster_key_command</replaceable>, and
78+
then writes the result back to the cluster directory.
79+
</para>
80+
81+
<para>
82+
See the <xref linkend="app-initdb"/> documentation for how to define
83+
the old and new passphrase commands. You can use different executables
84+
for these commands, or you can use the same executable with different
85+
arguments to specify retrieval of the old or new key.
86+
</para>
87+
88+
<para>
89+
When started, <command>pg_alterckey</command> repairs any files that
90+
remain from previous <command>pg_alterckey</command> failures before
91+
altering the cluster key. To perform only the repair task,
92+
use the <option>--repair</option> option. The server will not start
93+
if repair is needed, though a running server is unaffected by an
94+
unrepaired cluster key configuration.
95+
</para>
96+
97+
<para>
98+
You can specify the data directory on the command line, or use
99+
the environment variable <envar>PGDATA</envar>.
100+
</para>
101+
</refsect1>
102+
103+
<refsect1>
104+
<title>Options</title>
105+
106+
<para>
107+
<varlistentry>
108+
<term><option>-R</option></term>
109+
<term><option>--authprompt</option></term>
110+
<listitem>
111+
<para>
112+
Allows the <option>old_cluster_key_command</option> and
113+
<option>new_cluster_key_command</option> commands
114+
to prompt for a passphrase or PIN.
115+
</para>
116+
</listitem>
117+
</varlistentry>
118+
</variablelist>
119+
</para>
120+
121+
<para>
122+
Other options:
123+
124+
<variablelist>
125+
<varlistentry>
126+
<term><option>-V</option></term>
127+
<term><option>--version</option></term>
128+
<listitem>
129+
<para>
130+
Print the <application>pg_alterckey</application> version and exit.
131+
</para>
132+
</listitem>
133+
</varlistentry>
134+
135+
<varlistentry>
136+
<term><option>-?</option></term>
137+
<term><option>--help</option></term>
138+
<listitem>
139+
<para>
140+
Show help about <application>pg_alterckey</application> command line
141+
arguments, and exit.
142+
</para>
143+
</listitem>
144+
</varlistentry>
145+
146+
</variablelist>
147+
</para>
148+
149+
</refsect1>
150+
151+
<refsect1>
152+
<title>Environment</title>
153+
154+
<variablelist>
155+
<varlistentry>
156+
<term><envar>PGDATA</envar></term>
157+
158+
<listitem>
159+
<para>
160+
Default data directory location
161+
</para>
162+
</listitem>
163+
</varlistentry>
164+
165+
<varlistentry>
166+
<term><envar>PG_COLOR</envar></term>
167+
<listitem>
168+
<para>
169+
Specifies whether to use color in diagnostic messages. Possible values
170+
are <literal>always</literal>, <literal>auto</literal> and
171+
<literal>never</literal>.
172+
</para>
173+
</listitem>
174+
</varlistentry>
175+
176+
</refsect1>
177+
178+
<refsect1>
179+
<title>See Also</title>
180+
181+
<simplelist type="inline">
182+
<member><xref linkend="app-initdb"/></member>
183+
</simplelist>
184+
</refsect1>
185+
186+
</refentry>

‎src/bin/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ include $(top_builddir)/src/Makefile.global
1616
SUBDIRS = \
1717
initdb \
1818
pg_archivecleanup \
19+
pg_alterckey \
1920
pg_basebackup \
2021
pg_checksums \
2122
pg_config \

‎src/bin/pg_alterckey/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/pg_alterckey

‎src/bin/pg_alterckey/Makefile

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
#-------------------------------------------------------------------------
2+
#
3+
# Makefile for src/bin/pg_alterckey
4+
#
5+
# Copyright (c) 1998-2020, PostgreSQL Global Development Group
6+
#
7+
# src/bin/pg_alterckey/Makefile
8+
#
9+
#-------------------------------------------------------------------------
10+
11+
PGFILEDESC = "pg_alterckey - alter the cluster key"
12+
PGAPPICON=win32
13+
14+
subdir = src/bin/pg_alterckey
15+
top_builddir = ../../..
16+
include $(top_builddir)/src/Makefile.global
17+
18+
OBJS = \
19+
$(WIN32RES) \
20+
pg_alterckey.o
21+
22+
all: pg_alterckey
23+
24+
pg_alterckey: $(OBJS) | submake-libpgport
25+
$(CC) $(CFLAGS) $^ $(LDFLAGS) $(LDFLAGS_EX) $(LIBS) -o $@$(X)
26+
27+
install: all installdirs
28+
$(INSTALL_PROGRAM) pg_alterckey$(X) '$(DESTDIR)$(bindir)/pg_alterckey$(X)'
29+
30+
installdirs:
31+
$(MKDIR_P) '$(DESTDIR)$(bindir)'
32+
33+
uninstall:
34+
rm -f '$(DESTDIR)$(bindir)/pg_alterckey$(X)'
35+
36+
clean distclean maintainer-clean:
37+
rm -f pg_alterckey$(X) $(OBJS)
38+
rm -rf tmp_check
39+
40+
check:
41+
$(prove_check)
42+
43+
installcheck:
44+
$(prove_installcheck)

0 commit comments

Comments
 (0)