Changes between Version 12 and Version 13 of HOWTO


Ignore:
Timestamp:
07/25/14 14:38:10 (10 years ago)
Author:
Samuli Seppänen
Comment:

Fixed formatting up to "Caveats"

Legend:

Unmodified
Added
Removed
Modified

  • HOWTO

    v12 v13  
    712712= How to add dual-factor authentication to an OpenVPN configuration using client-side smart cards =
    713713
    714 Also see Article: The OpenVPN Smartcard HOWTO
    715 
    716     About dual-factor authentication
    717     What is PKCS#11?
    718     Finding PKCS#11 provider library.
    719     How to configure a cryptographic token
    720     How to modify an OpenVPN configuration to make use of cryptographic tokens
    721         Determine the correct object.
    722         Using OpenVPN with PKCS#11.
    723         PKCS#11 implementation considerations.
    724         OpenSC PKCS#11 provider.
    725     Difference between PKCS#11 and Microsoft Cryptographic API (CryptoAPI).
    726 
    727 About dual-factor authentication
     714Also see Article: [http://acksyn.org/docs/smart-cards-openvpn.html The OpenVPN Smartcard HOWTO]
     715
     716== About dual-factor authentication ==
    728717
    729718Dual-factor authentication is a method of authentication that combines two elements: something you have and something you know.
    … …  
    738727
    739728If you store the secret private key in a file, the key is usually encrypted by a password. The problem with this approach is that the encrypted key is exposed to decryption attacks or spyware/malware running on the client machine. Unlike when using a cryptographic device, the file cannot erase itself automatically after several failed decryption attempts.
    740 What is PKCS#11?
    741 
    742 This standard specifies an API, called Cryptoki, to devices which hold cryptographic information and perform cryptographic functions. Cryptoki, pronounced "crypto-key" and short for cryptographic token interface, follows a simple object-based approach, addressing the goals of technology independence (any kind of device) and resource sharing (multiple applications accessing multiple devices), presenting to applications a common, logical view of the device called a cryptographic token.
    743 
    744 Source: RSA Security Inc. http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11.
     729
     730== What is PKCS#11? ==
     731
     732''This standard specifies an API, called Cryptoki, to devices which hold cryptographic information and perform cryptographic functions. Cryptoki, pronounced "crypto-key" and short for cryptographic token interface, follows a simple object-based approach, addressing the goals of technology independence (any kind of device) and resource sharing (multiple applications accessing multiple devices), presenting to applications a common, logical view of the device called a cryptographic token.''
     733
     734Source: RSA Security Inc. (the original, now broken link: http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11).
    745735
    746736To summarize, PKCS#11 is a standard that can be used by application software to access cryptographic tokens such as smart cards and other devices. Most device vendors provide a library that implements the PKCS#11 provider interface -- this library can be used by applications in order to access these devices. PKCS#11 is a cross-platform, vendor-independent free standard.
    747 Finding PKCS#11 provider library
     737
     738== Finding PKCS#11 provider library ==
    748739
    749740The first thing you need to do is to find the provider library, it should be installed with the device drivers. Each vendor has its own library. For example, the OpenSC PKCS#11 provider is located at /usr/lib/pkcs11/opensc-pkcs11.so on Unix or at opensc-pkcs11.dll on Windows.
    750 How to configure cryptographic token
     741
     742== How to configure cryptographic token ==
    751743
    752744You should follow an enrollment procedure:
    753745
    754    Initialize the PKCS#11 token.
    755    Generate RSA key pair on the PKCS#11 token.
    756    Create a certificate request based on the key pair, you can use OpenSC and OpenSSL in order to do that.
    757    Submit the certificate request to a certificate authority, and receive a certificate.
    758    Load the certificate onto the token, while noting that the id and label attributes of the certificate must match those of the private key.
     746 * Initialize the PKCS#11 token.
     747 * Generate RSA key pair on the PKCS#11 token.
     748 * Create a certificate request based on the key pair, you can use OpenSC and OpenSSL in order to do that.
     749 * Submit the certificate request to a certificate authority, and receive a certificate.
     750 * Load the certificate onto the token, while noting that the id and label attributes of the certificate must match those of the private key.
    759751
    760752A configured token is a token that has a private key object and a certificate object, where both share the same id and label attributes.
    … …  
    763755
    764756Initialize a token using the following command:
    765 
    766     $ ./pkitool --pkcs11-slots /usr/lib/pkcs11/
    767     $ ./pkitool --pkcs11-init /usr/lib/pkcs11/ 
    768 
     757{{{
     758$ ./pkitool --pkcs11-slots /usr/lib/pkcs11/
     759$ ./pkitool --pkcs11-init /usr/lib/pkcs11/ 
     760}}}
    769761Enroll a certificate using the following command:
    770 
    771     $ ./pkitool --pkcs11 /usr/lib/pkcs11/   client1
    772 
    773 How to modify an OpenVPN configuration to make use of cryptographic tokens
     762{{{
     763$ ./pkitool --pkcs11 /usr/lib/pkcs11/   client1
     764}}}
     765== How to modify an OpenVPN configuration to make use of cryptographic tokens ==
    774766
    775767You should have OpenVPN 2.1 or above in order to use the PKCS#11 features.
    776 Determine the correct object
     768=== Determine the correct object ===
    777769
    778770Each PKCS#11 provider can support multiple devices. In order to view the available object list you can use the following command:
    779771
    780     $ openvpn --show-pkcs11-ids /usr/lib/pkcs11/
    781 
    782     The following objects are available for use.
    783     Each object shown below may be used as parameter to
    784     --pkcs11-id option please remember to use single quote mark.
    785 
    786     Certificate
    787            DN:             /CN=User1
    788            Serial:         490B82C4000000000075
    789            Serialized id:  aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600
    790 
    791 Each certificate/private key pair have unique "Serialized id" string. The serialized id string of the requested certificate should be specified to the pkcs11-id option using single quote marks.
    792 
    793     pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
    794 
    795 Using OpenVPN with PKCS#11
    796 A typical set of OpenVPN options for PKCS#11
    797 
    798     pkcs11-providers /usr/lib/pkcs11/
    799     pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
    800 
     772{{{
     773$ openvpn --show-pkcs11-ids /usr/lib/pkcs11/
     774
     775The following objects are available for use.
     776Each object shown below may be used as parameter to
     777--pkcs11-id option please remember to use single quote mark.
     778
     779Certificate
     780       DN:             /CN=User1
     781       Serial:         490B82C4000000000075
     782       Serialized id:  aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600
     783}}}
     784Each certificate/private key pair have unique "Serialized id" string. The serialized id string of the requested certificate should be specified to the '''pkcs11-id''' option using single quote marks.
     785{{{
     786pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
     787}}}
     788
     789=== Using OpenVPN with PKCS#11 ===
     790
     791A typical set of OpenVPN options for PKCS#11:
     792{{{
     793pkcs11-providers /usr/lib/pkcs11/
     794pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
     795}}}
    801796This will select the object which matches the pkcs11-id string.
    802 Advanced OpenVPN options for PKCS#11
    803 
    804     pkcs11-providers /usr/lib/pkcs11/provider1.so /usr/lib/pkcs11/provider2.so
    805     pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
    806     pkcs11-pin-cache 300
    807     daemon
    808     auth-retry nointeract
    809     management-hold
    810     management-signal
    811     management 127.0.0.1 8888
    812     management-query-passwords
    813 
    814 This will load two providers into OpenVPN, use the certificate specified on pkcs11-id option, and use the management interface in order to query passwords. The daemon will resume into hold state on the event when token cannot be accessed. The token will be used for 300 seconds after which the password will be re-queried, session will disconnect if management session disconnects.
    815 PKCS#11 implementation considerations
     797
     798'''Advanced OpenVPN options for PKCS#11'''
     799{{{
     800pkcs11-providers /usr/lib/pkcs11/provider1.so /usr/lib/pkcs11/provider2.so
     801pkcs11-id 'aaaa/bbb/41545F5349474E415455524581D2A1A1B23C4AA4CB17FAF7A4600'
     802pkcs11-pin-cache 300
     803daemon
     804auth-retry nointeract
     805management-hold
     806management-signal
     807management 127.0.0.1 8888
     808management-query-passwords
     809}}}
     810This will load two providers into OpenVPN, use the certificate specified on '''pkcs11-id''' option, and use the management interface in order to query passwords. The daemon will resume into hold state on the event when token cannot be accessed. The token will be used for 300 seconds after which the password will be re-queried, session will disconnect if management session disconnects.
     811=== PKCS#11 implementation considerations ===
    816812
    817813Many PKCS#11 providers make use of threads, in order to avoid problems caused by implementation of LinuxThreads (setuid, chroot), it is highly recommend to upgrade to Native POSIX Thread Library (NPTL) enabled glibc if you intend to use PKCS#11.
    818 OpenSC PKCS#11 provider
     814=== OpenSC PKCS#11 provider ===
    819815
    820816OpenSC PKCS#11 provider is located at /usr/lib/pkcs11/opensc-pkcs11.so on Unix or at opensc-pkcs11.dll on Windows.
    821 Difference between PKCS#11 and Microsoft Cryptographic API (CryptoAPI)
     817
     818== Difference between PKCS#11 and Microsoft Cryptographic API (CryptoAPI) ==
    822819
    823820PKCS#11 is a free, cross-platform vendor independent standard. CryptoAPI is a Microsoft specific API. Most smart card vendors provide support for both interfaces. In the Windows environment, the user should select which interface to use.
    824821
    825 The current implementation of OpenVPN that uses the MS CryptoAPI (cryptoapicert option) works well as long as you don't run OpenVPN as a service. If you wish to run OpenVPN in an administrative environment using a service, the implementation will not work with most smart cards because of the following reasons:
    826 
    827    Most smart card providers do not load certificates into the local machine store, so the implementation will be unable to access the user certificate.
    828    If the OpenVPN client is running as a service without direct interaction with the end-user, the service cannot query the user to provide a password for the smart card, causing the password-verification process on the smart card to fail.
     822The current implementation of OpenVPN that uses the MS CryptoAPI ('''cryptoapicert''' option) works well as long as you don't run OpenVPN as a service. If you wish to run OpenVPN in an administrative environment using a service, the implementation will not work with most smart cards because of the following reasons:
     823
     824 * Most smart card providers do not load certificates into the local machine store, so the implementation will be unable to access the user certificate.
     825 * If the OpenVPN client is running as a service without direct interaction with the end-user, the service cannot query the user to provide a password for the smart card, causing the password-verification process on the smart card to fail.
    829826
    830827Using the PKCS#11 interface, you can use smart cards with OpenVPN in any implementation, since PKCS#11 does not access Microsoft stores and does not necessarily require direct interaction with the end-user.
    831 Routing all client traffic (including web-traffic) through the VPN
    832 Overview
     828= Routing all client traffic (including web-traffic) through the VPN =
     829
     830== Overview ==
    833831
    834832By default, when an OpenVPN client is active, only network traffic to and from the OpenVPN server site will pass over the VPN. General web browsing, for example, will be accomplished with direct connections that bypass the VPN.
    835833
    836834In certain cases this behavior might not be desirable -- you might want a VPN client to tunnel all network traffic through the VPN, including general internet web browsing. While this type of VPN configuration will exact a performance penalty on the client, it gives the VPN administrator more control over security policies when a client is simultaneously connected to both the public internet and the VPN at the same time.
    837 Implementation
     835== Implementation ==
    838836
    839837Add the following directive to the server configuration file:
    840 
    841     push "redirect-gateway def1"
    842 
     838{{{
     839push "redirect-gateway def1"
     840}}}
    843841If your VPN setup is over a wireless network, where all clients and the server are on the same wireless subnet, add the local flag:
    844 
    845     push "redirect-gateway local def1"
    846 
    847 Pushing the redirect-gateway option to clients will cause all IP network traffic originating on client machines to pass through the OpenVPN server. The server will need to be configured to deal with this traffic somehow, such as by NATing it to the internet, or routing it through the server site's HTTP proxy.
     842{{{
     843push "redirect-gateway local def1"
     844}}}
     845Pushing the '''redirect-gateway''' option to clients will cause all IP network traffic originating on client machines to pass through the OpenVPN server. The server will need to be configured to deal with this traffic somehow, such as by NATing it to the internet, or routing it through the server site's HTTP proxy.
    848846
    849847On Linux, you could use a command such as this to NAT the VPN client traffic to the internet:
    850 
    851     iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
    852 
    853 This command assumes that the VPN subnet is 10.8.0.0/24 (taken from the server directive in the OpenVPN server configuration) and that the local ethernet interface is eth0.
    854 
    855 When redirect-gateway is used, OpenVPN clients will route DNS queries through the VPN, and the VPN server will need handle them. This can be accomplished by pushing a DNS server address to connecting clients which will replace their normal DNS server settings during the time that the VPN is active. For example:
    856 
    857     push "dhcp-option DNS 10.8.0.1"
    858 
     848{{{
     849iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
     850}}}
     851This command assumes that the VPN subnet is '''10.8.0.0/24''' (taken from the '''server''' directive in the OpenVPN server configuration) and that the local ethernet interface is '''eth0'''.
     852
     853When '''redirect-gateway''' is used, OpenVPN clients will route DNS queries through the VPN, and the VPN server will need handle them. This can be accomplished by pushing a DNS server address to connecting clients which will replace their normal DNS server settings during the time that the VPN is active. For example:
     854{{{
     855push "dhcp-option DNS 10.8.0.1"
     856}}}
    859857will configure Windows clients (or non-Windows clients with some extra server-side scripting) to use 10.8.0.1 as their DNS server. Any address which is reachable from clients may be used as the DNS server address.
    860 Caveats
     858
     859== Caveats ==
    861860
    862861Redirecting all network traffic through the VPN is not entirely a problem-free proposition. Here are some typical gotchas to be aware of: