gdoid/GDOI_PRIMER

359 lines
12 KiB
Text

$Id: GDOI_PRIMER,v 1.12.2.2 2011/12/12 23:24:16 bew Exp $
$Source: /nfs/cscbz/gdoi/gdoicvs/gdoi/GDOI_PRIMER,v $
GDOI Reference Implementation Primer
------------------------------------
A. Introduction
The purpose of this reference implementation is to provide a base vehicle for
testing the GDOI group key management protocol. GDOI was first specified in RFC 3547, and
re-published with corrections and updates in RFC 6407. This primer shows
the very basics of configuring GDOI on a pair of systems with known-working
configurations.
GDOI is a key management system for groups. It is primarily designed for use
with secure broadcast applications, but many other types of applications can
take advantage of GDOI as well for their keying.
B. System Requirements
You will need two systems, either Linux (based on a 2.6 kernel ONLY) or
BSD systems. This code was developed on Linux and OS/X. The following
releases have been tested and are safe to use:
Linux: Fedora 14
OS X: 10.6.8
You will need to have version of OpenSSL that has support for SHA256. This is
currently release openssl-0.9.8a or later. Some hints if you install this
version in a non-standard location (e.g., the default is /usr/local/ssl):
* If you have shared library version of libcrypto installed in /usr/lib then
you may need to generate a shared library version in the non-standard
location.
* If you are using a shared library be sure that the shared library is
included in your LD_LIBRARY_PATH environment variable.
For help with gdoid configuration,see gdoid.conf.5. Note that the page must be
formated with "nroff -mandoc" macros.
For Ubuntu, you may need to install the libssl-dev package. E.g.,
"sudo apt-get install libssl-dev"
C. System Roles
It is most efficient for many group applications to have a rendezvous point
where group members can get keys. With that in mind, GDOI was developed to
have two distinct roles in the protocol: the role of a key server, and the
role of a group member.
C.1 Key Server
A GDOI key server has the responsibility of keeping keys for the group, and
releasing them on demand to authenticated and authorized group members.
GDOI authenticates group members using the definition of an IKE Phase 1
exchange (see RFC 2409). The GDOI registration exchange follows the IKE Phase 1
exchange. It contains liveliness checks, confidentiality, and authorization
checks.
This GDOI reference implementation does not provide any level of authorization
check. As long as the group member passes the IKE Phase 1 authentication he is
granted access to whatever groups are available on the key server.
The key server does support the GDOI "push" (or rekey) message by which a
key server can update the keys and policy for the entire group. An IP multicast
message is used for this purpose.
C.2 Group Member
A group member is a host in which some cryptosystem which needs
keys. This version supports IPsec, and also an incomplete version of
IEC 61850-90-5.
C.2.1 IPSec
Applications are not aware of IPSec protecting applications; it's
all done transparently in the kernel. In this reference implementation
the GDOI group member code is pre-configured with which groups to
join, and it contacts the key server at startup time. This ensures
that the SAs will be loaded into the kernel when the application
is started.
To test IPsec, you can use a Linux system (with a 2.6 kernel) without
modification. I have demonstrated that the kernel will accept SAs for
multicast destinations and match incoming and outgoing packets against them.
Ciphers 3DES and AES have been validated to work with OpenBSD.
C.2.2 IEC 61850-90-5
This package comes with a framework for supporting IEC 61850-90-5, a standard for
distrubuting PMU traffic as IP multicast packets. IT does NOT contain the actual
protocol support needed to protect that standard.
D. Initial Setup
Choose which system will be your key server, and which system will be your
group member and note their IP addresses.
D.1 Key Server Setup
It would be best of find sample configurations in the samples document
and use one of them. To test between two or three systems use the samples in
the "three-clients" sample directory. A quick test can be made using the samples
in the "loopback" diectory. (Be sure to uncomment the appropriate line to create
additional loopback interfaces in loopback/START_KS.)
To setup the key server, copy the "gdoi_ks.conf" file and change the IP
addresses in the following lines:
Listen-on= <key server IP addr>
<member IP addr>= GDOI-group-member-1
[GDOI-group-member-1]
Local-address= <key server IP addr>
Address= <member IP addr>
(You can ignore the configuration lines for GDOI-group-member-2 and
GDOI-group-member-3 until you're ready to test with those systems.)
That's it! The rest of the policy defines the IKE Phase 1 policy, and one
group which contains two IPSec SAs. You can leave those as is.
D.2 Group Member Setup
Edit gdoi_client1.conf and change the IP addresses in these configuration
statements:
Listen-on= <member IP addr>
<key server IP addr>= GDOI-key-server
[GDOI-key-server]
Local-address= <member IP addr>
Address= <key server IP addr>
E. Using the sample configuration
Start the test by completing the following steps:
E.1. On the key server, become "root". Be sure the gdoi_gcks.conf file is
owned by root and has a mode of 600. Then start isakmpd as follows:
# ./START_KS
This prepares the key server to accept requests from GDOI group members.
You will see some debug messages.
E.2. On the group member, become "root". Be sure the gdoi_client1.conf file
is owned by root and has a mode of 600. Then start isakmpd as follows:
# ./START_CLIENT1
This causes the group member to initiate a GDOI exchange to the key server.
You will see some debug messages.
If you wish to load SAs into the kernel, remove the "-n" flag from the call
to isakmpd in START_CLIENT1.
E.3. The exchange is successful if you see the following string near the end
of the debugging statements on both systems: DONE WITH PHASE 2!!!
You can compare your output to two sample output scripts in the "three-clients"
directory.
E.4. If you are on OpenBSD systems, you can check if the SAs were loaded into
the kernel with this command:
# cat /kern/ipsec
and you can manually delete the SAs with this command:
# ipsecadm flush
On other systems, use the setkey command to view SAs:
# setkey -D; setkey -D -P
And you can manually delete the SAs with the -F option:
# setkey -F; setkey -F -P
E.5. More debugging
The sample scripts may not show all of the debugging statements possible. More
debugging can be shown by increasing the number <nn> on the -DA=<nn> flag. The
maximum amount of debugging can be gotten with -DA=99.
F. IKE Phase 1 Configuration Statements.
The following examples are taken from the accompanying sample configurations.
F.1. In IKE Phase 1, define the DOI to be "GROUP". This must be done on both
the key server and the group member.
EXAMPLE
-------
[Default-main-mode]
DOI= GROUP
EXCHANGE_TYPE= ID_PROT
Transforms= 3DES-SHA
F.2. For the GDOI exchange, define a Group-ID which is an IKE Phase 2 identity
type. Only KEY_ID is supported at the moment.
For more information on the IKE Phase 1 configuration see isakmpd.conf.5.
G. GDOI Configuration Statements.
To run the GDOI functionality, the following configuration is needed in the
configuration files. These examples are taken from the accompanying sample
configurations.
For more information, see the gdoid.conf(5) manual page included in this
distribution. Other example configurations can be found in the samples
directory.
G.1 Key Server
The key server stores the crypto policy and keys for a group. In this
reference implementation all keys and policy are static. Dynamic changing of
keys is not available.
The key server must define a security policy for the group. EXAMPLE 1 shows the
base policy definition to define group "1234". It defines the peer
(GDOI-group-member) and exact group policy (Default-group-mode) by
reference.
EXAMPLE 1
---------
[IPsec-group-policy]
Phase= 2
ISAKMP-peer= GDOI-group-member
Configuration= Default-group-mode
Group-ID= Group-1
[Group-1]
ID-type= KEY_ID
Key-value= 1234
The actual policy for Default-group-mode is shown in EXAMPLE 2. It defines the
Exchange to be a PULL_MODE (which is exchange number 32, see RFC 3547).
It also lists two Traffic Encryption Key policy groups to be part of this
group. (If this were keying a real application, perhaps one TEK would be
the audio stream and one the video stream).
EXAMPLE 2
---------
[Default-group-mode]
DOI= GROUP
EXCHANGE_TYPE= PULL_MODE
SA-TEKS= GROUP1-TEK1, GROUP1-TEK2
Finally, policy must be specified for each TEK. EXAMPLE 3 shows the policy for
GROUP1-TEK1. This defines a subset of the ESP policy information required.
EXAMPLE 3
---------
[GROUP1-TEK1]
Crypto-protocol= PROTO_IPSEC_ESP
Src-ID= Group-tek1-src
Dst-ID= Group-tek1-dst
TEK_Suite= GDOI-ESP-3DES-SHA-SUITE
[Group-tek1-src]
ID-type= IPV4_ADDR
Address= 172.19.193.37
Port= 1024
[Group-tek1-dst]
ID-type= IPV4_ADDR
Address= 239.192.1.1
Port= 1024
G.2 Group Member
On the group member side, the following configuration needs to be setup:
First, a policy must be defined based on the group name as shown in EXAMPLE 4.
This special naming allows the GDOI group member to find the appropriate IKE
Phase 1 policy when the crypto system gives it a group number.
EXAMPLE 4
---------
[Group-1234]
Phase= 2
ISAKMP-peer= ISAKMP-peer-gcks
Configuration= Default-group-mode
Group-ID= Group-1
[Group-1]
ID-type= KEY_ID
Key-value= 1234
The policy for Default-group-mode is shown in EXAMPLE 5.
EXAMPLE 5
---------
[Default-group-mode]
DOI= GROUP
EXCHANGE_TYPE= PULL_MODE
Suites= GM-ESP
H. Hints
Here are some things to keep in mind using this package.
1. The configuration (*.conf) files that you use MUST be owned by root and
have a mode of 600. If not, isakmpd will quickly abort. The configuration
files included in the samples directory may not be set correctly -- that
depends on how you extracted the files,
2. If the IKE Phase 1 connections don't seem to be working, restart both
isakmpd daemons and try again. That usually eliminates any confusion
between them.
3. A report of the current running gdoid state can be gotten by sending a
SIGUSR1 signal to gdoid. E.g.,
kill -SIGUSR1 <gdoid-pid>
I. Generating and using RSA Public Keys with OpenSSL
To create an RSA keypair to use with the rekey messages, follow the following
steps.
1. Generate a keypair of at least 1024 bits.
openssl genrsa 1024 > rsakeys.pem
2. The keys are generated in PEM format, and GDOI would like them to be in
DER format, so they must be converted
openssl rsa -in rsakeys.pem -outform DER -out rsakeys.der
NOTE: The keys are not in a displayable format.
J. Acknowledgments
Thanks to the following individuals for contributing to gdoid:
Sebastien.Josset at space dot alcatel dot fr contributed code which enabled
gdoid to support AES as an IPsec transform, as well as the new OpenBSD PF_KEY
extensions.
nico_kth at hotmail dot com provided modifications to the pf_key code, which
enabled pushing of SAD and SPD table entries into a Linux 2.6 kernel. This
gave gdoid the ablity of supportng IPsec on Linux, whereas previously Linux
could only be used as a key server.
reet79 at ggs.ch provided code that caused gdoid to clean up the SAs and SPD
entries it installed before exiting. He also provided code that allows
X.509 certificates to reside on an XFS file system.
K. Known Bugs
1. Configuring IPsec tunnel mode SAs actually end up as transport mode SAs.
2. ECDSA has not been tested. Enabling #define USE_EC is sure to fail!