Add method to generate a random mask (apple#1824)

* add static method to generate a random mask

* use SystemRandomNumberGenerator by default and add documentation

* use WebSocketMaskingKey instead of Self to support Swift 5.0

* add tests for random masking key

* add return keyword to support Swift 5.0

* run scripts/generate_linux_tests.rb

* rename T to Generator

* test SystemRandomNumberGenerator

* Revert "test SystemRandomNumberGenerator"

This reverts commit d9bdbe5.

* work around thread sanitizer bug on Swift 5.3

Author: dnadoba

Sources/NIOWebSocket/WebSocketFrame.swift

@@ -54,6 +54,7 @@ public struct WebSocketMaskingKey {
     /// - parameters:
     ///     - integer: The encoded network representation of the
     ///         masking key.
+    @usableFromInline
     internal init(networkRepresentation integer: UInt32) {
         self._key = (UInt8((integer & 0xFF000000) >> 24),
                      UInt8((integer & 0x00FF0000) >> 16),
@@ -71,6 +72,27 @@ extension WebSocketMaskingKey: ExpressibleByArrayLiteral {
     }
 }
 
+extension WebSocketMaskingKey {
+    /// Returns a random masking key, using the given generator as a source for randomness.
+    /// - Parameter generator: The random number generator to use when creating the
+    ///     new random masking key.
+    /// - Returns: A random masking key
+    @inlinable
+    public static func random<Generator>(
+        using generator: inout Generator
+    ) -> WebSocketMaskingKey where Generator: RandomNumberGenerator {
+        return WebSocketMaskingKey(networkRepresentation: .random(in: UInt32.min...UInt32.max, using: &generator))
+    }
+    
+    /// Returns a random masking key, using the `SystemRandomNumberGenerator` as a source for randomness.
+    /// - Returns: A random masking key
+    @inlinable
+    public static func random() -> WebSocketMaskingKey {
+        var generator = SystemRandomNumberGenerator()
+        return .random(using: &generator)
+    }
+}
+
 extension WebSocketMaskingKey: Equatable {
     public static func ==(lhs: WebSocketMaskingKey, rhs: WebSocketMaskingKey) -> Bool {
         return lhs._key == rhs._key

Tests/LinuxMain.swift

@@ -125,6 +125,7 @@ class LinuxMainRunnerImpl: LinuxMainRunner {
              testCase(WebSocketClientEndToEndTests.allTests),
              testCase(WebSocketFrameDecoderTest.allTests),
              testCase(WebSocketFrameEncoderTest.allTests),
+             testCase(WebSocketMaskingKeyTests.allTests),
              testCase(WebSocketServerEndToEndTests.allTests),
         ])
     }

Tests/NIOWebSocketTests/WebSocketMaskingKeyTests+XCTest.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+//
+// WebSocketMaskingKeyTests+XCTest.swift
+//
+import XCTest
+
+///
+/// NOTE: This file was generated by generate_linux_tests.rb
+///
+/// Do NOT edit this file directly as it will be regenerated automatically when needed.
+///
+
+extension WebSocketMaskingKeyTests {
+
+   @available(*, deprecated, message: "not actually deprecated. Just deprecated to allow deprecated tests (which test deprecated functionality) without warnings")
+   static var allTests : [(String, (WebSocketMaskingKeyTests) -> () throws -> Void)] {
+      return [
+                ("testRandomMaskingKey", testRandomMaskingKey),
+                ("testRandomMaskingKeyIsNotAlwaysZero", testRandomMaskingKeyIsNotAlwaysZero),
+           ]
+   }
+}
+

Tests/NIOWebSocketTests/WebSocketMaskingKeyTests.swift

@@ -0,0 +1,34 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import XCTest
+import NIO
+import NIOWebSocket
+
+final class WebSocketMaskingKeyTests: XCTestCase {
+    var generator = SystemRandomNumberGenerator()
+    func testRandomMaskingKey() {
+        let key = WebSocketMaskingKey.random(using: &generator)
+        var buffer = ByteBuffer(bytes: [1, 2, 3, 4, 5, 6, 7, 8])
+        buffer.webSocketMask(key)
+        buffer.webSocketUnmask(key)
+        XCTAssertEqual(buffer, ByteBuffer(bytes: [1, 2, 3, 4, 5, 6, 7, 8]))
+    }
+    
+    func testRandomMaskingKeyIsNotAlwaysZero() {
+        XCTAssertTrue((0..<1000).contains { _ in
+            WebSocketMaskingKey.random(using: &generator) != [0, 0, 0, 0]
+        }, "at least 1 of 1000 random masking keys should not be all zeros")
+    }
+}