Changes in 89f3d49: Add manual links, remove dead keystone(4) reference, configure `tunnel` IPs on gre(4) device, provide hostname.gre0 example

howto/IPsecWithPublicKeys/OpenBSDExample.md

@@ -10,19 +10,19 @@ Here be dragons. This section should cover the basics:

 OpenBSD generates keys suitables for IPSec usage during the installation. The public key can be found in `/etc/isakmpd/local.pub`

 ## Generating your own keys

-If you don't want to use a pre-generated key, refer to the isakmpd(8) manpage under the section `X.509 AUTHENTICATION`.

+If you don't want to use a pre-generated key, refer to [isakmpd(8)](http://man.openbsd.org/isakmpd.8#X.509_AUTHENTICATION).

 ## Distributing keys

 Send your public key to your peer, preferrably digitally signed. A signature can be created with `gpg -sb -a local.pub` and checked with `gpg --verify local.pub.asc`. Since the key is not private, it can be transmitted in the open and on a public forum, such as a Pastebin service.

-Once your peer sent you their public key, it under `/etc/isakmpd/pubkeys/ipv4` or `/etc/isakmpd/ipv6`, depending on the address family the peer is using. The key file should be named after the peers address. For example, if your peer is `1.3.3.7`, you place their public key under `/etc/isakmpd/pubkeys/ipv4/1.3.3.7`.

+Once your peer sent you their public key, it under `/etc/isakmpd/pubkeys/fqdn`, `/etc/isakmpd/pubkeys/ipv4` or `/etc/isakmpd/ipv6`, depending on the ID type the peer is using. The key file should be named after the peers ID. For example, if your peer is `1.3.3.7`, you place their public key under `/etc/isakmpd/pubkeys/ipv4/1.3.3.7`.

 If your peers public key is not in PEM format, you can use [pubkey-converter](https://dn42.us/git/user/ryan/pubkey-converter.git/plain/pubkey-converter.pl) to convert between key formats.

 # IPSec Setup

-Change the value of the `isakmpd_flags` variable in `/etc/rc.conf.local` to `"-K"`, or add the `"-K"` flag if you already have flags in there. This disables keystone(4) authentication, which is okay because we are using `ipsecctl`.

+Change the value of the `isakmpd_flags` variable in [`/etc/rc.conf.local`](http://man.openbsd.org/rc.conf.local.8) to `"-K"`, or add the `"-K"` flag if you already have flags in there.

-Next, add the right flow parameters to `/etc/ipsec.conf`. We are using the following parameters in this example:

+Next, add the right flow parameters to [`/etc/ipsec.conf`](http://man.openbsd.org/ipsec.conf.5). We are using the following parameters in this example:

 * Encryption: AES-128

 * Authentication hash: HMAC-SHA1

@@ -52,12 +52,14 @@ Load the configuration file into isakmpd: `ipsecctl -f /etc/ipsec.conf`. Once th

 esp transport from 3.4.5.6 to 1.3.3.7 spi 0xf00df00d auth hmac-sha1 enc aes

 # GRE Setup

-Next, we will set up the GRE device. The GRE device encapsulates IPv4 and IPv6 traffic, which allows you to speak both address families over one tunnel and if you only have native connectivity for one address family. The addresses configured onto the GRE device should come from a private address range that is not used anywhere in DN42, or a registered transfer net. For IPv6, you should use either ULAs or Link-Local addresses. In this example, we assume you are using 10.20.30.0/31 as the IPv4 transfer "net" (it has only two addresses, so calling it a network is a bit of an overstatement) and Link-Local addresses for IPv6.

+Next, we will set up the GRE device. The [gre(4)](http://man.openbsd.org/gre.4) device encapsulates IPv4 and IPv6 traffic, which allows you to speak both address families over one tunnel if you only have native connectivity for one address family. The addresses configured onto the GRE device should come from a private address range that is not used anywhere in DN42, or a registered transfer net. For IPv6, you should use either ULAs or Link-Local addresses. In this example, we assume you are using 10.20.30.0/31 as the IPv4 transfer "net" (it has only two addresses, so calling it a network is a bit of an overstatement) and Link-Local addresses for IPv6.

- # ifconfig gre0 create

+ # ifconfig gre0 tunnel 3.4.5.6 1.3.3.7

 # ifconfig gre0 inet 10.20.30.0 10.20.30.1 # reverse these on your peer's side

- # # on older releases of OpenBSD, a Link-Local address is generated automatically

 # ifconfig gre0 inet6 eui64

- # ifconfig gre0 up

-These settings should also be added to `/etc/hostname.gre0`.

\ No newline at end of file

+These settings should also be added to [`/etc/hostname.gre0`](http://man.openbsd.org/hostname.if.5), .i.e.

+

+ tunnel 3.4.5.6 1.3.3.7

+ inet 10.20.30.0 10.20.30.1

+ inet6 eui64

\ No newline at end of file

...	...	@@ -10,19 +10,19 @@ Here be dragons. This section should cover the basics:
10	10	OpenBSD generates keys suitables for IPSec usage during the installation. The public key can be found in `/etc/isakmpd/local.pub`
11	11
12	12	## Generating your own keys
13		-If you don't want to use a pre-generated key, refer to the isakmpd(8) manpage under the section `X.509 AUTHENTICATION`.
	13	+If you don't want to use a pre-generated key, refer to [isakmpd(8)](http://man.openbsd.org/isakmpd.8#X.509_AUTHENTICATION).
14	14
15	15	## Distributing keys
16	16	Send your public key to your peer, preferrably digitally signed. A signature can be created with `gpg -sb -a local.pub` and checked with `gpg --verify local.pub.asc`. Since the key is not private, it can be transmitted in the open and on a public forum, such as a Pastebin service.
17	17
18		-Once your peer sent you their public key, it under `/etc/isakmpd/pubkeys/ipv4` or `/etc/isakmpd/ipv6`, depending on the address family the peer is using. The key file should be named after the peers address. For example, if your peer is `1.3.3.7`, you place their public key under `/etc/isakmpd/pubkeys/ipv4/1.3.3.7`.
	18	+Once your peer sent you their public key, it under `/etc/isakmpd/pubkeys/fqdn`, `/etc/isakmpd/pubkeys/ipv4` or `/etc/isakmpd/ipv6`, depending on the ID type the peer is using. The key file should be named after the peers ID. For example, if your peer is `1.3.3.7`, you place their public key under `/etc/isakmpd/pubkeys/ipv4/1.3.3.7`.
19	19
20	20	If your peers public key is not in PEM format, you can use [pubkey-converter](https://dn42.us/git/user/ryan/pubkey-converter.git/plain/pubkey-converter.pl) to convert between key formats.
21	21
22	22	# IPSec Setup
23		-Change the value of the `isakmpd_flags` variable in `/etc/rc.conf.local` to `"-K"`, or add the `"-K"` flag if you already have flags in there. This disables keystone(4) authentication, which is okay because we are using `ipsecctl`.
	23	+Change the value of the `isakmpd_flags` variable in [`/etc/rc.conf.local`](http://man.openbsd.org/rc.conf.local.8) to `"-K"`, or add the `"-K"` flag if you already have flags in there.
24	24
25		-Next, add the right flow parameters to `/etc/ipsec.conf`. We are using the following parameters in this example:
	25	+Next, add the right flow parameters to [`/etc/ipsec.conf`](http://man.openbsd.org/ipsec.conf.5). We are using the following parameters in this example:
26	26
27	27	* Encryption: AES-128
28	28	* Authentication hash: HMAC-SHA1
...	...	@@ -52,12 +52,14 @@ Load the configuration file into isakmpd: `ipsecctl -f /etc/ipsec.conf`. Once th
52	52	esp transport from 3.4.5.6 to 1.3.3.7 spi 0xf00df00d auth hmac-sha1 enc aes
53	53
54	54	# GRE Setup
55		-Next, we will set up the GRE device. The GRE device encapsulates IPv4 and IPv6 traffic, which allows you to speak both address families over one tunnel and if you only have native connectivity for one address family. The addresses configured onto the GRE device should come from a private address range that is not used anywhere in DN42, or a registered transfer net. For IPv6, you should use either ULAs or Link-Local addresses. In this example, we assume you are using 10.20.30.0/31 as the IPv4 transfer "net" (it has only two addresses, so calling it a network is a bit of an overstatement) and Link-Local addresses for IPv6.
	55	+Next, we will set up the GRE device. The [gre(4)](http://man.openbsd.org/gre.4) device encapsulates IPv4 and IPv6 traffic, which allows you to speak both address families over one tunnel if you only have native connectivity for one address family. The addresses configured onto the GRE device should come from a private address range that is not used anywhere in DN42, or a registered transfer net. For IPv6, you should use either ULAs or Link-Local addresses. In this example, we assume you are using 10.20.30.0/31 as the IPv4 transfer "net" (it has only two addresses, so calling it a network is a bit of an overstatement) and Link-Local addresses for IPv6.
56	56
57		- # ifconfig gre0 create
	57	+ # ifconfig gre0 tunnel 3.4.5.6 1.3.3.7
58	58	# ifconfig gre0 inet 10.20.30.0 10.20.30.1 # reverse these on your peer's side
59		- # # on older releases of OpenBSD, a Link-Local address is generated automatically
60	59	# ifconfig gre0 inet6 eui64
61		- # ifconfig gre0 up
62	60
63		-These settings should also be added to `/etc/hostname.gre0`.
...	...	\ No newline at end of file
	0	+These settings should also be added to [`/etc/hostname.gre0`](http://man.openbsd.org/hostname.if.5), .i.e.
	1	+
	2	+ tunnel 3.4.5.6 1.3.3.7
	3	+ inet 10.20.30.0 10.20.30.1
	4	+ inet6 eui64
...	...	\ No newline at end of file