github.com/pion/dtls/v2@v2.2.12/README.md (about)

     1  <h1 align="center">
     2    <br>
     3    Pion DTLS
     4    <br>
     5  </h1>
     6  <h4 align="center">A Go implementation of DTLS</h4>
     7  <p align="center">
     8    <a href="https://pion.ly"><img src="https://img.shields.io/badge/pion-dtls-gray.svg?longCache=true&colorB=brightgreen" alt="Pion DTLS"></a>
     9    <a href="https://sourcegraph.com/github.com/pion/dtls"><img src="https://sourcegraph.com/github.com/pion/dtls/-/badge.svg" alt="Sourcegraph Widget"></a>
    10    <a href="https://pion.ly/slack"><img src="https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen" alt="Slack Widget"></a>
    11    <br>
    12    <img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/pion/dtls/test.yaml">
    13    <a href="https://pkg.go.dev/github.com/pion/dtls/v2"><img src="https://pkg.go.dev/badge/github.com/pion/dtls/v2.svg" alt="Go Reference"></a>
    14    <a href="https://codecov.io/gh/pion/dtls"><img src="https://codecov.io/gh/pion/dtls/branch/master/graph/badge.svg" alt="Coverage Status"></a>
    15    <a href="https://goreportcard.com/report/github.com/pion/dtls/v2"><img src="https://goreportcard.com/badge/github.com/pion/dtls/v2" alt="Go Report Card"></a>
    16    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
    17  </p>
    18  <br>
    19  
    20  Native [DTLS 1.2][rfc6347] implementation in the Go programming language.
    21  
    22  A long term goal is a professional security review, and maybe an inclusion in stdlib.
    23  
    24  ### RFCs
    25  #### Implemented
    26  - **RFC 6347**: [Datagram Transport Layer Security Version 1.2][rfc6347]
    27  - **RFC 5705**: [Keying Material Exporters for Transport Layer Security (TLS)][rfc5705]
    28  - **RFC 7627**: [Transport Layer Security (TLS) - Session Hash and Extended Master Secret Extension][rfc7627]
    29  - **RFC 7301**: [Transport Layer Security (TLS) - Application-Layer Protocol Negotiation Extension][rfc7301]
    30  
    31  [rfc5289]: https://tools.ietf.org/html/rfc5289
    32  [rfc5487]: https://tools.ietf.org/html/rfc5487
    33  [rfc5489]: https://tools.ietf.org/html/rfc5489
    34  [rfc5705]: https://tools.ietf.org/html/rfc5705
    35  [rfc6347]: https://tools.ietf.org/html/rfc6347
    36  [rfc6655]: https://tools.ietf.org/html/rfc6655
    37  [rfc7301]: https://tools.ietf.org/html/rfc7301
    38  [rfc7627]: https://tools.ietf.org/html/rfc7627
    39  [rfc8422]: https://tools.ietf.org/html/rfc8422
    40  
    41  ### Goals/Progress
    42  This will only be targeting DTLS 1.2, and the most modern/common cipher suites.
    43  We would love contributions that fall under the 'Planned Features' and any bug fixes!
    44  
    45  #### Current features
    46  * DTLS 1.2 Client/Server
    47  * Key Exchange via ECDHE(curve25519, nistp256, nistp384) and PSK
    48  * Packet loss and re-ordering is handled during handshaking
    49  * Key export ([RFC 5705][rfc5705])
    50  * Serialization and Resumption of sessions
    51  * Extended Master Secret extension ([RFC 7627][rfc7627])
    52  * ALPN extension ([RFC 7301][rfc7301])
    53  
    54  #### Supported ciphers
    55  
    56  ##### ECDHE
    57  
    58  * TLS_ECDHE_ECDSA_WITH_AES_128_CCM ([RFC 6655][rfc6655])
    59  * TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 ([RFC 6655][rfc6655])
    60  * TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ([RFC 5289][rfc5289])
    61  * TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ([RFC 5289][rfc5289])
    62  * TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ([RFC 5289][rfc5289])
    63  * TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ([RFC 5289][rfc5289])
    64  * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ([RFC 8422][rfc8422])
    65  * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ([RFC 8422][rfc8422])
    66  
    67  ##### PSK
    68  
    69  * TLS_PSK_WITH_AES_128_CCM ([RFC 6655][rfc6655])
    70  * TLS_PSK_WITH_AES_128_CCM_8 ([RFC 6655][rfc6655])
    71  * TLS_PSK_WITH_AES_256_CCM_8 ([RFC 6655][rfc6655])
    72  * TLS_PSK_WITH_AES_128_GCM_SHA256 ([RFC 5487][rfc5487])
    73  * TLS_PSK_WITH_AES_128_CBC_SHA256 ([RFC 5487][rfc5487])
    74  
    75  ##### ECDHE & PSK
    76  
    77  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 ([RFC 5489][rfc5489])
    78  
    79  #### Planned Features
    80  * Chacha20Poly1305
    81  
    82  #### Excluded Features
    83  * DTLS 1.0
    84  * Renegotiation
    85  * Compression
    86  
    87  ### Using
    88  
    89  This library needs at least Go 1.13, and you should have [Go modules
    90  enabled](https://github.com/golang/go/wiki/Modules).
    91  
    92  #### Pion DTLS
    93  For a DTLS 1.2 Server that listens on 127.0.0.1:4444
    94  ```sh
    95  go run examples/listen/selfsign/main.go
    96  ```
    97  
    98  For a DTLS 1.2 Client that connects to 127.0.0.1:4444
    99  ```sh
   100  go run examples/dial/selfsign/main.go
   101  ```
   102  
   103  #### OpenSSL
   104  Pion DTLS can connect to itself and OpenSSL.
   105  ```
   106    // Generate a certificate
   107    openssl ecparam -out key.pem -name prime256v1 -genkey
   108    openssl req -new -sha256 -key key.pem -out server.csr
   109    openssl x509 -req -sha256 -days 365 -in server.csr -signkey key.pem -out cert.pem
   110  
   111    // Use with examples/dial/selfsign/main.go
   112    openssl s_server -dtls1_2 -cert cert.pem -key key.pem -accept 4444
   113  
   114    // Use with examples/listen/selfsign/main.go
   115    openssl s_client -dtls1_2 -connect 127.0.0.1:4444 -debug -cert cert.pem -key key.pem
   116  ```
   117  
   118  ### Using with PSK
   119  Pion DTLS also comes with examples that do key exchange via PSK
   120  
   121  #### Pion DTLS
   122  ```sh
   123  go run examples/listen/psk/main.go
   124  ```
   125  
   126  ```sh
   127  go run examples/dial/psk/main.go
   128  ```
   129  
   130  #### OpenSSL
   131  ```
   132    // Use with examples/dial/psk/main.go
   133    openssl s_server -dtls1_2 -accept 4444 -nocert -psk abc123 -cipher PSK-AES128-CCM8
   134  
   135    // Use with examples/listen/psk/main.go
   136    openssl s_client -dtls1_2 -connect 127.0.0.1:4444 -psk abc123 -cipher PSK-AES128-CCM8
   137  ```
   138  
   139  ### Community
   140  Pion has an active community on the [Slack](https://pion.ly/slack).
   141  
   142  Follow the [Pion Twitter](https://twitter.com/_pion) for project updates and important WebRTC news.
   143  
   144  We are always looking to support **your projects**. Please reach out if you have something to build!
   145  If you need commercial support or don't want to use public methods you can contact us at [team@pion.ly](mailto:team@pion.ly)
   146  
   147  ### Contributing
   148  Check out the [contributing wiki](https://github.com/pion/webrtc/wiki/Contributing) to join the group of amazing people making this project possible: [AUTHORS.txt](./AUTHORS.txt)
   149  
   150  ### License
   151  MIT License - see [LICENSE](LICENSE) for full text