-
Notifications
You must be signed in to change notification settings - Fork 5
/
QUICKSTART.txt
201 lines (141 loc) · 8.05 KB
/
QUICKSTART.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
**Building Packages**
NOTE: Building the packages is for advanced users/testers only, you can
obtain packages in the normal way from OS repos by looking here:-
https://netlore.github.io/OpenAKC/download/
_Debian/Ubuntu_
To create ".deb" packages for Debian/Ubuntu, simply download the repo using
whatever method you prefer, then, as the "root" user, cd into the folder, and
run "./makedebs.sh". Watch for unexpected errors, and assuming there are no
issues you will find that the required 4 .deb packages appear in the same
folder as the "makedebs.sh" script. Be sure to move them aside as they may
interfere with some of the "contrib" tools.
_Redhat_
Collect the zip for "master", or for a release version, place it in the SOURCES
folder of a working "rpmbuild" environment (Configuring an RPM build
environment is not covered here), Eg:-
cd ~/rpmbuild/SOURCES
wget https://github.com/netlore/OpenAKC/archive/master.zip
Then extract the zip so that the associated "openakc-rhel.spec" file is available,
and run rpmbuild to create the packages Eg:-
unzip master.zip
rpmbuild -ba OpenAKC-master/openakc.spec
If nothing goes wrong, the RPM's will appear in the build environments "RPMS"
folder.
_SuSE_
As for RedHat, except if you build as root, it will already have a
preconfigured RPM build environment in /usr/src
**Quickstart Guide**
_Server Installation_
If installing from compiledpackages's rather than a repo, you may first need to
ensure that some dependencies are installed. At the time of writing, a standard
minimal "CentOS container" requires several packages to be installed
in addition to the default:-
Eg.
yum install openssh-clients openssl xinetd openssl sudo which
For a minimal Ubuntu, installing the extra depenencies is also required
if not using a repo, but there are not as many.
Eg.
apt isntall xinetd
With dependencies handled, simply install packages
1) "openakc-server" which provides the server itself, which handles
authentication requests, registration requests from users, and permissions
updates.
2) "openakc-tools" which contains the interface tool, which allows users to
register their keys, and administrators to upload static keys and configure
permissions.
3) "openakc-shared" which contains functions shared between all openakc
components.
To verify that the server is working, simply type "openakc ping" after
installing the server packages. This should force the server to write out
a default configuration and reply with "OK: Pong!"
_Client Installation_
As for the server, if you are installing from packages's rather than a repo,
you may first need to ensure that some dependencies are installed. At the time
of writing, a standard minimal "CentOS container" requires the several
packages to be installed in advance:-
Eg.
yum install e2fsprogs openssh-clients openssh-server openssl which
For a minimal Ubuntu, installing extra dependencies is currently not
required on the client host.
Once any dependencies are met, install packages "openakc" & "openakc-shared"
To set up the client, ensure that the host(s) listed in the client config
(/etc/openakc/openakc.conf) (which can be either name or IP) are configured
to refer to the appropriate server. The configuration is pre-populated with
"openakc01 & openakc02", so you could simply ensure that these values are
configured in DNS, or in the /etc/hosts on the client for testing, or alter
them as you prefer.
NOTE: Before attempting to edit this file, you are advised to read the
assocated "readme" - /etc/openakc/openakc.conf.readme, since the OpenAKC
client installation marks its configuration "immutable" to avoid casual
editing of those files by users you may need to grant root access.
To verify that the client is configured, and can contact the server, after
installation, you can run "openakc-plugin ping". The plugin only has very
minimal command line functions, but if for any reason you rebuild the
server, and loose it's openssl identity, you may want to remove the server
identity from the client using "openakc-plugin resetkeys"... otherwise no
communication will be possible.
_System Setup_
In a minimal installation, the only configuration required is to ensure that
the client config contains valid "APIS".
Note that all personal key pairs registered with the system must have a
passphrase. In future support for tools like Yubikey may be added, and this
rule may be relaxed when using keys backed with a hardware 2FA device.
To test get started with authentication, you will need at least one non-root
user on the server, ideally 2 (one to be the security administrator, and the
other to be a normal user). For testing of course the security administrator
could simply assign rights to himself. Configurations where the users are
on a different server will be discussed in the documentation proper, but
will require only the openakc-tools package to be installed.
Ensure your users exist, and if they do not already have an SSH key pair then
create one (with pass phrase), and attempt to register that key by running the
command:-
"openakc register"
Now attempt to connect to your a client machine, this will demonstrate that
you cannot connect (no permissions have been granted), but will also serve to
let the server to learn about the client, (when a public key is presented to
the remote ssh daemon, it will call the plugin and request authentication from
the server, which will populate date about that host on the server) this will
help later on.
Designating security administrators.
For a (registered) user who you wish to make a "security administrator",
take the file from the users home folder:-
~[user]/.openakc/openakc-user-client-[user]-pubkey.pem and place this in the
root owned folder on the server "/var/lib/openakc/keys". This method allows
a user who may be on an entirely unrelated system with only the openakc-tools
package installed to manage permissions. For the purpose of this "quickstart"
guide however, we will not discuss distributed systems.
This user will now be able to run call the role management functions in the
api tool Eg:-
"openakc editrole root@DEFAULT" (Default rolefile is applied to hosts not
yet configured explicitly, so it is a useful way to get started).
Examine the comments, and example role "block" shown, and create one
defining access for a user or group.
The role data can also be uploaded or downloaded using the "getrole" or
"setrole" commands with a filename as an extra parameter Eg:-
"openakc getrole root@DEFAULT /tmp/role.txt"
This will get the role and write it to the file /tmp/role.txt... you can then
edit it and upload it. "setrole" could be used to upload roles without first
downloading them, perhaps from some automation.
Once the role data is saved, access should be available instantly... since
keys are not "distributed" to the clients as in other key managers, but the
clients query the server for every incoming ssh connection. This allows
for detailed logs to be keps on the server, but more importantly it allows
for session logging to be performed (even if the connection does not come from
the server, or indeed, in the case of a static key the connection may come from
outside your network, and you will still see a session log generated on the
server if specified in the role)
You can examine the logs on each host to see what was logged, as well as check
the keystroke log written to /var/lib/openakc/keylogs on the server, as well as
the configuration audit data in /var/lib/openakc/audit on the server.
For further details please see the full documentation which can be found at
the web site:-
https://netlore.github.io/OpenAKC/
Note: At the time of writing, the documentation is incomplete, feel free to
assist with this, or make suggestions at the GitHub site.
*Related software*
OpenAKC makes use of hpenc, by Vsevolod Stakhov and libsodium by Frank Denis,
these tools are included with minor modifications (in the case of hpenc) to
ensure successful compilation on newer versions of GCC, in the source package
for OpenAKC and specific licence terms for these tools are included in
separate LICENCE-* files and in the documentation directory deployed by
OpenAKC packages.