pylurk 0.0.2

Python LURK

pyLURK : python implementation of LURK

The LURK Protocol as well as the LURK Extensions that enables remote interaction with cryptographic material.

pylurk implements the LURK Extension 'tls12' which enables interactions between a LURK Client and a LURK Server in a TLS1.2

The LURK specifications is available in draft-mglt-lurk-lurk and the TLS 1.2 extension is available in draft-mglt-lurk-tls12.

The current code is available on github.

Installation

Quick Install

pylurk can be installed using pip3

pip3 install pylurk

Manual installation

Prerequisites

pylurk has the following dependencies :

• python3.6 or greater
• construct2.8(doc)
• cryptodome(doc
• tinyec
• pyca/cryptography (optional) only used to create certificate

installing python3.6

check you Python version

python3 --version

If the version is lower than 3.6 install the latest Python version. On Ubuntu this could be achieved as :

sudo apt-get install python3

installing construct

installing contruct 2.8. There is a version 2.9 that seems to have significant changes from 2.8. Further testing is needed before moving to the latest version.

wget
https://files.pythonhosted.org/packages/e5/c6/3e3aeef38bb0c27364af3d21493d9690c7c3925f298559bca3c48b7c9419/construct-2.8.22.tar.gz
tar -xvzf construct-2.8.12.tar.gz
cd construct-2.8.22
sudo python3 setup.py install

or

pip3 install construct==2.8.22 

installing cryptodrome

sudo apt-get install build-essential libgmp3-dev python3-dev
pip3 install pycryptodomex
python3 -m Cryptodome.SelfTest

installing tinyec

pip3 install tinyec

installing pyca/cryptography

pip3 install cryptography

installing pylurk

Installing pylurk:

git clone ssh://[e-mail]/lurk/pylurk.git pylurk
cd pylurk
python3 test_lurk.py 
python3 test_tls12.py 

Installation Testing

The lurk and tls12 tests modules have been written to tests and illustrate the usage of the LURK protocol as well as its TLS 1.2 extension.

python3 -m pylurk.tests.lurk

python3 -m pylurk.tests.tls12

Example

Demo scripts: LURK exchange for TLS 1.2 / RSA Master

Start the LURK Server by running the following command

python3 -m pylurk.sample.tls12_rsa_master_server_demo
Server started with configuration below:
    - role: server
    - connectivity: {'type': 'udp', 'ip_address': '127.0.0.1', 'port': 6789}
    - extensions:
        - lurk, v1, ping
        - lurk, v1, capabilities
        - tls12, v1, ping
        - tls12, v1, capabilities
        - tls12, v1, rsa_master
             > designation: tls12
             > version: v1
             > type: rsa_master
             > key_id_type: ['sha256_32']
             > freshness_funct: ['null', 'sha256']
             > random_time_window: 5
             > check_server_random: False
             > check_client_random: False
             > cert: ['/home/emigdan/gitlab/pylurk.git/pylurk/core/../data/cert-rsa-enc.der']
             > key: ['/home/emigdan/gitlab/pylurk.git/pylurk/core/../data/key-rsa-enc-pkcs8.der']
        - tls12, v1, rsa_extended_master
        - tls12, v1, ecdhe


UDP Server listening...

Run the LURK Client detailing the operations on an TLS Edge Server

python3 -m pylurk.sample.tls12_rsa_master_client_demo

    This demo exposes the interactions between a TLS Server terminating a TLS session and a Key Server. The demo illustrates the case of RSA authentication


== 1. Instantiating LurkUDPClient ==
------------------------------------


    LurkUDPClient started with capabilities:
        -ping
        -capabilities
        -rsa_master
        -rsa_extended_master
        -ecdhe



== 2. Listening for ClientHello from TLS Client... ==
-----------------------------------------------------


    ...ClientHello
    ...Container: 
    ...    client_version = Container: 
    ...        major = TLS12M (total 6)
    ...        minor = TLS12m (total 6)
    ...    random = Container: 
    ...        gmt_unix_time = [\x8e\xe9\x03 (total 4)
    ...        random = ;\xe7\xfb,\x07\xba\x86\x068\xb4\xfc3'\x1d\x
    ...            f7\xd2T\xfcB\x87\xf8\xc8\xbe\x8b\xddV\xec\xb8 (t
    ...            otal 28)
    ...    session_id = \x99B\x80\xe1\xeb\xbf\xed\x886lm\x8d\xe8\x8
    ...        2\xcd(B0\xe6\xd18\xc8c\x9f\x8a/\xbf\xc0\x1b\xd8t\x08
    ...         (total 32)
    ...    cipher_suites = ListContainer: 
    ...        TLS_RSA_WITH_AES_128_GCM_SHA256
    ...        TLS_RSA_WITH_AES_256_GCM_SHA384
    ...    compression_methods = ListContainer: 
    ...        null
    ...    extensions = ListContainer: 

    ...---------->




== 3. Responding with a ServerHello to the TLS Client ==
--------------------------------------------------------


    a) Selecting cipher suite:
        > TLS_RSA_WITH_AES_128_GCM_SHA256

    b) Extracting client_random:
        > Random
        > Container: 
        >     gmt_unix_time = [\x8e\xe9\x03 (total 4)
        >     random = ;\xe7\xfb,\x07\xba\x86\x068\xb4\xfc3'\x1d\xf7\x
        >         d2T\xfcB\x87\xf8\xc8\xbe\x8b\xddV\xec\xb8 (total 28)


    c) Generating a random (S):
        > Random
        > Container: 
        >     gmt_unix_time = [\x8e\xe9\x03 (total 4)
        >     random = 2\x0f^\xe3VFp\x80\n^\xcb\xa2\xc0\x8b\x8e,\x01\x
        >         13\xafB\x17\x8a\xb8\x8d\xa4\xe3\x82\xb8 (total 28)

    d) Obfuscating S (server_random):
        > Random
        > Container: 
        >     gmt_unix_time = [\x8e\xe9\x03 (total 4)
        >     random = \x1b\xa2\x193\xd8\xb6\x96{\xbd\x18V\xb2~l1#}\xa
        >         63C\x98\xb9b\x02\xf8o\xf9\x9b (total 28)


    e) Sending the ServerHello
    ...ServerHello
    ...Container: 
    ...    server_version = Container: 
    ...        major = TLS12M (total 6)
    ...        minor = TLS12m (total 6)
    ...    random = Container: 
    ...        gmt_unix_time = [\x8e\xe9\x03 (total 4)
    ...        random = \x1b\xa2\x193\xd8\xb6\x96{\xbd\x18V\xb2~l1#
    ...            }\xa63C\x98\xb9b\x02\xf8o\xf9\x9b (total 28)
    ...    session_id = +q\x91\xa0\xcc\xe3W\xf7Q)\xdd5\x94\xd6\xf0\
    ...        xd7D\xeb\x8aD\x91,?\xdaA\x05ej\x9e\xdd\xb6s (total 3
    ...        2)
    ...    cipher_suite = TLS_RSA_WITH_AES_128_GCM_SHA256 (total 31
    ...        )
    ...    compression_method = null (total 4)
    ...    extensions = ListContainer: 

    ...Certificate
    ...ListContainer: 
    ...    b'0\x82\x03f0\x82\x02N\xa0\x03\x02\x01\x02\x02\x14nU\xc1
    ...        o\xcb\x8d \x99\x14\xf2\x08\xcb\xb6\xc2y\xe4\x86_PH0\
    ...        r\x06\t*\x86H\x86\xf7\r\x01\x01\x0b\x05\x000\\1\x0b0
    ...        \t\x06\x03U\x04\x06\x13\x02CA1\x0b0\t\x06\x03U\x04\x
    ...        08\x0c\x02QC1\x110\x0f\x06\x03U\x04\x07\x0c\x08Montr
    ...        eal1\x130\x11\x06\x03U\x04\n\x0c\nMy Company1\x180\x
    ...        16\x06\x03U\x04\x03\x0c\x0fwww.example.com0 \x17\r18
    ...        0508223907Z\x18\x0f21180414223907Z0\\1\x0b0\t\x06\x0
    ...        3U\x04\x06\x13\x02CA1\x0b0\t\x06\x03U\x04\x08\x0c\x0
    ...        2QC1\x110\x0f\x06\x03U\x04\x07\x0c\x08Montreal1\x130
    ...        \x11\x06\x03U\x04\n\x0c\nMy Company1\x180\x16\x06\x0
    ...        3U\x04\x03\x0c\x0fwww.example.com0\x82\x01"0\r\x06\t
    ...        *\x86H\x86\xf7\r\x01\x01\x01\x05\x00\x03\x82\x01\x0f
    ...        \x000\x82\x01\n\x02\x82\x01\x01\x00\xc0\x02\xe0\xd5\
    ...        xe7\x17\xfe\xcf\x04>\xba\x16\xeb\xb289-\xef$\xbc\xf4
    ...        TL\xcdQ(\xc6\x07\x8cwU\xec\x82%\xae\x1d\x01Y\x86\xa7
    ...        \x9b\t\x18\x13\xb3\x15\xcaTw\n\x12\xc4\xb3L3\xbd\xc1
    ...        \xe2\xaa@\x197\xd6l\x07\x8f\xc4\x82\xa7\xb1\xa5\xc07
    ...        \xeb\x1b#\x8b4\x16]\xdf\x87\x94\xdd\xa8\xa7\xb9YO\xd
    ...        a\xc9\x02\x19\x06\x7f\xb4\x81\xce"+b\xec|\xa9\x95\xf
    ...        20#\x97A\x19R<\xfd>\xf3\xad\xd6\xe6\xa4C\x13\r\xb9\x
    ...        c8\x19\x17L\x94\xc7\xd8\xb8\xdd \xf6\xe6\xa3\xdfv\xd
    ...        f\x0bH\xf5XF\xa0\x83\xc7P\x00\xed\xd2L\x83\xc4c\x93\
    ...        x15\x83\x0c2\xec3,\x97U\x8c\x03\xef\xf1\xc0\xa8\xb7\
    ...        x94\xfeVg\\.\xd1X\xc6\xb4\xc1\x97\x94\n\xa8F\xcd\xeb
    ...        @.\xf3\x81\t\x8d\xb6@t\x9e,l\xbf\x01c\xd6\xcf\xef\x0
    ...        1\x91\x9e\xec\xca\xc7\x96\xde\x03\xb6\xe8\xe1Z816!$K
    ...        \x9f\xfa\xe2<\x964\xd3\xce\xf5\x0f*Z\x94\x01\xb39\xb
    ...        5ea\nA\xab>%\x93\xa2 \x17\x02\x03\x01\x00\x01\xa3\x1
    ...        e0\x1c0\x1a\x06\x03U\x1d\x11\x04\x130\x11\x82\x0fwww
    ...        .example.com0\r\x06\t*\x86H\x86\xf7\r\x01\x01\x0b\x0
    ...        5\x00\x03\x82\x01\x01\x00AX\xda\x85\xfb\x06\xb0\x1a\
    ...        xf7\x17\x01\x0b\xe8k\xf1i8G\xfb\xea\xe8n}kc\x91\xb5W
    ...        -\xc9\xbc"\x06@gx\xd6\xbe@Gg>\x90+\x03\x83\x9es&q\x8
    ...        f\x98\xf0m`[\xb9\x1e\xe0\r\x8c9\x12\rB^\xe3\xf0\x08z
    ...        \x8a\xf3cl\x96v\x17\xb4\x1d\x98\xd12A7$|Y\x89\x96j?\
    ...        x16\x85\xf8\xfc\xbf\xf4B\x89\x81\x01\xdb\xa3S\xe4\xc
    ...        c7\xeb\x1b!\xdc`\x7f\x13U\x8e\xdeX\xec&\x1b\x00\xb7\
    ...        xad\xccK\x01\x131\xc8Y,\xde\xef\xe6G\x98)\x1c\xe8\x1
    ...        f\xf1\xfe\xc5\xf38tT#?\x9bl\x1bzwd\xdf\x87\x12\n=sBQ
    ...        \x1f]|\x94\x9c!\xb1\x8c\xbd#\x01\xe4\xda\xb9\x17\xe6
    ...        \xa8%\x8f9|\x07\xcb\xbc5\xc9KE\x8c\xf8\x1c\xc6VT\x90
    ...        0\xfdz\xaa\xef\xe8|\xd3z\xbd%-\xf7\xe8\xa3\xd3\xe6\x
    ...        90\xf0\xc1\xc2\xf6`\xaf\x8f\xbf\x93y}-\xc45B3\x0el\x
    ...        84 \x98S.\xf2xh\x1d\x8fU\x95y\xe9\xa4\xc8\xde\x82\xe
    ...        0B '

    ...ServerHelloDone
    ...b''

    ...<----------




== 4. Listening for Client Key Exchange from the TLS Client ==
--------------------------------------------------------------


    ...ClientKeyExchange
    ...b'W\xb3\x0b\xb7"\x8a\xb2\x13\xcc\x97&d*\xba3\x80K\x9f\xc0\x0
    ...    0<_\t\xf4O\xe9\x1ft\xb0\x95\x9f\xd3`\xe6\xa8\x8dY\x15\xe
    ...    7\x8b\x1e\x188\xffhO\x88\x82\x94w/g\x1d\x0c\x89\xb7\xc4g
    ...    \x87\xf9qv\xa9+u\x1c?\x15\xb1n\x1c\xba\x1f\xca\xe5:\xee\
    ...    xb2\x11S\x87\xf3\xa8;\xd3\x06\x08m\xd6\xa1\xd0\xba\xb2\x
    ...    d8\x13L\xb0\xa8\x9e4\xf9h}\x01\x10\xe7\x123%H\xa4\x11\xd
    ...    7\x92\xe2M\xb8\x84C\xcc`\xb9\x89\xb5\xbc\xff\xb0\xf9\x00
    ...    )\xca\xe2?-B*\xbf\xa9\xffh\xc1(G\x1d\xa6\x01\x83\x95\x9b
    ...    \xb5\xdd\x84\x7f\xd9\xc1-\xc9\xe0\xa8\x90p%\xe3\xba\xb5W
    ...    \xc7x\x10\xd2\'D\xdbY@F\x0e\x19*\xbb,ih\xe1\xe7\x84\xb2_
    ...    \x12\xe3".\xa7$\x0b\xd1p\xaa\x00[A\x12n>N\x19u\xdff3\x1c
    ...    ?O) z%\x8d\x8cf\xe9\xbb\xe3\x0b\x81F\xdf\x04U\x13\x87y\x
    ...    e1\xe6\xaci\xa7\xcb\xdf|\'=\x13\xe5\xec.\x7f9\xdf\x90\xb
    ...    e*6lW\xe1'



== 5. Generation of the master secret by the Key Server ==
----------------------------------------------------------


    The master secret is requested to the Key Server (LURK)

    The master secret is generated by the Key Server

          ...Lurk Header
          ...Container: 
          ...    designation = tls12 (total 5)
          ...    version = v1 (total 2)
          ...    type = rsa_master (total 10)
          ...    status = request (total 7)
          ...    id = a(\x89\xb0\x97\x05\x0c\xcd (total 8)
          ...    length = 342
          ...TLS12RSAMasterRequestPayload
          ...Container: 
          ...    key_id = Container: 
          ...        key_id_type = sha256_32 (total 9)
          ...        key_id = \xee\xee\x19\x0e (total 4)
          ...    freshness_funct = sha256 (total 6)
          ...    client_random = Container: 
          ...        gmt_unix_time = [\x8e\xe9\x03 (total 4)
          ...        random = ;\xe7\xfb,\x07\xba\x86\x068\xb4\xfc3'\x1d\x
          ...            f7\xd2T\xfcB\x87\xf8\xc8\xbe\x8b\xddV\xec\xb8 (t
          ...            otal 28)
          ...    server_random = Container: 
          ...        gmt_unix_time = [\x8e\xe9\x03 (total 4)
          ...        random = 2\x0f^\xe3VFp\x80\n^\xcb\xa2\xc0\x8b\x8e,\x
          ...            01\x13\xafB\x17\x8a\xb8\x8d\xa4\xe3\x82\xb8 (tot
          ...            al 28)
          ...    encrypted_premaster = W\xb3\x0b\xb7"\x8a\xb2\x13\xcc\x97
          ...        &d*\xba3\x80K\x9f\xc0\x00<_\t\xf4O\xe9\x1ft\xb0\x95\
          ...        x9f\xd3`\xe6\xa8\x8dY\x15\xe7\x8b\x1e\x188\xffhO\x88
          ...        \x82\x94w/g\x1d\x0c\x89\xb7\xc4g\x87\xf9qv\xa9+... (
          ...        truncated, total 256)

    ...<----------




          ...Lurk Header
          ...Container: 
          ...    designation = tls12 (total 5)
          ...    version = v1 (total 2)
          ...    type = rsa_master (total 10)
          ...    status = success (total 7)
          ...    id = a(\x89\xb0\x97\x05\x0c\xcd (total 8)
          ...    length = 64
          ...TLS12RSAMasterResponsePayload
          ...Container: 
          ...    master = \xbbRPz>\xf5$\xdf\x0e\xe6?\x8d\x8bYj\xf9\x13(\x
          ...        fe\xd4q\xd7\x04\x97\t6\xcd\xf1J\x93-\xf4\xde\xb7\x97
          ...        d\x9bX\xa7\xdb\xdb\xe2J\x1a\xfa\x93R\xcb (total 48)

    ...---------->



== 6. Terminating the TLS Key Exchange with the TLS Client ==
-------------------------------------------------------------


    With the master secret, the TLS Key Exchange can be
              completed
    ...[ChangeCipherSpec]
    ...Finished
    ...-------->
    ...                    [ChangeCipherSpec]
    ...                        Finished
    ...                    <--------
    ...Application Data      <------->     Application Data

Manually generating the LURK exchange for TLS 1.2 RSA Master

Open a python3 shell and start the LURK server by typing

>>> from pylurk.core.lurk import LurkUDPServer
>>> LurkUDPServer()

Open a python3 shell and start sending LURK queries using a LURK Client

lurk_client = LurkUDPClient( )
query, response = lurk_client.resolve( designation='tls12',\
    version='v1', type='rsa_master', payload={})
##
## query response are dictionaries
##

>>> print(query)
{'designation': 'tls12', 'version': 'v1', 'type': 'rsa_master', 'status': 'request', 'id': 147517109808405528, 'length': 342, 'payload': Container(key_id=Container(key_id_type='sha256_32')(key_id=b'\xee\xee\x19\x0e'))(freshness_funct='null')(client_random=Container(gmt_unix_time=b'[\x8e\xddz')(random=b'\xfd \xf7\x8e\xfc\xd0\x133vS\x81\x14\xe7]z\xbd\xb7\xe9a\xf2\xb4\xe4\x92\xb1,\xfb\x84B'))(server_random=Container(gmt_unix_time=b'[\x8e\xddz')(random=b'\xc3\xe3o\x03>\xcf\xb7\xaa\xdd\xb2\x82\xc9kbg\xf2\xecfsP\x81:\xb4\xda\xe3\xd8\xa0I'))(encrypted_premaster=b'%\xe7{\xf9\x9a\x1d?\x1b\xd7\xfb\xd2\x9e\xc4\'\x9b\xb2\xcd\xe7N^\xd9\xfca?\x0c\x9b\x96\x88\r\xcd\xfa\xe5\x01\xe5\xf5\xa09.\xf1"\x93\xd2\x92\x90"_?\xae\xaa_\\\xe5A\xfb\x97\x84\xc1\xfe\xa8\xda\xfe\xdcu\xec@\xe7\x85\xd0\'\x91\xfa\xa3\xf3jD\xba3\xcbf\x05\x94H_!\x7f\xad\xcd\xfbhG\xf3p\xd1\xa1\xb3\xfe<\xd6\x1e&&8\x98\x86\xbb\x84SB\x98\xa0\xaa\x85@\xb8w\x82\xbf\xfe\x11\x9c\xea\\\xa2[;\'\x998o\xe3}\xd21b\x92@\xbb1qz\xb0\xb5\xebt\x16\x95E\xb2\t\xff~\xd6R\x95\xc7\xeb\xad.\x80%36i\xe8hE\x11\xe4\xe6\xf8\xb4|D-\x06\xa2E\x19\x89>t\x07\xb0jz\xda\xcd\r_G\xe4\x14vJ0\xfb3\x90\xd6$;\x0e\x193\x1d\x13r\xae\xc8\xda\x00\xf8\x0e\x96\x8b&\xf1\xcf\xcf\'\xc6\xe0F\xd7)\x0b|\xf5\r\xd9\xe0\x04\xf5\x93#\xbb?k\xb8.\xdevk\\\xa7\xba\x15\xb4\xc1\xeaiBR~\x84\xc6')}
>>> print(response)
{'designation': 'tls12', 'version': 'v1', 'type': 'rsa_master', 'status': 'success', 'id': b'\x02\x0c\x16\x07\xa0l\x1c\x18', 'length': 64, 'payload': Container(master=b"\xe7\x7f\xaa\xcc\xec8\n\xb1\x9f\xf5@\x05 \xdey\x11\x1b\xd8\xd7\xd2\xcev\x96l\xc3kf\x0b\x17\x10S\xbd\x10\xb2w\xa4\x1f\x87\xa0@'\xc6\xe5u\x15N\x94\x10")}

##
## query, response can nicely be printed using LurkMessage
##

>>> from pylurk.core.lurk import LurkMessage
>>> msg = LurkMessage()
>>> msg.show(query)
Lurk Header
Container: 
    designation = tls12 (total 5)
    version = v1 (total 2)
    type = rsa_master (total 10)
    status = request (total 7)
    id = \x02\x0c\x16\x07\xa0l\x1c\x18 (total 8)
    length = 342
TLS12RSAMasterRequestPayload
Container: 
    key_id = Container: 
        key_id_type = sha256_32 (total 9)
        key_id = \xee\xee\x19\x0e (total 4)
    freshness_funct = null (total 4)
    client_random = Container: 
        gmt_unix_time = [\x8e\xddz (total 4)
        random = \xfd \xf7\x8e\xfc\xd0\x133vS\x81\x14\xe7]z\
            xbd\xb7\xe9a\xf2\xb4\xe4\x92\xb1,\xfb\x84B (tota
            l 28)
    server_random = Container: 
        gmt_unix_time = [\x8e\xddz (total 4)
        random = \xc3\xe3o\x03>\xcf\xb7\xaa\xdd\xb2\x82\xc9k
            bg\xf2\xecfsP\x81:\xb4\xda\xe3\xd8\xa0I (total 2
            8)
    encrypted_premaster = %\xe7{\xf9\x9a\x1d?\x1b\xd7\xfb\xd
        2\x9e\xc4\'\x9b\xb2\xcd\xe7N^\xd9\xfca?\x0c\x9b\x96\
        x88\r\xcd\xfa\xe5\x01\xe5\xf5\xa09.\xf1"\x93\xd2\x92
        \x90"_?\xae\xaa_\\\xe5A\xfb\x97\x84\xc1\xfe\xa8\xda\
        xfe\xdcu\xec... (truncated, total 256)

>>> msg.show(response)
Lurk Header
Container: 
    designation = tls12 (total 5)
    version = v1 (total 2)
    type = rsa_master (total 10)
    status = success (total 7)
    id = \x02\x0c\x16\x07\xa0l\x1c\x18 (total 8)
    length = 64
TLS12RSAMasterResponsePayload
Container: 
    master = \xe7\x7f\xaa\xcc\xec8\n\xb1\x9f\xf5@\x05 \xdey\
        x11\x1b\xd8\xd7\xd2\xcev\x96l\xc3kf\x0b\x17\x10S\xbd
        \x10\xb2w\xa4\x1f\x87\xa0@'\xc6\xe5u\x15N\x94\x10 (t
        otal 48)