mirror of
https://github.com/Yubico/yubikey-ksm.git
synced 2024-11-29 00:24:14 +01:00
Asciidocified docs.
This commit is contained in:
Dain Nilsson
parent
7d83e645f6
commit
ca517e168c
@ -16,13 +16,13 @@ For example:
|
|||||||
|
|
||||||
The content of the various fields are as follows:
|
The content of the various fields are as follows:
|
||||||
|
|
||||||
* '''counter''': 16-bit hex integer, counting upwards on each powerup&touch
|
* 'counter': 16-bit hex integer, counting upwards on each powerup&touch
|
||||||
|
|
||||||
* '''low''': 16-bit hex integer, low part of time-stamp of OTP
|
* 'low': 16-bit hex integer, low part of time-stamp of OTP
|
||||||
|
|
||||||
* '''high''': 8-bit hex integer, high part of time-stamp of OTP
|
* 'high': 8-bit hex integer, high part of time-stamp of OTP
|
||||||
|
|
||||||
* '''use''': 8-bit hex integer, counting upwards on each touch
|
* 'use': 8-bit hex integer, counting upwards on each touch
|
||||||
|
|
||||||
On soft errors, the response will follow this format:
|
On soft errors, the response will follow this format:
|
||||||
|
|
||||||
@ -1,70 +0,0 @@
|
|||||||
Generate KSM Key
|
|
||||||
----------------
|
|
||||||
|
|
||||||
Import of key material to an YK-KSM is typically always done via the
|
|
||||||
OpenPGP encrypted/signed KeyProvisioningFormat format. This setup
|
|
||||||
assumes that each YK-KSM system has a private key.
|
|
||||||
|
|
||||||
Below is a walk-through of a typical key generation session for a host
|
|
||||||
called 'crater'. As you can see at the end, it generated a key with a
|
|
||||||
key id of '8B88A11B'.
|
|
||||||
|
|
||||||
After this step you may want to generate AES keys for your YubiKeys,
|
|
||||||
see [[GenerateKeys]], and then import them to your KSM, see
|
|
||||||
[[ImportKeysToKSM]].
|
|
||||||
|
|
||||||
user@crater:~$ gpg --gen-key
|
|
||||||
gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
|
|
||||||
This is free software: you are free to change and redistribute it.
|
|
||||||
There is NO WARRANTY, to the extent permitted by law.
|
|
||||||
|
|
||||||
Please select what kind of key you want:
|
|
||||||
(1) DSA and Elgamal (default)
|
|
||||||
(2) DSA (sign only)
|
|
||||||
(5) RSA (sign only)
|
|
||||||
Your selection? 1
|
|
||||||
DSA keypair will have 1024 bits.
|
|
||||||
ELG-E keys may be between 1024 and 4096 bits long.
|
|
||||||
What keysize do you want? (2048)
|
|
||||||
Requested keysize is 2048 bits
|
|
||||||
Please specify how long the key should be valid.
|
|
||||||
0 = key does not expire
|
|
||||||
<n> = key expires in n days
|
|
||||||
<n>w = key expires in n weeks
|
|
||||||
<n>m = key expires in n months
|
|
||||||
<n>y = key expires in n years
|
|
||||||
Key is valid for? (0)
|
|
||||||
Key does not expire at all
|
|
||||||
Is this correct? (y/N) y
|
|
||||||
|
|
||||||
You need a user ID to identify your key; the software constructs the user ID
|
|
||||||
from the Real Name, Comment and Email Address in this form:
|
|
||||||
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
|
|
||||||
|
|
||||||
Real name: YK-KSM crater Import Key
|
|
||||||
Email address:
|
|
||||||
Comment:
|
|
||||||
You selected this USER-ID:
|
|
||||||
"YK-KSM crater Import Key"
|
|
||||||
|
|
||||||
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
|
|
||||||
You need a Passphrase to protect your secret key.
|
|
||||||
|
|
||||||
We need to generate a lot of random bytes. It is a good idea to perform
|
|
||||||
some other action (type on the keyboard, move the mouse, utilize the
|
|
||||||
disks) during the prime generation; this gives the random number
|
|
||||||
generator a better chance to gain enough entropy.
|
|
||||||
.+++++++++++++++++++++++++..+++++.+++++++++++++++++++++++++...+++++++++++++++.++++++++++.++++++++++++++++++++++++++++++++++++++++.++++++++++>++++++++++......++++++++++..++++++++++++++++++++..++++++++++++++++++++++++++++++++++++++++....+++++.+++++...+++++.++++++++++.+++++++++++++++.+++++..+++++.++++++++++.+++++++++++++++..+++++>++++++++++>+++++.................................>+++++..............+++++^^^
|
|
||||||
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
|
|
||||||
gpg: key 8B88A11B marked as ultimately trusted
|
|
||||||
public and secret key created and signed.
|
|
||||||
|
|
||||||
gpg: checking the trustdb
|
|
||||||
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
|
|
||||||
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
|
|
||||||
pub 1024D/8B88A11B 2009-12-14
|
|
||||||
Key fingerprint = 9B18 20A2 F02E 3C3B 84E3 44F5 AE72 7967 8B88 A11B
|
|
||||||
uid YK-KSM crater Import Key
|
|
||||||
sub 2048g/140A17F1 2009-12-14
|
|
||||||
|
|
||||||
user@crater:~$
|
|
||||||
@ -1,79 +0,0 @@
|
|||||||
Generate Keys
|
|
||||||
-------------
|
|
||||||
|
|
||||||
To generate some AES keys for your !YubiKeys served via your YK-KSM,
|
|
||||||
you use the 'ykksm-gen-keys' tool. The tool is useful for generating
|
|
||||||
large sets of test keys, for performance testing of the database and
|
|
||||||
web interface. It can also be used to produce keying material that
|
|
||||||
are intended to used for programming real keys.
|
|
||||||
|
|
||||||
As you should never store encryption keys in plaintext, you typically
|
|
||||||
use the tool by piping it directly to GnuPG. So the first step will
|
|
||||||
always be to create a OpenPGP key for your KSM host, see
|
|
||||||
[[GenerateKSMKey]]. Below we will both sign the data from and encrypt
|
|
||||||
it to the same key id '8B88A11B'. Here is how you would generate 5
|
|
||||||
keys for test purposes:
|
|
||||||
|
|
||||||
user@ksm:~$ ykksm-gen-keys --urandom 1 5 | gpg -a --encrypt -r 8B88A11B -s > keys.txt
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Note the flag --urandom will cause the tool to use /dev/urandom rather
|
|
||||||
than /dev/random, which speed things up but is considered by some to
|
|
||||||
have weaker security.
|
|
||||||
|
|
||||||
After this step you may want to import the keys into your KSM, see
|
|
||||||
[[ImportKeysToKSM]].
|
|
||||||
|
|
||||||
In production, you may want to separate the key generation facility
|
|
||||||
into a separate machine with a separate OpenPGP key.
|
|
||||||
|
|
||||||
To display the test keys above, you can decrypt them using GnuPG:
|
|
||||||
|
|
||||||
user@ksm:~$ gpg < keys.txt
|
|
||||||
|
|
||||||
You need a passphrase to unlock the secret key for
|
|
||||||
user: "YK-KSM crater Import Key"
|
|
||||||
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
|
||||||
|
|
||||||
gpg: encrypted with 2048-bit ELG-E key, ID 140A17F1, created 2009-12-14
|
|
||||||
"YK-KSM crater Import Key"
|
|
||||||
# ykksm 1
|
|
||||||
# serialnr,identity,internaluid,aeskey,lockpw,created,accessed[,progflags]
|
|
||||||
1,cccccccccccb,d74fbdf6a890,82211e0854e7369e83d941f24761a84e,881ae7bee927,2009-12-14T16:40:57,
|
|
||||||
2,cccccccccccd,7a5ad1886b70,3091a8048524ab8407ae816457d764e5,8e5ab609e346,2009-12-14T16:40:57,
|
|
||||||
3,ccccccccccce,981abbbeafb8,91be4bfd2f40e24ebd39386868aa9619,037b6f6ae73c,2009-12-14T16:40:57,
|
|
||||||
4,cccccccccccf,c1f33c17f77b,a2389839d7b80bfe4c80258184aff4ce,abf92cbbdab3,2009-12-14T16:40:57,
|
|
||||||
5,cccccccccccg,c55773192393,7387b5f6bede83f64a9cd75b2023826a,d70c937bbbff,2009-12-14T16:40:57,
|
|
||||||
gpg: Signature made Mon 14 Dec 2009 04:40:57 PM CET using DSA key ID 8B88A11B
|
|
||||||
gpg: Good signature from "YK-KSM crater Import Key"
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
The format is documented in the KeyProvisioningFormat wiki page.
|
|
||||||
|
|
||||||
To generate many small files each containing just one key, you can use
|
|
||||||
a small wrapper like this:
|
|
||||||
|
|
||||||
|
|
||||||
#!/bin/sh
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
start=$1
|
|
||||||
stop=$2
|
|
||||||
key=$3
|
|
||||||
urandom=$4
|
|
||||||
|
|
||||||
if test -z "$start" || test -z "$stop" || test -z "$key"; then
|
|
||||||
echo "Usage: run-gen-keys START STOP KEY [--urandom]"
|
|
||||||
echo ""
|
|
||||||
echo "Example usage:"
|
|
||||||
echo " run-gen-keys 4711 11147 A1296239 --urandom"
|
|
||||||
echo ""
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
cur=$start
|
|
||||||
while test $cur -le $stop; do
|
|
||||||
ykksm-gen-keys $urandom $cur | gpg -a --sign --encrypt -r $key > $cur.asc
|
|
||||||
cur=`expr $cur + 1`
|
|
||||||
done
|
|
||||||
74
doc/Generate_KSM_Key.adoc
Normal file
74
doc/Generate_KSM_Key.adoc
Normal file
@ -0,0 +1,74 @@
|
|||||||
|
Generate KSM Key
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Import of key material to an YK-KSM is typically always done via the
|
||||||
|
OpenPGP encrypted/signed
|
||||||
|
link:Key_Provisioning_Format.adoc[Key Provisioning Format]. This setup
|
||||||
|
assumes that each YK-KSM system has a private key.
|
||||||
|
|
||||||
|
Below is a walk-through of a typical key generation session for a host
|
||||||
|
called 'crater'. As you can see at the end, it generated a key with a
|
||||||
|
key id of '8B88A11B'.
|
||||||
|
|
||||||
|
After this step you may want to generate AES keys for your YubiKeys,
|
||||||
|
see link:Generate_Keys.adoc[Generate Keys], and then import them to your
|
||||||
|
KSM, see link:Import_Keys_To_KSM.adoc[Import Keys To KSM].
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@crater:~$ gpg --gen-key
|
||||||
|
gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
|
||||||
|
This is free software: you are free to change and redistribute it.
|
||||||
|
There is NO WARRANTY, to the extent permitted by law.
|
||||||
|
|
||||||
|
Please select what kind of key you want:
|
||||||
|
(1) DSA and Elgamal (default)
|
||||||
|
(2) DSA (sign only)
|
||||||
|
(5) RSA (sign only)
|
||||||
|
Your selection? 1
|
||||||
|
DSA keypair will have 1024 bits.
|
||||||
|
ELG-E keys may be between 1024 and 4096 bits long.
|
||||||
|
What keysize do you want? (2048)
|
||||||
|
Requested keysize is 2048 bits
|
||||||
|
Please specify how long the key should be valid.
|
||||||
|
0 = key does not expire
|
||||||
|
<n> = key expires in n days
|
||||||
|
<n>w = key expires in n weeks
|
||||||
|
<n>m = key expires in n months
|
||||||
|
<n>y = key expires in n years
|
||||||
|
Key is valid for? (0)
|
||||||
|
Key does not expire at all
|
||||||
|
Is this correct? (y/N) y
|
||||||
|
|
||||||
|
You need a user ID to identify your key; the software constructs the user ID
|
||||||
|
from the Real Name, Comment and Email Address in this form:
|
||||||
|
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
|
||||||
|
|
||||||
|
Real name: YK-KSM crater Import Key
|
||||||
|
Email address:
|
||||||
|
Comment:
|
||||||
|
You selected this USER-ID:
|
||||||
|
"YK-KSM crater Import Key"
|
||||||
|
|
||||||
|
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
|
||||||
|
You need a Passphrase to protect your secret key.
|
||||||
|
|
||||||
|
We need to generate a lot of random bytes. It is a good idea to perform
|
||||||
|
some other action (type on the keyboard, move the mouse, utilize the
|
||||||
|
disks) during the prime generation; this gives the random number
|
||||||
|
generator a better chance to gain enough entropy.
|
||||||
|
.+++++++++++++++++++++++++..+++++.+++++++++++++++++++++++++...+++++++++++++++.++++++++++.++++++++++++++++++++++++++++++++++++++++.++++++++++>++++++++++......++++++++++..++++++++++++++++++++..++++++++++++++++++++++++++++++++++++++++....+++++.+++++...+++++.++++++++++.+++++++++++++++.+++++..+++++.++++++++++.+++++++++++++++..+++++>++++++++++>+++++.................................>+++++..............+++++^^^
|
||||||
|
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
|
||||||
|
gpg: key 8B88A11B marked as ultimately trusted
|
||||||
|
public and secret key created and signed.
|
||||||
|
|
||||||
|
gpg: checking the trustdb
|
||||||
|
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
|
||||||
|
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
|
||||||
|
pub 1024D/8B88A11B 2009-12-14
|
||||||
|
Key fingerprint = 9B18 20A2 F02E 3C3B 84E3 44F5 AE72 7967 8B88 A11B
|
||||||
|
uid YK-KSM crater Import Key
|
||||||
|
sub 2048g/140A17F1 2009-12-14
|
||||||
|
|
||||||
|
user@crater:~$
|
||||||
|
----
|
||||||
88
doc/Generate_Keys.adoc
Normal file
88
doc/Generate_Keys.adoc
Normal file
@ -0,0 +1,88 @@
|
|||||||
|
Generate Keys
|
||||||
|
-------------
|
||||||
|
|
||||||
|
To generate some AES keys for your !YubiKeys served via your YK-KSM,
|
||||||
|
you use the 'ykksm-gen-keys' tool. The tool is useful for generating
|
||||||
|
large sets of test keys, for performance testing of the database and
|
||||||
|
web interface. It can also be used to produce keying material that
|
||||||
|
are intended to used for programming real keys.
|
||||||
|
|
||||||
|
As you should never store encryption keys in plaintext, you typically
|
||||||
|
use the tool by piping it directly to GnuPG. So the first step will
|
||||||
|
always be to create a OpenPGP key for your KSM host, see
|
||||||
|
link:Generate_KSM_Key.adoc[Generate KSM Key]. Below we will both sign
|
||||||
|
the data from and encrypt it to the same key id '8B88A11B'. Here is
|
||||||
|
how you would generate 5 keys for test purposes:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ ykksm-gen-keys --urandom 1 5 | gpg -a --encrypt -r 8B88A11B -s > keys.txt
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Note the flag --urandom will cause the tool to use /dev/urandom rather
|
||||||
|
than /dev/random, which speed things up but is considered by some to
|
||||||
|
have weaker security.
|
||||||
|
|
||||||
|
After this step you may want to import the keys into your KSM, see
|
||||||
|
link:Import_Keys_To_KSM.adoc[Import Keys To KSM].
|
||||||
|
|
||||||
|
In production, you may want to separate the key generation facility
|
||||||
|
into a separate machine with a separate OpenPGP key.
|
||||||
|
|
||||||
|
To display the test keys above, you can decrypt them using GnuPG:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ gpg < keys.txt
|
||||||
|
|
||||||
|
You need a passphrase to unlock the secret key for
|
||||||
|
user: "YK-KSM crater Import Key"
|
||||||
|
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
||||||
|
|
||||||
|
gpg: encrypted with 2048-bit ELG-E key, ID 140A17F1, created 2009-12-14
|
||||||
|
"YK-KSM crater Import Key"
|
||||||
|
# ykksm 1
|
||||||
|
# serialnr,identity,internaluid,aeskey,lockpw,created,accessed[,progflags]
|
||||||
|
1,cccccccccccb,d74fbdf6a890,82211e0854e7369e83d941f24761a84e,881ae7bee927,2009-12-14T16:40:57,
|
||||||
|
2,cccccccccccd,7a5ad1886b70,3091a8048524ab8407ae816457d764e5,8e5ab609e346,2009-12-14T16:40:57,
|
||||||
|
3,ccccccccccce,981abbbeafb8,91be4bfd2f40e24ebd39386868aa9619,037b6f6ae73c,2009-12-14T16:40:57,
|
||||||
|
4,cccccccccccf,c1f33c17f77b,a2389839d7b80bfe4c80258184aff4ce,abf92cbbdab3,2009-12-14T16:40:57,
|
||||||
|
5,cccccccccccg,c55773192393,7387b5f6bede83f64a9cd75b2023826a,d70c937bbbff,2009-12-14T16:40:57,
|
||||||
|
gpg: Signature made Mon 14 Dec 2009 04:40:57 PM CET using DSA key ID 8B88A11B
|
||||||
|
gpg: Good signature from "YK-KSM crater Import Key"
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
The format is documented in the
|
||||||
|
link:Key_Provisioning_format.adoc[Key Provisioning Format] page.
|
||||||
|
|
||||||
|
To generate many small files each containing just one key, you can use
|
||||||
|
a small wrapper like this:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
start=$1
|
||||||
|
stop=$2
|
||||||
|
key=$3
|
||||||
|
urandom=$4
|
||||||
|
|
||||||
|
if test -z "$start" || test -z "$stop" || test -z "$key"; then
|
||||||
|
echo "Usage: run-gen-keys START STOP KEY [--urandom]"
|
||||||
|
echo ""
|
||||||
|
echo "Example usage:"
|
||||||
|
echo " run-gen-keys 4711 11147 A1296239 --urandom"
|
||||||
|
echo ""
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
cur=$start
|
||||||
|
while test $cur -le $stop; do
|
||||||
|
ykksm-gen-keys $urandom $cur | gpg -a --sign --encrypt -r $key > $cur.asc
|
||||||
|
cur=`expr $cur + 1`
|
||||||
|
done
|
||||||
|
----
|
||||||
@ -1,76 +0,0 @@
|
|||||||
Import Keys To Yubikey KSM
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
To import keys into the YK-KSM database from text files in the
|
|
||||||
encrypted/signed KeyProvisioningFormat format, you can use the tool
|
|
||||||
'ykksm-import'. The tool reads the data on standard input, and will
|
|
||||||
import the data to the database. On any error, execution is aborted,
|
|
||||||
so be careful about partial imports leaving the database in an
|
|
||||||
intermediate state.
|
|
||||||
|
|
||||||
The tool requires that your system has a GnuPG private key, read
|
|
||||||
[[GenerateKSMKey]] on how to generate it.
|
|
||||||
|
|
||||||
For example, to import the file generated by the [[GenerateKeys]]
|
|
||||||
document:
|
|
||||||
|
|
||||||
user@ksm:~$ ykksm-import --verbose --database 'DBI:Pg:dbname=ykksm;host=127.0.0.1' --db-user ykksmimporter --db-passwd otherpassword < ~/keys.txt
|
|
||||||
|
|
||||||
You need a passphrase to unlock the secret key for
|
|
||||||
user: "YK-KSM crater Import Key"
|
|
||||||
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
[GNUPG:] ENC_TO 8C73EAF1140A17F1 16 0
|
|
||||||
[GNUPG:] USERID_HINT 8C73EAF1140A17F1 YK-KSM crater Import Key
|
|
||||||
[GNUPG:] NEED_PASSPHRASE 8C73EAF1140A17F1 AE7279678B88A11B 16 0
|
|
||||||
[GNUPG:] GOOD_PASSPHRASE
|
|
||||||
gpg: encrypted with 2048-bit ELG-E key, ID 140A17F1, created 2009-12-14
|
|
||||||
"YK-KSM crater Import Key"
|
|
||||||
[GNUPG:] BEGIN_DECRYPTION
|
|
||||||
[GNUPG:] PLAINTEXT 62 1260805257
|
|
||||||
gpg: Signature made Mon 14 Dec 2009 04:40:57 PM CET using DSA key ID 8B88A11B
|
|
||||||
[GNUPG:] SIG_ID YGplk8qkUkb75lY0aurb/iS1Oog 2009-12-14 1260805257
|
|
||||||
[GNUPG:] GOODSIG AE7279678B88A11B YK-KSM crater Import Key
|
|
||||||
gpg: Good signature from "YK-KSM crater Import Key"
|
|
||||||
[GNUPG:] VALIDSIG 9B1820A2F02E3C3B84E344F5AE7279678B88A11B 2009-12-14 1260805257 0 4 0 17 2 00 9B1820A2F02E3C3B84E344F5AE7279678B88A11B
|
|
||||||
[GNUPG:] TRUST_ULTIMATE
|
|
||||||
[GNUPG:] DECRYPTION_OKAY
|
|
||||||
[GNUPG:] GOODMDC
|
|
||||||
[GNUPG:] END_DECRYPTION
|
|
||||||
encrypted to: 8C73EAF1140A17F1
|
|
||||||
signed by: 8B88A11B
|
|
||||||
|
|
||||||
You need a passphrase to unlock the secret key for
|
|
||||||
user: "YK-KSM crater Import Key"
|
|
||||||
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
|
||||||
|
|
||||||
line: 1,cccccccccccb,d74fbdf6a890,82211e0854e7369e83d941f24761a84e,881ae7bee927,2009-12-14T16:40:57,
|
|
||||||
serialnr 1 publicName cccccccccccb internalName d74fbdf6a890 aesKey 82211e0854e7369e83d941f24761a84e lockCode 881ae7bee927 created 2009-12-14T16:40:57 accessed eol
|
|
||||||
line: 2,cccccccccccd,7a5ad1886b70,3091a8048524ab8407ae816457d764e5,8e5ab609e346,2009-12-14T16:40:57,
|
|
||||||
serialnr 2 publicName cccccccccccd internalName 7a5ad1886b70 aesKey 3091a8048524ab8407ae816457d764e5 lockCode 8e5ab609e346 created 2009-12-14T16:40:57 accessed eol
|
|
||||||
line: 3,ccccccccccce,981abbbeafb8,91be4bfd2f40e24ebd39386868aa9619,037b6f6ae73c,2009-12-14T16:40:57,
|
|
||||||
serialnr 3 publicName ccccccccccce internalName 981abbbeafb8 aesKey 91be4bfd2f40e24ebd39386868aa9619 lockCode 037b6f6ae73c created 2009-12-14T16:40:57 accessed eol
|
|
||||||
line: 4,cccccccccccf,c1f33c17f77b,a2389839d7b80bfe4c80258184aff4ce,abf92cbbdab3,2009-12-14T16:40:57,
|
|
||||||
serialnr 4 publicName cccccccccccf internalName c1f33c17f77b aesKey a2389839d7b80bfe4c80258184aff4ce lockCode abf92cbbdab3 created 2009-12-14T16:40:57 accessed eol
|
|
||||||
line: 5,cccccccccccg,c55773192393,7387b5f6bede83f64a9cd75b2023826a,d70c937bbbff,2009-12-14T16:40:57,
|
|
||||||
serialnr 5 publicName cccccccccccg internalName c55773192393 aesKey 7387b5f6bede83f64a9cd75b2023826a lockCode d70c937bbbff created 2009-12-14T16:40:57 accessed eol
|
|
||||||
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
When importing large data sets it is recommended to avoid the
|
|
||||||
--verbose flag to reduce noise.
|
|
||||||
|
|
||||||
To test the import, you can attempt to decrypt an (invalid) OTP for
|
|
||||||
one of the AES keys. Like this:
|
|
||||||
|
|
||||||
user@ksm:~$ curl 'http://localhost/wsapi/decrypt?otp=cccccccccccdvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv'
|
|
||||||
ERR Corrupt OTP
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
In the system log file /var/log/ykksm.log you should get this error:
|
|
||||||
|
|
||||||
Dec 14 17:20:08 crater ykksm[12693]: UID error: cccccccccccdvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv a515841f249c5f4bb8e9007ab0f7ac2b: a515841f249c vs 7a5ad1886b70
|
|
||||||
|
|
||||||
Note that the actual values may differ slightly because the AES key
|
|
||||||
you generated was random.
|
|
||||||
85
doc/Import_Keys_To_KSM.adoc
Normal file
85
doc/Import_Keys_To_KSM.adoc
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
Import Keys To Yubikey KSM
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
To import keys into the YK-KSM database from text files in the
|
||||||
|
encrypted/signed KeyProvisioningFormat format, you can use the tool
|
||||||
|
'ykksm-import'. The tool reads the data on standard input, and will
|
||||||
|
import the data to the database. On any error, execution is aborted,
|
||||||
|
so be careful about partial imports leaving the database in an
|
||||||
|
intermediate state.
|
||||||
|
|
||||||
|
The tool requires that your system has a GnuPG private key, read
|
||||||
|
link:Generate_KSM_Key.adoc[Generate KSM Key] on how to generate it.
|
||||||
|
|
||||||
|
For example, to import the file generated by the
|
||||||
|
link:Generate_Keys.adoc[Generate Keys] document:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ ykksm-import --verbose --database 'DBI:Pg:dbname=ykksm;host=127.0.0.1' --db-user ykksmimporter --db-passwd otherpassword < ~/keys.txt
|
||||||
|
|
||||||
|
You need a passphrase to unlock the secret key for
|
||||||
|
user: "YK-KSM crater Import Key"
|
||||||
|
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
||||||
|
|
||||||
|
Verification output:
|
||||||
|
[GNUPG:] ENC_TO 8C73EAF1140A17F1 16 0
|
||||||
|
[GNUPG:] USERID_HINT 8C73EAF1140A17F1 YK-KSM crater Import Key
|
||||||
|
[GNUPG:] NEED_PASSPHRASE 8C73EAF1140A17F1 AE7279678B88A11B 16 0
|
||||||
|
[GNUPG:] GOOD_PASSPHRASE
|
||||||
|
gpg: encrypted with 2048-bit ELG-E key, ID 140A17F1, created 2009-12-14
|
||||||
|
"YK-KSM crater Import Key"
|
||||||
|
[GNUPG:] BEGIN_DECRYPTION
|
||||||
|
[GNUPG:] PLAINTEXT 62 1260805257
|
||||||
|
gpg: Signature made Mon 14 Dec 2009 04:40:57 PM CET using DSA key ID 8B88A11B
|
||||||
|
[GNUPG:] SIG_ID YGplk8qkUkb75lY0aurb/iS1Oog 2009-12-14 1260805257
|
||||||
|
[GNUPG:] GOODSIG AE7279678B88A11B YK-KSM crater Import Key
|
||||||
|
gpg: Good signature from "YK-KSM crater Import Key"
|
||||||
|
[GNUPG:] VALIDSIG 9B1820A2F02E3C3B84E344F5AE7279678B88A11B 2009-12-14 1260805257 0 4 0 17 2 00 9B1820A2F02E3C3B84E344F5AE7279678B88A11B
|
||||||
|
[GNUPG:] TRUST_ULTIMATE
|
||||||
|
[GNUPG:] DECRYPTION_OKAY
|
||||||
|
[GNUPG:] GOODMDC
|
||||||
|
[GNUPG:] END_DECRYPTION
|
||||||
|
encrypted to: 8C73EAF1140A17F1
|
||||||
|
signed by: 8B88A11B
|
||||||
|
|
||||||
|
You need a passphrase to unlock the secret key for
|
||||||
|
user: "YK-KSM crater Import Key"
|
||||||
|
2048-bit ELG-E key, ID 140A17F1, created 2009-12-14 (main key ID 8B88A11B)
|
||||||
|
|
||||||
|
line: 1,cccccccccccb,d74fbdf6a890,82211e0854e7369e83d941f24761a84e,881ae7bee927,2009-12-14T16:40:57,
|
||||||
|
serialnr 1 publicName cccccccccccb internalName d74fbdf6a890 aesKey 82211e0854e7369e83d941f24761a84e lockCode 881ae7bee927 created 2009-12-14T16:40:57 accessed eol
|
||||||
|
line: 2,cccccccccccd,7a5ad1886b70,3091a8048524ab8407ae816457d764e5,8e5ab609e346,2009-12-14T16:40:57,
|
||||||
|
serialnr 2 publicName cccccccccccd internalName 7a5ad1886b70 aesKey 3091a8048524ab8407ae816457d764e5 lockCode 8e5ab609e346 created 2009-12-14T16:40:57 accessed eol
|
||||||
|
line: 3,ccccccccccce,981abbbeafb8,91be4bfd2f40e24ebd39386868aa9619,037b6f6ae73c,2009-12-14T16:40:57,
|
||||||
|
serialnr 3 publicName ccccccccccce internalName 981abbbeafb8 aesKey 91be4bfd2f40e24ebd39386868aa9619 lockCode 037b6f6ae73c created 2009-12-14T16:40:57 accessed eol
|
||||||
|
line: 4,cccccccccccf,c1f33c17f77b,a2389839d7b80bfe4c80258184aff4ce,abf92cbbdab3,2009-12-14T16:40:57,
|
||||||
|
serialnr 4 publicName cccccccccccf internalName c1f33c17f77b aesKey a2389839d7b80bfe4c80258184aff4ce lockCode abf92cbbdab3 created 2009-12-14T16:40:57 accessed eol
|
||||||
|
line: 5,cccccccccccg,c55773192393,7387b5f6bede83f64a9cd75b2023826a,d70c937bbbff,2009-12-14T16:40:57,
|
||||||
|
serialnr 5 publicName cccccccccccg internalName c55773192393 aesKey 7387b5f6bede83f64a9cd75b2023826a lockCode d70c937bbbff created 2009-12-14T16:40:57 accessed eol
|
||||||
|
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
When importing large data sets it is recommended to avoid the
|
||||||
|
'--verbose' flag to reduce noise.
|
||||||
|
|
||||||
|
To test the import, you can attempt to decrypt an (invalid) OTP for
|
||||||
|
one of the AES keys. Like this:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ curl 'http://localhost/wsapi/decrypt?otp=cccccccccccdvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv'
|
||||||
|
ERR Corrupt OTP
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
In the system log file /var/log/ykksm.log you should get this error:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
Dec 14 17:20:08 crater ykksm[12693]: UID error: cccccccccccdvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv a515841f249c5f4bb8e9007ab0f7ac2b: a515841f249c vs 7a5ad1886b70
|
||||||
|
----
|
||||||
|
|
||||||
|
Note that the actual values may differ slightly because the AES key
|
||||||
|
you generated was random.
|
||||||
328
doc/Installation.adoc
Normal file
328
doc/Installation.adoc
Normal file
@ -0,0 +1,328 @@
|
|||||||
|
Installation and Configuration of Yubikey KSM
|
||||||
|
---------------------------------------------
|
||||||
|
|
||||||
|
The Yubikey KSM module is responsible for storing AES keys and
|
||||||
|
providing two interfaces:
|
||||||
|
|
||||||
|
* Decrypting an OTP
|
||||||
|
|
||||||
|
* Adding new AES keys
|
||||||
|
|
||||||
|
It is intentionally not possible to extract the AES keys or to make
|
||||||
|
modifications to the database content, see link:Design_Goals.adoc[DesignGoals].
|
||||||
|
|
||||||
|
The installation procedure documented below applies to any Unix-like
|
||||||
|
environment, although it was written for Debian GNU/Linux version 5.0
|
||||||
|
(aka "lenny").
|
||||||
|
|
||||||
|
Since version 1.1 of the YK-KSM, any database supported by the PHP PDO
|
||||||
|
interface is supported by the YK-KSM. To give concrete examples, we
|
||||||
|
will here explain how to set it up using MySQL or PostgreSQL. Note
|
||||||
|
that you only need to install either MySQL or PostgreSQL (or any other
|
||||||
|
supported database), not both!
|
||||||
|
|
||||||
|
Step 1: YK-KSM Installation
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
First you should download and install the latest YK-KSM release:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install wget make help2man
|
||||||
|
...
|
||||||
|
user@ksm:~$ wget http://yubico.github.com/yubikey-ksm/releases/yubikey-ksm-1.8.tgz
|
||||||
|
...
|
||||||
|
user@ksm:~$ tar xfz yubikey-ksm-1.8.tgz
|
||||||
|
user@ksm:~$ cd yubikey-ksm-1.8
|
||||||
|
user@ksm:~/yubikey-ksm-1.8$ sudo make install
|
||||||
|
...
|
||||||
|
user@ksm:~/yubikey-ksm-1.8$
|
||||||
|
----
|
||||||
|
|
||||||
|
Alternatively, you may also check out YK-KSM from its source code repository. For example:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install git make help2man
|
||||||
|
...
|
||||||
|
user@ksm:~$ git clone git://github.com/Yubico/yubikey-ksm.git
|
||||||
|
...
|
||||||
|
user@ksm:~$ cd yubikey-ksm
|
||||||
|
user@ksm:~/yubikey-ksm$ sudo make install
|
||||||
|
...
|
||||||
|
user@ksm:~/yubikey-ksm$
|
||||||
|
----
|
||||||
|
|
||||||
|
The rest of this documentation will assume you have installed the
|
||||||
|
YK-KSM with 'make install'.
|
||||||
|
|
||||||
|
Step 2: Install web server and PHP
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You will need to install a web server with PHP5 and the PHP mcrypt
|
||||||
|
interface:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
user@ksm:~$ sudo apt-get install apache2 php5 php5-mcrypt
|
||||||
|
|
||||||
|
Any web server with PHP support should work.
|
||||||
|
|
||||||
|
Step 3A: MySQL Installation
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Install the required packages:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install mysql-server php5-mysql libdbd-mysql-perl
|
||||||
|
...
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
The installation asks you for a MySQL "root" password, and I recommend
|
||||||
|
to specify one.
|
||||||
|
|
||||||
|
To avoid having to specify a password when using the 'mysql' tool
|
||||||
|
interactively, you can store the password in ~/.my.cnf, see
|
||||||
|
/usr/share/doc/mysql-server-5.0/README.Debian.gz. For example:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ cat > .my.cnf
|
||||||
|
[client]
|
||||||
|
user = root
|
||||||
|
password = YOURPASSWORD
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
First create the database and the tables as follows:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ echo 'create database ykksm' | mysql
|
||||||
|
user@ksm:~$ mysql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
You should also create database users for the decrypt and import
|
||||||
|
interfaces, normally called 'ykksmreader' and 'ykksmimporter':
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ mysql --silent ykksm
|
||||||
|
mysql> CREATE USER 'ykksmreader';
|
||||||
|
mysql> GRANT SELECT ON ykksm.yubikeys TO 'ykksmreader'@'localhost';
|
||||||
|
mysql> SET PASSWORD FOR 'ykksmreader'@'localhost' = PASSWORD('yourpassword');
|
||||||
|
mysql> CREATE USER 'ykksmimporter';
|
||||||
|
mysql> GRANT INSERT ON ykksm.yubikeys TO 'ykksmimporter'@'localhost';
|
||||||
|
mysql> SET PASSWORD FOR 'ykksmimporter'@'localhost' = PASSWORD('otherpassword');
|
||||||
|
mysql> FLUSH PRIVILEGES;
|
||||||
|
mysql> \q
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Step 3B: PostgreSQL Installation
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Install some packages:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install postgresql php5-pgsql libdbd-pg-perl
|
||||||
|
...
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
The database needs to be initialized as follows:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo su postgres
|
||||||
|
postgres@ksm:~$ createdb ykksm
|
||||||
|
postgres@ksm:~$ psql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql
|
||||||
|
postgres@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
You also need to create a user for the decrypt interface, normally
|
||||||
|
called 'ykksmreader':
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
postgres@ksm:~$ psql ykksm -q
|
||||||
|
ykksm=# CREATE USER ykksmreader PASSWORD 'yourpassword';
|
||||||
|
ykksm=# GRANT SELECT ON yubikeys TO ykksmreader;
|
||||||
|
ykksm=# CREATE USER ykksmimporter PASSWORD 'otherpassword';
|
||||||
|
ykksm=# GRANT INSERT ON yubikeys TO ykksmimporter;
|
||||||
|
ykksm=# \q
|
||||||
|
postgres@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
During installation and debugging it may be useful to watch the
|
||||||
|
database log entries:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
user@ksm:~$ sudo tail -F /var/log/postgresql/postgresql-*-main.log &
|
||||||
|
|
||||||
|
Step 4: Include path configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Set the include path by creating a file /etc/php5/conf.d/ykksm.ini
|
||||||
|
with the following content:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /etc/php5/conf.d/ykksm.ini'
|
||||||
|
include_path = "/etc/yubico/ksm:/usr/share/yubikey-ksm"
|
||||||
|
user@ksm:~$ sudo /etc/init.d/apache2 restart
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
The paths are the default, if you installed the YK-KSM in some other
|
||||||
|
place you need to modify the paths.
|
||||||
|
|
||||||
|
Step 5: Logging
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The PHP interface uses syslog for logging of incoming requests. The
|
||||||
|
facility is set in ykksm-config.php but defaults the LOG_LOCAL0. To
|
||||||
|
place these messages in a separate file, you can add the following to
|
||||||
|
/etc/syslog.conf, or if you use rsyslog, create a file
|
||||||
|
/etc/rsyslog.d/ykksm.conf with this content:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykksm.conf'
|
||||||
|
local0.* -/var/log/ykksm.log
|
||||||
|
user@ksm:~$ sudo /etc/init.d/rsyslog restart
|
||||||
|
...
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
The '-' before the filename avoids syncing the file after each write,
|
||||||
|
which is recommended for performance.
|
||||||
|
|
||||||
|
The log file can grow large quickly, so it is a good idea to setup
|
||||||
|
rotation of log files. Here is an example that rotates the log file
|
||||||
|
weekly. Create a file /etc/logrotate.d/ykksm like this:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /etc/logrotate.d/ykksm'
|
||||||
|
/var/log/ykksm.log {
|
||||||
|
weekly
|
||||||
|
missingok
|
||||||
|
rotate 9999
|
||||||
|
notifempty
|
||||||
|
postrotate
|
||||||
|
invoke-rc.d rsyslog reload > /dev/null
|
||||||
|
endscript
|
||||||
|
}
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Step 5.1: Fix default log (optional)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Unfortunately, most default syslog configuration, including the
|
||||||
|
syslog.conf configuration file on Debian, will also log all entries to
|
||||||
|
/var/log/syslog and/or /var/log/messages.
|
||||||
|
|
||||||
|
I am not aware of any way to avoid this without modifying these other
|
||||||
|
rules. To avoid YK-KSM log entries in these other files, you must
|
||||||
|
modify the default rules. For example, edit the following lines of
|
||||||
|
/etc/rsyslog.conf (or /etc/syslog.conf if you don't use rsyslog):
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
*.*;auth,authpriv.none -/var/log/syslog
|
||||||
|
*.=info;*.=notice;*.=warn;\
|
||||||
|
auth,authpriv.none;\
|
||||||
|
cron,daemon.none;\
|
||||||
|
mail,news.none -/var/log/messages
|
||||||
|
----
|
||||||
|
|
||||||
|
Change them into:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
*.*;auth,authpriv.none,local0.none -/var/log/syslog
|
||||||
|
*.=info;*.=notice;*.=warn;\
|
||||||
|
auth,authpriv.none;\
|
||||||
|
cron,daemon.none;\
|
||||||
|
local0.none;\
|
||||||
|
mail,news.none -/var/log/messages
|
||||||
|
----
|
||||||
|
|
||||||
|
Step 6: Decrypt OTP Interface
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The interface to decrypt OTPs is implemented using a PHP script. You
|
||||||
|
can place the script under any URL, but we recommend serving it as
|
||||||
|
http://ykksm.example.org/wsapi/decrypt. The simplest way is to use
|
||||||
|
the 'symlink' rule in our makefile:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo make -f /usr/share/doc/yubikey-ksm/ykksm.mk symlink
|
||||||
|
install -d /var/www/wsapi
|
||||||
|
ln -sf /usr/share/yubikey-ksm/.htaccess /var/www/wsapi/.htaccess
|
||||||
|
ln -sf /usr/share/yubikey-ksm/ykksm-decrypt.php /var/www/wsapi/decrypt.php
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
You may also run the commands manually.
|
||||||
|
|
||||||
|
Step 7: YK-KSM Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You need to edit the ykksm-config.php script. An example file is
|
||||||
|
included in YK-KSM as 'ykksm-config.php'. It is normally installed as
|
||||||
|
/etc/yubico/ksm/ykksm-config.php:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo cat /etc/yubico/ksm/ykksm-config.php
|
||||||
|
<?php
|
||||||
|
$db_dsn = "mysql:dbname=ykksm;host=127.0.0.1";
|
||||||
|
$db_username = "ykksmreader";
|
||||||
|
$db_password = "yourpassword";
|
||||||
|
$db_options = array();
|
||||||
|
$logfacility = LOG_LOCAL0;
|
||||||
|
?>
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Be careful about the user permissions and ownership so that unrelated
|
||||||
|
users on the system cannot read the database password.
|
||||||
|
|
||||||
|
Typically you only need to modify the database password, and possibly
|
||||||
|
the database definition in $db_dsn. Example DSN for a MySQL setup:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
$db_dsn = "mysql:dbname=ykksm;host=127.0.0.1";
|
||||||
|
|
||||||
|
An example DSN for a PostgreSQL setup:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
$db_dsn = "pgsql:dbname=ykksm;host=127.0.0.1";
|
||||||
|
|
||||||
|
The End
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
You now have a YK-KSM up and running. You can test the service by
|
||||||
|
requesting a URL. Using wget, for example:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install wget
|
||||||
|
user@ksm:~$ wget -q -O - 'http://localhost/wsapi/decrypt?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh'
|
||||||
|
ERR Unknown yubikey
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
You will need to import keys into the database for the decrypt function
|
||||||
|
to do anything useful. See link:Server_Hardening.adoc[Server Hardening]
|
||||||
|
on how to improve security of your system. Likely next steps are
|
||||||
|
link:Generate_KSM_Key.adoc[Generate KSM Key],
|
||||||
|
link:Generate_Keys.adoc[Generate Keys] and/or
|
||||||
|
link:Import_Keys_To_KSM.adoc[Import Keys To KSM].
|
||||||
@ -1,271 +0,0 @@
|
|||||||
Installation and Configuration of Yubikey KSM
|
|
||||||
---------------------------------------------
|
|
||||||
|
|
||||||
The Yubikey KSM module is responsible for storing AES keys and
|
|
||||||
providing two interfaces:
|
|
||||||
|
|
||||||
* Decrypting an OTP
|
|
||||||
|
|
||||||
* Adding new AES keys
|
|
||||||
|
|
||||||
It is intentionally not possible to extract the AES keys or to make
|
|
||||||
modifications to the database content, see [[DesignGoals]].
|
|
||||||
|
|
||||||
The installation procedure documented below applies to any Unix-like
|
|
||||||
environment, although it was written for Debian GNU/Linux version 5.0
|
|
||||||
(aka "lenny").
|
|
||||||
|
|
||||||
Since version 1.1 of the YK-KSM, any database supported by the PHP PDO
|
|
||||||
interface is supported by the YK-KSM. To give concrete examples, we
|
|
||||||
will here explain how to set it up using MySQL or PostgreSQL. Note
|
|
||||||
that you only need to install either MySQL or PostgreSQL (or any other
|
|
||||||
supported database), not both!
|
|
||||||
|
|
||||||
Step 1: YK-KSM Installation
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
First you should download and install the latest YK-KSM release:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install wget make help2man
|
|
||||||
...
|
|
||||||
user@ksm:~$ wget http://yubico.github.com/yubikey-ksm/releases/yubikey-ksm-1.8.tgz
|
|
||||||
...
|
|
||||||
user@ksm:~$ tar xfz yubikey-ksm-1.8.tgz
|
|
||||||
user@ksm:~$ cd yubikey-ksm-1.8
|
|
||||||
user@ksm:~/yubikey-ksm-1.8$ sudo make install
|
|
||||||
...
|
|
||||||
user@ksm:~/yubikey-ksm-1.8$
|
|
||||||
|
|
||||||
Alternatively, you may also check out YK-KSM from its source code repository. For example:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install git make help2man
|
|
||||||
...
|
|
||||||
user@ksm:~$ git clone git://github.com/Yubico/yubikey-ksm.git
|
|
||||||
...
|
|
||||||
user@ksm:~$ cd yubikey-ksm
|
|
||||||
user@ksm:~/yubikey-ksm$ sudo make install
|
|
||||||
...
|
|
||||||
user@ksm:~/yubikey-ksm$
|
|
||||||
|
|
||||||
The rest of this documentation will assume you have installed the
|
|
||||||
YK-KSM with 'make install'.
|
|
||||||
|
|
||||||
Step 2: Install web server and PHP
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
You will need to install a web server with PHP5 and the PHP mcrypt
|
|
||||||
interface:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install apache2 php5 php5-mcrypt
|
|
||||||
|
|
||||||
Any web server with PHP support should work.
|
|
||||||
|
|
||||||
Step 3A: MySQL Installation
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
Install the required packages:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install mysql-server php5-mysql libdbd-mysql-perl
|
|
||||||
...
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
The installation asks you for a MySQL "root" password, and I recommend
|
|
||||||
to specify one.
|
|
||||||
|
|
||||||
To avoid having to specify a password when using the 'mysql' tool
|
|
||||||
interactively, you can store the password in ~/.my.cnf, see
|
|
||||||
/usr/share/doc/mysql-server-5.0/README.Debian.gz. For example:
|
|
||||||
|
|
||||||
user@ksm:~$ cat > .my.cnf
|
|
||||||
[client]
|
|
||||||
user = root
|
|
||||||
password = YOURPASSWORD
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
First create the database and the tables as follows:
|
|
||||||
|
|
||||||
user@ksm:~$ echo 'create database ykksm' | mysql
|
|
||||||
user@ksm:~$ mysql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
You should also create database users for the decrypt and import
|
|
||||||
interfaces, normally called 'ykksmreader' and 'ykksmimporter':
|
|
||||||
|
|
||||||
user@ksm:~$ mysql --silent ykksm
|
|
||||||
mysql> CREATE USER 'ykksmreader';
|
|
||||||
mysql> GRANT SELECT ON ykksm.yubikeys TO 'ykksmreader'@'localhost';
|
|
||||||
mysql> SET PASSWORD FOR 'ykksmreader'@'localhost' = PASSWORD('yourpassword');
|
|
||||||
mysql> CREATE USER 'ykksmimporter';
|
|
||||||
mysql> GRANT INSERT ON ykksm.yubikeys TO 'ykksmimporter'@'localhost';
|
|
||||||
mysql> SET PASSWORD FOR 'ykksmimporter'@'localhost' = PASSWORD('otherpassword');
|
|
||||||
mysql> FLUSH PRIVILEGES;
|
|
||||||
mysql> \q
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Step 3B: PostgreSQL Installation
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
Install some packages:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install postgresql php5-pgsql libdbd-pg-perl
|
|
||||||
...
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
The database needs to be initialized as follows:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo su postgres
|
|
||||||
postgres@ksm:~$ createdb ykksm
|
|
||||||
postgres@ksm:~$ psql ykksm < /usr/share/doc/yubikey-ksm/ykksm-db.sql
|
|
||||||
postgres@ksm:~$
|
|
||||||
|
|
||||||
You also need to create a user for the decrypt interface, normally
|
|
||||||
called 'ykksmreader':
|
|
||||||
|
|
||||||
postgres@ksm:~$ psql ykksm -q
|
|
||||||
ykksm=# CREATE USER ykksmreader PASSWORD 'yourpassword';
|
|
||||||
ykksm=# GRANT SELECT ON yubikeys TO ykksmreader;
|
|
||||||
ykksm=# CREATE USER ykksmimporter PASSWORD 'otherpassword';
|
|
||||||
ykksm=# GRANT INSERT ON yubikeys TO ykksmimporter;
|
|
||||||
ykksm=# \q
|
|
||||||
postgres@ksm:~$
|
|
||||||
|
|
||||||
During installation and debugging it may be useful to watch the
|
|
||||||
database log entries:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo tail -F /var/log/postgresql/postgresql-*-main.log &
|
|
||||||
|
|
||||||
Step 4: Include path configuration
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
Set the include path by creating a file /etc/php5/conf.d/ykksm.ini
|
|
||||||
with the following content:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /etc/php5/conf.d/ykksm.ini'
|
|
||||||
include_path = "/etc/yubico/ksm:/usr/share/yubikey-ksm"
|
|
||||||
user@ksm:~$ sudo /etc/init.d/apache2 restart
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
The paths are the default, if you installed the YK-KSM in some other
|
|
||||||
place you need to modify the paths.
|
|
||||||
|
|
||||||
Step 5: Logging
|
|
||||||
---------------
|
|
||||||
|
|
||||||
The PHP interface uses syslog for logging of incoming requests. The
|
|
||||||
facility is set in ykksm-config.php but defaults the LOG_LOCAL0. To
|
|
||||||
place these messages in a separate file, you can add the following to
|
|
||||||
/etc/syslog.conf, or if you use rsyslog, create a file
|
|
||||||
/etc/rsyslog.d/ykksm.conf with this content:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /etc/rsyslog.d/ykksm.conf'
|
|
||||||
local0.* -/var/log/ykksm.log
|
|
||||||
user@ksm:~$ sudo /etc/init.d/rsyslog restart
|
|
||||||
...
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
The '-' before the filename avoids syncing the file after each write,
|
|
||||||
which is recommended for performance.
|
|
||||||
|
|
||||||
The log file can grow large quickly, so it is a good idea to setup
|
|
||||||
rotation of log files. Here is an example that rotates the log file
|
|
||||||
weekly. Create a file /etc/logrotate.d/ykksm like this:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /etc/logrotate.d/ykksm'
|
|
||||||
/var/log/ykksm.log {
|
|
||||||
weekly
|
|
||||||
missingok
|
|
||||||
rotate 9999
|
|
||||||
notifempty
|
|
||||||
postrotate
|
|
||||||
invoke-rc.d rsyslog reload > /dev/null
|
|
||||||
endscript
|
|
||||||
}
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Step 5.1: Fix default log (optional)
|
|
||||||
------------------------------------
|
|
||||||
|
|
||||||
Unfortunately, most default syslog configuration, including the
|
|
||||||
syslog.conf configuration file on Debian, will also log all entries to
|
|
||||||
/var/log/syslog and/or /var/log/messages.
|
|
||||||
|
|
||||||
I am not aware of any way to avoid this without modifying these other
|
|
||||||
rules. To avoid YK-KSM log entries in these other files, you must
|
|
||||||
modify the default rules. For example, edit the following lines of
|
|
||||||
/etc/rsyslog.conf (or /etc/syslog.conf if you don't use rsyslog):
|
|
||||||
|
|
||||||
*.*;auth,authpriv.none -/var/log/syslog
|
|
||||||
*.=info;*.=notice;*.=warn;\
|
|
||||||
auth,authpriv.none;\
|
|
||||||
cron,daemon.none;\
|
|
||||||
mail,news.none -/var/log/messages
|
|
||||||
|
|
||||||
Change them into:
|
|
||||||
|
|
||||||
*.*;auth,authpriv.none,local0.none -/var/log/syslog
|
|
||||||
*.=info;*.=notice;*.=warn;\
|
|
||||||
auth,authpriv.none;\
|
|
||||||
cron,daemon.none;\
|
|
||||||
local0.none;\
|
|
||||||
mail,news.none -/var/log/messages
|
|
||||||
|
|
||||||
Step 6: Decrypt OTP Interface
|
|
||||||
-----------------------------
|
|
||||||
|
|
||||||
The interface to decrypt OTPs is implemented using a PHP script. You
|
|
||||||
can place the script under any URL, but we recommend serving it as
|
|
||||||
http://ykksm.example.org/wsapi/decrypt. The simplest way is to use
|
|
||||||
the 'symlink' rule in our makefile:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo make -f /usr/share/doc/yubikey-ksm/ykksm.mk symlink
|
|
||||||
install -d /var/www/wsapi
|
|
||||||
ln -sf /usr/share/yubikey-ksm/.htaccess /var/www/wsapi/.htaccess
|
|
||||||
ln -sf /usr/share/yubikey-ksm/ykksm-decrypt.php /var/www/wsapi/decrypt.php
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
You may also run the commands manually.
|
|
||||||
|
|
||||||
Step 7: YK-KSM Configuration
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
You need to edit the ykksm-config.php script. An example file is
|
|
||||||
included in YK-KSM as 'ykksm-config.php'. It is normally installed as
|
|
||||||
/etc/yubico/ksm/ykksm-config.php:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo cat /etc/yubico/ksm/ykksm-config.php
|
|
||||||
<?php
|
|
||||||
$db_dsn = "mysql:dbname=ykksm;host=127.0.0.1";
|
|
||||||
$db_username = "ykksmreader";
|
|
||||||
$db_password = "yourpassword";
|
|
||||||
$db_options = array();
|
|
||||||
$logfacility = LOG_LOCAL0;
|
|
||||||
?>
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Be careful about the user permissions and ownership so that unrelated
|
|
||||||
users on the system cannot read the database password.
|
|
||||||
|
|
||||||
Typically you only need to modify the database password, and possibly
|
|
||||||
the database definition in $db_dsn. Example DSN for a MySQL setup:
|
|
||||||
|
|
||||||
$db_dsn = "mysql:dbname=ykksm;host=127.0.0.1";
|
|
||||||
|
|
||||||
An example DSN for a PostgreSQL setup:
|
|
||||||
|
|
||||||
$db_dsn = "pgsql:dbname=ykksm;host=127.0.0.1";
|
|
||||||
|
|
||||||
The End
|
|
||||||
-------
|
|
||||||
|
|
||||||
You now have a YK-KSM up and running. You can test the service by
|
|
||||||
requesting a URL. Using wget, for example:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install wget
|
|
||||||
user@ksm:~$ wget -q -O - 'http://localhost/wsapi/decrypt?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh'
|
|
||||||
ERR Unknown yubikey
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
You will need to import keys into the database for the decrypt
|
|
||||||
function to do anything useful. See [[ServerHardening]] on how to
|
|
||||||
improve security of your system. Likely next steps are
|
|
||||||
[[GenerateKSMKey]], [[GenerateKeys]] and/or [[ImportKeysToKSM]].
|
|
||||||
@ -23,90 +23,86 @@ are also treated as comments.
|
|||||||
|
|
||||||
The meaning are as follows:
|
The meaning are as follows:
|
||||||
|
|
||||||
* serialNr:
|
serialNr::
|
||||||
|
|
||||||
the serial number of the device used for the barcode, decimal integer
|
the serial number of the device used for the barcode, decimal integer
|
||||||
|
|
||||||
* publicName:
|
publicName::
|
||||||
|
|
||||||
encoding of the "external" yubikey prefix, 0-16 modhex characters, typically 12
|
encoding of the "external" yubikey prefix, 0-16 modhex characters, typically 12
|
||||||
modhex encoded data
|
modhex encoded data
|
||||||
|
|
||||||
* internalName:
|
internalName::
|
||||||
|
|
||||||
encoding of the "internal" yubikey identity, always 6 binary bytes = 12 hex,
|
encoding of the "internal" yubikey identity, always 6 binary bytes = 12 hex,
|
||||||
hex encoded data
|
hex encoded data
|
||||||
|
|
||||||
* aesKey:
|
aesKey::
|
||||||
|
|
||||||
an aes key used for the device, length decides whether it is a 128, 192, or 256 bit keys.
|
an aes key used for the device, length decides whether it is a 128, 192, or 256 bit keys.
|
||||||
hex encoded data
|
hex encoded data
|
||||||
|
|
||||||
* lockCode:
|
lockCode::
|
||||||
|
|
||||||
the locking code, always 6 binary bytes = 12 hex,
|
the locking code, always 6 binary bytes = 12 hex,
|
||||||
hex encoded data
|
hex encoded data
|
||||||
|
|
||||||
* created:
|
created::
|
||||||
|
|
||||||
timestamp of when the key was created
|
timestamp of when the key was created
|
||||||
for example 2009-02-24T17:41:57 or empty
|
for example 2009-02-24T17:41:57 or empty
|
||||||
|
|
||||||
* accessed:
|
accessed::
|
||||||
|
|
||||||
timestamp of when the key was last accessed
|
timestamp of when the key was last accessed
|
||||||
for example 2009-02-24T17:41:57 or empty
|
for example 2009-02-24T17:41:57 or empty
|
||||||
|
|
||||||
* progflags:
|
progflags::
|
||||||
|
|
||||||
optional field, integer with flags used during personalization
|
optional field, integer with flags used during personalization
|
||||||
to enable, e.g., static key mode or cr output
|
to enable, e.g., static key mode or cr output
|
||||||
|
|
||||||
Examples of valid data lines:
|
Examples of valid data lines:
|
||||||
|
|
||||||
4711,dlcfffckrcde,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,
|
....
|
||||||
4712,,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40
|
4711,dlcfffckrcde,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,
|
||||||
4713,dlcfffckrcdedlcf,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40,0
|
4712,,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40
|
||||||
4714,dlcfffckrcdedlcf,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40,4711
|
4713,dlcfffckrcdedlcf,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40,0
|
||||||
|
4714,dlcfffckrcdedlcf,ca62baca62ba,ecde18dbe76fbd0c33330f1c354871db,be70aeca62ba,2009-01-22 00:25:11,2009-02-13 00:05:40,4711
|
||||||
|
....
|
||||||
|
|
||||||
Example of actual data using the password 'foobar' (normally it would
|
Example of actual data using the password 'foobar' (normally it would
|
||||||
be encrypted to a particular OpenPGP key id):
|
be encrypted to a particular OpenPGP key id):
|
||||||
|
|
||||||
....
|
....
|
||||||
-----BEGIN PGP MESSAGE-----
|
-----BEGIN PGP MESSAGE-----
|
||||||
Version: GnuPG v1.4.9 (GNU/Linux)
|
Version: GnuPG v1.4.9 (GNU/Linux)
|
||||||
|
|
||||||
jA0EAwMClfljrWYVfm5gycDMIpZXLnzKtUfeEsqXRp63IdAghBzAfdIt4aeJ2kdV
|
jA0EAwMClfljrWYVfm5gycDMIpZXLnzKtUfeEsqXRp63IdAghBzAfdIt4aeJ2kdV
|
||||||
x8uvvHKeHfytjEo/U9Wg4NYqYoDnMeb4zXBmrRqWu558ldW75e5R2kPImuQnZIBQ
|
x8uvvHKeHfytjEo/U9Wg4NYqYoDnMeb4zXBmrRqWu558ldW75e5R2kPImuQnZIBQ
|
||||||
3WKRbElrLpQTlbdyDDAzlOnVLvTrmekZ8ByUrED3tyZKJw7OW5YsHi3z5N+QNFbZ
|
3WKRbElrLpQTlbdyDDAzlOnVLvTrmekZ8ByUrED3tyZKJw7OW5YsHi3z5N+QNFbZ
|
||||||
hpMWfDBiJRksQEXv3BbiWVojSS+ZlCBiDjqnbIGuk0nZlJSe3F3Jwdz22Y05aU2h
|
hpMWfDBiJRksQEXv3BbiWVojSS+ZlCBiDjqnbIGuk0nZlJSe3F3Jwdz22Y05aU2h
|
||||||
+2e6vWkqsbvZMVHnU6pauyaM1dh2owXsoHCPLM1fs7ztIh5dAnV9d0TuW4ufKEFQ
|
+2e6vWkqsbvZMVHnU6pauyaM1dh2owXsoHCPLM1fs7ztIh5dAnV9d0TuW4ufKEFQ
|
||||||
FdH5c4dNgl36CNM8dDlM3c8YpfjxlQ11e6ub7QZC1Eu3gqvfPIvYpczlwjkYOkcH
|
FdH5c4dNgl36CNM8dDlM3c8YpfjxlQ11e6ub7QZC1Eu3gqvfPIvYpczlwjkYOkcH
|
||||||
nu1Iq42VgUSJzBr36aL9lLySyT8WRizzmJLaGYX/YqKgBXt6RTSO984WsxE6cl80
|
nu1Iq42VgUSJzBr36aL9lLySyT8WRizzmJLaGYX/YqKgBXt6RTSO984WsxE6cl80
|
||||||
paFvFOjybJ2V5GYc7pfdZAM2ySEhnS6PaxYAQXfrEhhtTTCCg1eCqKh4Yamv3u0v
|
paFvFOjybJ2V5GYc7pfdZAM2ySEhnS6PaxYAQXfrEhhtTTCCg1eCqKh4Yamv3u0v
|
||||||
DAkppMqXeprjpC4cNvrQsVOKGx7HissA5x4rECLC
|
DAkppMqXeprjpC4cNvrQsVOKGx7HissA5x4rECLC
|
||||||
=d54w
|
=d54w
|
||||||
-----END PGP MESSAGE-----
|
-----END PGP MESSAGE-----
|
||||||
....
|
....
|
||||||
|
|
||||||
Naming Scheme
|
Naming Scheme
|
||||||
-------------
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
The files should use the standard GnuPG output extension '.asc'.
|
The files should use the standard GnuPG output extension '.asc'.
|
||||||
|
|
||||||
If you want to store many keys in a one-key per file approach, we
|
If you want to store many keys in a one-key per file approach, we
|
||||||
suggest to create files named after the serial number. For example:
|
suggest to create files named after the serial number. For example:
|
||||||
|
|
||||||
0.asc
|
....
|
||||||
1.asc
|
0.asc
|
||||||
2.asc
|
1.asc
|
||||||
3.asc
|
2.asc
|
||||||
4.asc
|
3.asc
|
||||||
5.asc
|
4.asc
|
||||||
6.asc
|
5.asc
|
||||||
7.asc
|
6.asc
|
||||||
8.asc
|
7.asc
|
||||||
9.asc
|
8.asc
|
||||||
10.asc
|
9.asc
|
||||||
11.asc
|
10.asc
|
||||||
...
|
11.asc
|
||||||
|
...
|
||||||
|
....
|
||||||
@ -5,7 +5,7 @@ The point of this document is to describe all steps required to make a
|
|||||||
proper release of the yubikey-personalization project.
|
proper release of the yubikey-personalization project.
|
||||||
|
|
||||||
Dependencies
|
Dependencies
|
||||||
------------
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
Making a release requires the following packages:
|
Making a release requires the following packages:
|
||||||
|
|
||||||
@ -16,7 +16,7 @@ which can be installed (under Ubuntu) by running:
|
|||||||
sudo apt-get install make git gnupg help2man git2cl
|
sudo apt-get install make git gnupg help2man git2cl
|
||||||
|
|
||||||
Details
|
Details
|
||||||
-------
|
~~~~~~~
|
||||||
|
|
||||||
* Make sure the version number in Makefile has been incremented.
|
* Make sure the version number in Makefile has been incremented.
|
||||||
|
|
||||||
@ -1,256 +0,0 @@
|
|||||||
Server Hardening
|
|
||||||
----------------
|
|
||||||
|
|
||||||
While the defaults should be secure, there are some simple
|
|
||||||
administrative actions that will increase your overall security. None
|
|
||||||
of these steps are required, but we encourage you to read this
|
|
||||||
document to see if the enhancements are relevant for your environment.
|
|
||||||
|
|
||||||
Tighten PHP configuration
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
Tighten the security of the PHP installation by creating a file
|
|
||||||
/etc/php5/conf.d/harden.ini with the following content:
|
|
||||||
|
|
||||||
user@host:~$ sudo sh -c 'cat > /etc/php5/conf.d/harden.ini'
|
|
||||||
display_errors = Off
|
|
||||||
log_errors = On
|
|
||||||
user@host:~$
|
|
||||||
|
|
||||||
Tighten Apache configuration
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Tighten the security of the Apache installation by making sure
|
|
||||||
directory listings are disabled globally. Edit
|
|
||||||
/etc/apache2/conf.d/security and make sure the following is
|
|
||||||
uncommented:
|
|
||||||
|
|
||||||
<Directory />
|
|
||||||
AllowOverride None
|
|
||||||
Order Deny,Allow
|
|
||||||
Deny from all
|
|
||||||
</Directory>
|
|
||||||
|
|
||||||
Time Synchronization
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
For logging and (on the validation server) time-stamping it is
|
|
||||||
important to have synchronized clocks. Install ntp.
|
|
||||||
|
|
||||||
user@host:~$ sudo apt-get install ntp
|
|
||||||
...
|
|
||||||
|
|
||||||
Firewall
|
|
||||||
--------
|
|
||||||
|
|
||||||
There is no reason why the KSM needs to listen to incoming requests
|
|
||||||
from the entire Internet, and restricting access to the intended
|
|
||||||
YK-VAL servers are recommended.
|
|
||||||
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
|
||||||
#!/bin/sh
|
|
||||||
# IPv4 firewall:
|
|
||||||
iptables -F
|
|
||||||
iptables -P INPUT DROP
|
|
||||||
iptables -P FORWARD DROP
|
|
||||||
iptables -P OUTPUT ACCEPT
|
|
||||||
iptables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 -s 1.2.3.4 --dport 22 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 -s 2.3.4.5 --dport 80 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 -s 2.3.4.5 --dport 443 -j ACCEPT
|
|
||||||
# IPv6 firewall:
|
|
||||||
ip6tables -F
|
|
||||||
ip6tables -P INPUT DROP
|
|
||||||
ip6tables -P FORWARD DROP
|
|
||||||
ip6tables -P OUTPUT ACCEPT
|
|
||||||
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 -s 2000:1:2::3 --dport 22 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 -s 2000:2:3::4 --dport 80 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 -s 2000:2:3::4 --dport 443 -j ACCEPT
|
|
||||||
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the address
|
|
||||||
of the host you want to be able to login from via SSH, and replace
|
|
||||||
2.3.4.5 (for IPv4) and 2000:2:3::4 (for IPv6) with the address of the
|
|
||||||
YK-VAL that will be accessing this YK-KSM. Add more lines for each
|
|
||||||
validation server and SSH host.
|
|
||||||
|
|
||||||
For a validation server, you may want to allow HTTP(S) requests from
|
|
||||||
anyone, but not anything else.
|
|
||||||
|
|
||||||
user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
|
||||||
#!/bin/sh
|
|
||||||
# IPv4 firewall
|
|
||||||
iptables -F
|
|
||||||
iptables -P INPUT DROP
|
|
||||||
iptables -P FORWARD DROP
|
|
||||||
iptables -P OUTPUT ACCEPT
|
|
||||||
iptables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 -s 1.2.3.4 --dport 22 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
|
||||||
# IPv6 firewall:
|
|
||||||
ip6tables -F
|
|
||||||
ip6tables -P INPUT DROP
|
|
||||||
ip6tables -P FORWARD DROP
|
|
||||||
ip6tables -P OUTPUT ACCEPT
|
|
||||||
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 -s 2000:1:2::3 --dport 22 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
|
||||||
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
|
||||||
user@ksm:~$
|
|
||||||
|
|
||||||
Again, replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the
|
|
||||||
address of the host you want to be able to login from via SSH.
|
|
||||||
|
|
||||||
If you want to allow SSH and HTTP(S) from everywhere, but nothing
|
|
||||||
else, try this:
|
|
||||||
|
|
||||||
user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
|
||||||
#!/bin/sh
|
|
||||||
# IPv4 firewall
|
|
||||||
iptables -F
|
|
||||||
iptables -P INPUT DROP
|
|
||||||
iptables -P FORWARD DROP
|
|
||||||
iptables -P OUTPUT ACCEPT
|
|
||||||
iptables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 --dport 22 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
|
||||||
iptables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
|
||||||
# IPv6 firewall:
|
|
||||||
ip6tables -F
|
|
||||||
ip6tables -P INPUT DROP
|
|
||||||
ip6tables -P FORWARD DROP
|
|
||||||
ip6tables -P OUTPUT ACCEPT
|
|
||||||
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
|
||||||
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 --dport 22 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
|
||||||
ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
|
||||||
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
|
||||||
user@val:~$
|
|
||||||
|
|
||||||
Database Encryption
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
The database contains sensitive information. If someone is able to
|
|
||||||
access your machine physically, they may shut it off and steal it with
|
|
||||||
the goal of reading out the sensitive information. By encrypting the
|
|
||||||
disk, you can prevent this. Note that this does not protect against
|
|
||||||
an attacker who has physical access to your server and sufficient time
|
|
||||||
to read out the data from the already running system.
|
|
||||||
|
|
||||||
Full disk encryption will give you the highest protection, but
|
|
||||||
requires that you can enter the disk encryption password on each
|
|
||||||
power-up. This can be unpractical when your hosting environment is
|
|
||||||
remote.
|
|
||||||
|
|
||||||
Partial disk encryption allows the operating system to start up, and
|
|
||||||
enable you to login to the machine remotely to enter the disk
|
|
||||||
encryption password. This is less secure than full disk encryption,
|
|
||||||
because an attacker could physically disconnect your machine, modify
|
|
||||||
the operating system to send a copy of the password to the attacker,
|
|
||||||
but may be sufficient if you keep good track of when your machine is
|
|
||||||
not working properly.
|
|
||||||
|
|
||||||
To use partial disk encryption for the database content, we suggest
|
|
||||||
you install the operating system as normal but create another file
|
|
||||||
system on an encrypted volume.
|
|
||||||
|
|
||||||
If you need swap space, be sure to only put the swap on the encrypted
|
|
||||||
volume too. Make sure that the database does not start up
|
|
||||||
automatically on boot, and also make sure that the system does not
|
|
||||||
attempt to mount your encrypted partition automatically.
|
|
||||||
|
|
||||||
Setup:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-amd64
|
|
||||||
...
|
|
||||||
user@ksm:~$ sudo rmmod loop && sudo modprobe loop
|
|
||||||
user@ksm:~$ sudo dd if=/dev/zero of=/root/ksm.img bs=1k count=1M
|
|
||||||
...
|
|
||||||
user@ksm:~$ sudo losetup -e AES128 /dev/loop0 /root/ksm.img
|
|
||||||
Password:
|
|
||||||
user@ksm:~$ sudo mkfs.ext2 -q /dev/loop0
|
|
||||||
user@ksm:~$ sudo mkdir /ksm
|
|
||||||
user@ksm:~$ sudo mount /dev/loop0 /ksm
|
|
||||||
user@ksm:~$ sudo /etc/init.d/postgresql-8.3 stop
|
|
||||||
...
|
|
||||||
user@ksm:~$ sudo update-rc.d -f postgresql-8.3 remove
|
|
||||||
user@ksm:~$ sudo mv /var/lib/postgresql /ksm
|
|
||||||
user@ksm:~$ sudo ln -s /ksm/postgresql /var/lib/postgresql
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-start'
|
|
||||||
#!/bin/sh
|
|
||||||
set -e
|
|
||||||
set -x
|
|
||||||
losetup -e AES128 /dev/loop0 /root/ksm.img
|
|
||||||
fsck /dev/loop0
|
|
||||||
mount /dev/loop0 /ksm/
|
|
||||||
/etc/init.d/postgresql-8.3 start
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-stop'
|
|
||||||
#!/bin/sh
|
|
||||||
set -e
|
|
||||||
set -x
|
|
||||||
/etc/init.d/postgresql-8.3 stop
|
|
||||||
umount /ksm
|
|
||||||
losetup -d /dev/loop0
|
|
||||||
user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop}
|
|
||||||
|
|
||||||
Slightly adapted for MySQL:
|
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-686
|
|
||||||
...
|
|
||||||
user@ksm:~$ sudo rmmod loop && sudo modprobe loop
|
|
||||||
user@ksm:~$ sudo dd if=/dev/zero of=/root/ksm.img bs=1k count=1M
|
|
||||||
...
|
|
||||||
user@ksm:~$ sudo losetup -e AES128 /dev/loop0 /root/ksm.img
|
|
||||||
Password:
|
|
||||||
user@ksm:~$ sudo mkfs.ext2 -q /dev/loop0
|
|
||||||
user@ksm:~$ sudo mkdir /ksm
|
|
||||||
user@ksm:~$ sudo mount /dev/loop0 /ksm
|
|
||||||
user@ksm:~$ sudo /etc/init.d/mysql stop
|
|
||||||
user@ksm:~$ sudo update-rc.d -f mysql remove
|
|
||||||
user@ksm:~$ sudo mv /var/lib/mysql /ksm
|
|
||||||
user@ksm:~$ sudo ln -s /ksm/mysql /var/lib/mysql
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-start'
|
|
||||||
#!/bin/sh
|
|
||||||
set -e
|
|
||||||
set -x
|
|
||||||
losetup -e AES128 /dev/loop0 /root/ksm.img
|
|
||||||
fsck /dev/loop0
|
|
||||||
mount /dev/loop0 /ksm/
|
|
||||||
/etc/init.d/mysql start
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-stop'
|
|
||||||
#!/bin/sh
|
|
||||||
set -e
|
|
||||||
set -x
|
|
||||||
/etc/init.d/mysql stop
|
|
||||||
umount /ksm
|
|
||||||
losetup -d /dev/loop0
|
|
||||||
user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop}
|
|
||||||
|
|
||||||
Then in the future, to start the YK-KSM, you will need to login to the
|
|
||||||
machine and issue the command 'sudo ykksm-start' and enter the disk
|
|
||||||
encryption password.
|
|
||||||
|
|
||||||
Again, make sure that you don't use any unencrypted swap.
|
|
||||||
|
|
||||||
Intrusion Detection
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
To make some attacks discussed in the previous section harder, make
|
|
||||||
sure that your system has a hardware intrusion detection system and
|
|
||||||
that your software is notified when it is triggered. When the
|
|
||||||
intrusion detection is triggered, you should stop the database and
|
|
||||||
unmount the encrypted volume and send out a signal to your
|
|
||||||
administrators.
|
|
||||||
289
doc/Server_Hardening.adoc
Normal file
289
doc/Server_Hardening.adoc
Normal file
@ -0,0 +1,289 @@
|
|||||||
|
Server Hardening
|
||||||
|
----------------
|
||||||
|
|
||||||
|
While the defaults should be secure, there are some simple
|
||||||
|
administrative actions that will increase your overall security. None
|
||||||
|
of these steps are required, but we encourage you to read this
|
||||||
|
document to see if the enhancements are relevant for your environment.
|
||||||
|
|
||||||
|
Tighten PHP configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Tighten the security of the PHP installation by creating a file
|
||||||
|
/etc/php5/conf.d/harden.ini with the following content:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@host:~$ sudo sh -c 'cat > /etc/php5/conf.d/harden.ini'
|
||||||
|
display_errors = Off
|
||||||
|
log_errors = On
|
||||||
|
user@host:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Tighten Apache configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Tighten the security of the Apache installation by making sure
|
||||||
|
directory listings are disabled globally. Edit
|
||||||
|
/etc/apache2/conf.d/security and make sure the following is
|
||||||
|
uncommented:
|
||||||
|
|
||||||
|
[source, xml]
|
||||||
|
----
|
||||||
|
<Directory />
|
||||||
|
AllowOverride None
|
||||||
|
Order Deny,Allow
|
||||||
|
Deny from all
|
||||||
|
</Directory>
|
||||||
|
----
|
||||||
|
|
||||||
|
Time Synchronization
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
For logging and (on the validation server) time-stamping it is
|
||||||
|
important to have synchronized clocks. Install ntp.
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@host:~$ sudo apt-get install ntp
|
||||||
|
...
|
||||||
|
----
|
||||||
|
|
||||||
|
Firewall
|
||||||
|
~~~~~~~~
|
||||||
|
|
||||||
|
There is no reason why the KSM needs to listen to incoming requests
|
||||||
|
from the entire Internet, and restricting access to the intended
|
||||||
|
YK-VAL servers are recommended.
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
# IPv4 firewall:
|
||||||
|
iptables -F
|
||||||
|
iptables -P INPUT DROP
|
||||||
|
iptables -P FORWARD DROP
|
||||||
|
iptables -P OUTPUT ACCEPT
|
||||||
|
iptables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 -s 1.2.3.4 --dport 22 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 -s 2.3.4.5 --dport 80 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 -s 2.3.4.5 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
# IPv6 firewall:
|
||||||
|
ip6tables -F
|
||||||
|
ip6tables -P INPUT DROP
|
||||||
|
ip6tables -P FORWARD DROP
|
||||||
|
ip6tables -P OUTPUT ACCEPT
|
||||||
|
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 -s 2000:1:2::3 --dport 22 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 -s 2000:2:3::4 --dport 80 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 -s 2000:2:3::4 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the address
|
||||||
|
of the host you want to be able to login from via SSH, and replace
|
||||||
|
2.3.4.5 (for IPv4) and 2000:2:3::4 (for IPv6) with the address of the
|
||||||
|
YK-VAL that will be accessing this YK-KSM. Add more lines for each
|
||||||
|
validation server and SSH host.
|
||||||
|
|
||||||
|
For a validation server, you may want to allow HTTP(S) requests from
|
||||||
|
anyone, but not anything else.
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
# IPv4 firewall
|
||||||
|
iptables -F
|
||||||
|
iptables -P INPUT DROP
|
||||||
|
iptables -P FORWARD DROP
|
||||||
|
iptables -P OUTPUT ACCEPT
|
||||||
|
iptables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 -s 1.2.3.4 --dport 22 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
# IPv6 firewall:
|
||||||
|
ip6tables -F
|
||||||
|
ip6tables -P INPUT DROP
|
||||||
|
ip6tables -P FORWARD DROP
|
||||||
|
ip6tables -P OUTPUT ACCEPT
|
||||||
|
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 -s 2000:1:2::3 --dport 22 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Again, replace 1.2.3.4 (for IPv4) and 2000:1:2::3 (for IPv6) with the
|
||||||
|
address of the host you want to be able to login from via SSH.
|
||||||
|
|
||||||
|
If you want to allow SSH and HTTP(S) from everywhere, but nothing
|
||||||
|
else, try this:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@val:~$ sudo sh -c 'cat > /etc/network/if-pre-up.d/iptables'
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
# IPv4 firewall
|
||||||
|
iptables -F
|
||||||
|
iptables -P INPUT DROP
|
||||||
|
iptables -P FORWARD DROP
|
||||||
|
iptables -P OUTPUT ACCEPT
|
||||||
|
iptables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
iptables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 --dport 22 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
||||||
|
iptables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
# IPv6 firewall:
|
||||||
|
ip6tables -F
|
||||||
|
ip6tables -P INPUT DROP
|
||||||
|
ip6tables -P FORWARD DROP
|
||||||
|
ip6tables -P OUTPUT ACCEPT
|
||||||
|
ip6tables -A INPUT -i lo -p all -j ACCEPT
|
||||||
|
ip6tables -A INPUT -i eth0 -m state --state ESTABLISHED,RELATED -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p icmpv6 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 --dport 22 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 --dport 80 -j ACCEPT
|
||||||
|
ip6tables -A INPUT -p tcp -i eth0 --dport 443 -j ACCEPT
|
||||||
|
|
||||||
|
user@ksm:~$ chmod +x /etc/network/if-pre-up.d/iptables
|
||||||
|
user@val:~$
|
||||||
|
----
|
||||||
|
|
||||||
|
Database Encryption
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The database contains sensitive information. If someone is able to
|
||||||
|
access your machine physically, they may shut it off and steal it with
|
||||||
|
the goal of reading out the sensitive information. By encrypting the
|
||||||
|
disk, you can prevent this. Note that this does not protect against
|
||||||
|
an attacker who has physical access to your server and sufficient time
|
||||||
|
to read out the data from the already running system.
|
||||||
|
|
||||||
|
Full disk encryption will give you the highest protection, but
|
||||||
|
requires that you can enter the disk encryption password on each
|
||||||
|
power-up. This can be unpractical when your hosting environment is
|
||||||
|
remote.
|
||||||
|
|
||||||
|
Partial disk encryption allows the operating system to start up, and
|
||||||
|
enable you to login to the machine remotely to enter the disk
|
||||||
|
encryption password. This is less secure than full disk encryption,
|
||||||
|
because an attacker could physically disconnect your machine, modify
|
||||||
|
the operating system to send a copy of the password to the attacker,
|
||||||
|
but may be sufficient if you keep good track of when your machine is
|
||||||
|
not working properly.
|
||||||
|
|
||||||
|
To use partial disk encryption for the database content, we suggest
|
||||||
|
you install the operating system as normal but create another file
|
||||||
|
system on an encrypted volume.
|
||||||
|
|
||||||
|
If you need swap space, be sure to only put the swap on the encrypted
|
||||||
|
volume too. Make sure that the database does not start up
|
||||||
|
automatically on boot, and also make sure that the system does not
|
||||||
|
attempt to mount your encrypted partition automatically.
|
||||||
|
|
||||||
|
Setup:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-amd64
|
||||||
|
...
|
||||||
|
user@ksm:~$ sudo rmmod loop && sudo modprobe loop
|
||||||
|
user@ksm:~$ sudo dd if=/dev/zero of=/root/ksm.img bs=1k count=1M
|
||||||
|
...
|
||||||
|
user@ksm:~$ sudo losetup -e AES128 /dev/loop0 /root/ksm.img
|
||||||
|
Password:
|
||||||
|
user@ksm:~$ sudo mkfs.ext2 -q /dev/loop0
|
||||||
|
user@ksm:~$ sudo mkdir /ksm
|
||||||
|
user@ksm:~$ sudo mount /dev/loop0 /ksm
|
||||||
|
user@ksm:~$ sudo /etc/init.d/postgresql-8.3 stop
|
||||||
|
...
|
||||||
|
user@ksm:~$ sudo update-rc.d -f postgresql-8.3 remove
|
||||||
|
user@ksm:~$ sudo mv /var/lib/postgresql /ksm
|
||||||
|
user@ksm:~$ sudo ln -s /ksm/postgresql /var/lib/postgresql
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-start'
|
||||||
|
#!/bin/sh
|
||||||
|
set -e
|
||||||
|
set -x
|
||||||
|
losetup -e AES128 /dev/loop0 /root/ksm.img
|
||||||
|
fsck /dev/loop0
|
||||||
|
mount /dev/loop0 /ksm/
|
||||||
|
/etc/init.d/postgresql-8.3 start
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-stop'
|
||||||
|
#!/bin/sh
|
||||||
|
set -e
|
||||||
|
set -x
|
||||||
|
/etc/init.d/postgresql-8.3 stop
|
||||||
|
umount /ksm
|
||||||
|
losetup -d /dev/loop0
|
||||||
|
user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop}
|
||||||
|
----
|
||||||
|
|
||||||
|
Slightly adapted for MySQL:
|
||||||
|
|
||||||
|
[source, sh]
|
||||||
|
----
|
||||||
|
user@ksm:~$ sudo apt-get install loop-aes-utils loop-aes-modules-2.6-686
|
||||||
|
...
|
||||||
|
user@ksm:~$ sudo rmmod loop && sudo modprobe loop
|
||||||
|
user@ksm:~$ sudo dd if=/dev/zero of=/root/ksm.img bs=1k count=1M
|
||||||
|
...
|
||||||
|
user@ksm:~$ sudo losetup -e AES128 /dev/loop0 /root/ksm.img
|
||||||
|
Password:
|
||||||
|
user@ksm:~$ sudo mkfs.ext2 -q /dev/loop0
|
||||||
|
user@ksm:~$ sudo mkdir /ksm
|
||||||
|
user@ksm:~$ sudo mount /dev/loop0 /ksm
|
||||||
|
user@ksm:~$ sudo /etc/init.d/mysql stop
|
||||||
|
user@ksm:~$ sudo update-rc.d -f mysql remove
|
||||||
|
user@ksm:~$ sudo mv /var/lib/mysql /ksm
|
||||||
|
user@ksm:~$ sudo ln -s /ksm/mysql /var/lib/mysql
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-start'
|
||||||
|
#!/bin/sh
|
||||||
|
set -e
|
||||||
|
set -x
|
||||||
|
losetup -e AES128 /dev/loop0 /root/ksm.img
|
||||||
|
fsck /dev/loop0
|
||||||
|
mount /dev/loop0 /ksm/
|
||||||
|
/etc/init.d/mysql start
|
||||||
|
user@ksm:~$ sudo sh -c 'cat > /usr/local/sbin/ykksm-stop'
|
||||||
|
#!/bin/sh
|
||||||
|
set -e
|
||||||
|
set -x
|
||||||
|
/etc/init.d/mysql stop
|
||||||
|
umount /ksm
|
||||||
|
losetup -d /dev/loop0
|
||||||
|
user@ksm:~$ sudo chmod +x /usr/local/sbin/ykksm-{start,stop}
|
||||||
|
----
|
||||||
|
|
||||||
|
Then in the future, to start the YK-KSM, you will need to login to the
|
||||||
|
machine and issue the command 'sudo ykksm-start' and enter the disk
|
||||||
|
encryption password.
|
||||||
|
|
||||||
|
Again, make sure that you don't use any unencrypted swap.
|
||||||
|
|
||||||
|
Intrusion Detection
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To make some attacks discussed in the previous section harder, make
|
||||||
|
sure that your system has a hardware intrusion detection system and
|
||||||
|
that your software is notified when it is triggered. When the
|
||||||
|
intrusion detection is triggered, you should stop the database and
|
||||||
|
unmount the encrypted volume and send out a signal to your
|
||||||
|
administrators.
|
||||||
@ -19,9 +19,12 @@ freshness) and then is the truncated hash value.
|
|||||||
|
|
||||||
The script requires the Perl SHA-1 package. Install it like this:
|
The script requires the Perl SHA-1 package. Install it like this:
|
||||||
|
|
||||||
user@ksm:~$ sudo apt-get install libdigest-sha1-perl
|
[source, sh]
|
||||||
...
|
----
|
||||||
user@ksm:~$
|
user@ksm:~$ sudo apt-get install libdigest-sha1-perl
|
||||||
|
...
|
||||||
|
user@ksm:~$
|
||||||
|
----
|
||||||
|
|
||||||
The typical way to use this is either manually or to run it in a cron
|
The typical way to use this is either manually or to run it in a cron
|
||||||
job and output the hash to a file that can be downloaded by a remote
|
job and output the hash to a file that can be downloaded by a remote
|
||||||
@ -30,12 +33,15 @@ that downloads this file from all of your KSMs, and the Nagios check
|
|||||||
verify that all values are 1) fresh (Unix time is not too old) and 2)
|
verify that all values are 1) fresh (Unix time is not too old) and 2)
|
||||||
that the truncated hash value is identical on all KSMs.
|
that the truncated hash value is identical on all KSMs.
|
||||||
|
|
||||||
user@ksm:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykksm-checksum'
|
[source, sh]
|
||||||
#!/bin/sh
|
----
|
||||||
FILE=/var/www/checksum.txt
|
user@ksm:~$ sudo sh -c 'cat > /etc/cron.hourly/run-ykksm-checksum'
|
||||||
(date --utc +%s; ykksm-checksum --db-user ykksmreader --db-passwd `grep passwo rd /etc/yubico/ksm/ykksm-config.php|cut -d\ -f3|cut -d\" -f2`) > $FILE.tmp
|
#!/bin/sh
|
||||||
mv $FILE.tmp $FILE
|
FILE=/var/www/checksum.txt
|
||||||
user@ksm:~$ sudo chmod +x /etc/cron.hourly/run-ykksm-checksum
|
(date --utc +%s; ykksm-checksum --db-user ykksmreader --db-passwd `grep passwo rd /etc/yubico/ksm/ykksm-config.php|cut -d\ -f3|cut -d\" -f2`) > $FILE.tmp
|
||||||
|
mv $FILE.tmp $FILE
|
||||||
|
user@ksm:~$ sudo chmod +x /etc/cron.hourly/run-ykksm-checksum
|
||||||
|
----
|
||||||
|
|
||||||
If you notice mismatches, you may want to run ykksm-checksum with the
|
If you notice mismatches, you may want to run ykksm-checksum with the
|
||||||
'-v' parameter on the different hosts and then use 'diff -ur' or
|
'-v' parameter on the different hosts and then use 'diff -ur' or
|
||||||
Loading…
Reference in New Issue
Block a user