ring-native 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 461c320a3ceded3e82039c266b94fb6ba358206a
+  data.tar.gz: b6b41a976430779509ad441fcbbf5d976ba639c7
+SHA512:
+  metadata.gz: d0b2953cafbd07ffb6a96ea9676ff47a4b40e12452f05a5b4970f8afccfc56cd1bb2b6c6f57d1b3131b94b731e5e7e5f5ead068b4306128281ad284d49b85152
+  data.tar.gz: 471388e5ba6ee776b31076f2a86f2e2145525cb3dae649e937968259b7adcdb05469d50d5d5cfe346886661a17a366b115ac523b7edc154f5a01ebe14119d963

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,22 @@
+ring-native
+===========
+[![Gem Version](https://badge.fury.io/rb/ring-native.png)](http://badge.fury.io/rb/ring-native)
+
+The [*ring* cryptography library][ring] packaged as a RubyGem. Since *ring* has
+no upstream releases, this gem will be released as periodic snapshots with
+version numbers corresponding to the date the snapshot was taken until such time
+as *ring* has versioned releases.
+
+The boilerplate code in the ring-native gem is MIT along with the rest of the
+ruby-ring gem, however *ring* itself is a fork of BoringSSL and therefore
+carries with it a mixture of licenses, mostly the OpenSSL license.
+
+For more information on the licensing of *ring* itself, please see the
+[*ring* LICENSE][license].
+
+[ring]: https://github.com/briansmith/ring/
+[license]: https://github.com/briansmith/ring/blob/master/LICENSE
+
+# Usage
+
+This gem is automatically installed along with the *ring* gem.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/ext/ring/extconf.rb

@@ -0,0 +1,29 @@
+require "fileutils"
+
+def sys(cmd)
+  puts " -- #{cmd}"
+  unless ret = system(cmd)
+    raise "ERROR: '#{cmd}' failed"
+  end
+  ret
+end
+
+ring_src = File.expand_path("../../../vendor/ring", __FILE__)
+ring_dst = File.expand_path("../../../lib/ring/native", __FILE__)
+
+filename = RUBY_DESCRIPTION[/darwin/] ? "libring.dylib" : "libring.so"
+
+Dir.chdir(ring_src) do
+  sys("cargo build --release")
+  FileUtils.cp "target/release/#{filename}", ring_dst
+end
+
+makefile = <<MAKEFILE
+install:
+\t@echo "Nothing to do"
+
+clean:
+\t@echo "Nothing to do"
+MAKEFILE
+
+File.open("Makefile", "w") { |f| f.write(makefile) }

data/lib/ring/native.rb

@@ -0,0 +1,8 @@
+require "ring/native/version"
+
+module Ring
+  module Native
+    filename = RUBY_DESCRIPTION[/darwin/] ? "libring.dylib" : "libring.so"
+    LIB_PATH = File.expand_path("../native/#{filename}", __FILE__)
+  end
+end

data/lib/ring/native/version.rb

@@ -0,0 +1,5 @@
+module Ring
+  module Native
+    VERSION = "0.0.0"
+  end
+end

data/ring-native.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ring/native/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ring-native"
+  spec.version       = Ring::Native::VERSION
+  spec.authors       = ["Tony Arcieri"]
+  spec.email         = ["bascule@gmail.com"]
+
+  spec.summary       = "The *ring* cryptography library, packaged as a RubyGem"
+  spec.description   = "Snapshots of the *ring* cryptography library, packaged in RubyGem format"
+  spec.homepage      = "https://github.com/cryptosphere/ruby-ring"
+  spec.license       = "OpenSSL"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.files         += Dir.glob("vendor/ring/**/*")
+  spec.require_paths = ["lib"]
+
+  spec.extensions    = ["ext/ring/extconf.rb"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/vendor/ring/BUILDING.md

@@ -0,0 +1,40 @@
+Building *ring*
+===============
+
+*ring*'s Rust crate is named ```ring```. You can build it
+using ```cargo build --release``` and you can run the tests
+with ```cargo test --release```. When you use ```cargo``` to build *ring,
+the build script [build.rs](build.rs) automatically builds the C and
+assembly language components of *ring*.
+
+Currently on Windows you must currently invoke cargo from a Visual Studio
+Native Tools Command Prompt. Otherwise the build will likely fail in confusing
+ways because either msbuild won't be found or there will be a version mismatch
+between the toolchain used to build the C parts of the library and the toolchain
+used by cargo/rustc for linking. Visual Studio 2015 Update 1 and Visual Studio
+2013 Update 5 are supported.
+
+*ring* uses Visual Studio's native build system (msbuild) on Windows, and GNU
+Make otherwise. Because this is a little unusual, I would be particularly grateful
+if you could report any problems building (or using) *ring*'s Rust crate.
+
+GCC 4.8 and later, and Clang 3.4 and later are supported. Other compilers
+will also probably work without too much trouble. Note in particular that if
+you are cross-compiling an x86 build on a 64-bit version of Linux, then you
+need to have the proper gcc-multilibs and g++-multilibs packages or equivalent
+installed.
+
+
+
+Prerequisites for Regenerating `crypto/chacha/chacha_vec_arm.S`
+===============================================================
+
+If you change `crypto/chacha/chacha_vec.c`, you will need the
+arm-linux-gnueabihf-gcc compiler:
+
+```
+wget https://releases.linaro.org/14.11/components/toolchain/binaries/arm-linux-gnueabihf/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz && \
+echo bc4ca2ced084d2dc12424815a4442e19cb1422db87068830305d90075feb1a3b  gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz | sha256sum -c && \
+tar xf gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf.tar.xz && \
+sudo mv gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf /opt/
+```

data/vendor/ring/Cargo.toml

@@ -0,0 +1,43 @@
+[package]
+authors = ["Brian Smith <brian@briansmith.org>"]
+build = "build.rs"
+description = "A Rust interface for a simplification of BoringSSL's libcrypto."
+license-file = "LICENSE"
+name = "ring"
+readme = "README.md"
+repository = "https://github.com/briansmith/ring"
+version = "0.1.0"
+
+[lib]
+name = "ring"
+crate_type = ["dylib"]
+
+[build-dependencies]
+num = "0.1.27"
+rustc-serialize = "0.3.15"
+
+[dev-dependencies]
+rustc-serialize = "0.3.15"
+time = "0.1.32"
+
+# Fix the `bench`, `release`, and `test` profiles so they all have the
+# same configuration.
+#
+# XXX: We can't build with `debug = true` yet because that breaks the
+# Windows builds. See https://github.com/briansmith/ring/issues/44.
+
+[profile.bench]
+opt-level = 3
+debug = false
+rpath = false
+lto = true
+debug-assertions = false
+codegen-units = 1
+
+[profile.release]
+opt-level = 3
+debug = false
+rpath = false
+lto = true
+debug-assertions = false
+codegen-units = 1

data/vendor/ring/LICENSE

@@ -0,0 +1,185 @@
+BoringSSL is a fork of OpenSSL. As such, large parts of it fall under OpenSSL
+licensing. Files that are completely new have a Google copyright and an ISC
+license. This license is reproduced at the bottom of this file.
+
+Contributors to BoringSSL are required to follow the CLA rules for Chromium:
+https://cla.developers.google.com/clas
+
+Some files from Intel are under yet another license, which is also included
+underneath.
+
+The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the
+OpenSSL License and the original SSLeay license apply to the toolkit. See below
+for the actual license texts. Actually both licenses are BSD-style Open Source
+licenses. In case of any license issues related to OpenSSL please contact
+openssl-core@openssl.org.
+
+  OpenSSL License
+  ---------------
+
+/* ====================================================================
+ * Copyright (c) 1998-2011 The OpenSSL Project.  All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer. 
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. All advertising materials mentioning features or use of this
+ *    software must display the following acknowledgment:
+ *    "This product includes software developed by the OpenSSL Project
+ *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+ *
+ * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+ *    endorse or promote products derived from this software without
+ *    prior written permission. For written permission, please contact
+ *    openssl-core@openssl.org.
+ *
+ * 5. Products derived from this software may not be called "OpenSSL"
+ *    nor may "OpenSSL" appear in their names without prior written
+ *    permission of the OpenSSL Project.
+ *
+ * 6. Redistributions of any form whatsoever must retain the following
+ *    acknowledgment:
+ *    "This product includes software developed by the OpenSSL Project
+ *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+ * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This product includes cryptographic software written by Eric Young
+ * (eay@cryptsoft.com).  This product includes software written by Tim
+ * Hudson (tjh@cryptsoft.com).
+ *
+ */
+
+ Original SSLeay License
+ -----------------------
+
+/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
+ * All rights reserved.
+ *
+ * This package is an SSL implementation written
+ * by Eric Young (eay@cryptsoft.com).
+ * The implementation was written so as to conform with Netscapes SSL.
+ * 
+ * This library is free for commercial and non-commercial use as long as
+ * the following conditions are aheared to.  The following conditions
+ * apply to all code found in this distribution, be it the RC4, RSA,
+ * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
+ * included with this distribution is covered by the same copyright terms
+ * except that the holder is Tim Hudson (tjh@cryptsoft.com).
+ * 
+ * Copyright remains Eric Young's, and as such any Copyright notices in
+ * the code are not to be removed.
+ * If this package is used in a product, Eric Young should be given attribution
+ * as the author of the parts of the library used.
+ * This can be in the form of a textual message at program startup or
+ * in documentation (online or textual) provided with the package.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. All advertising materials mentioning features or use of this software
+ *    must display the following acknowledgement:
+ *    "This product includes cryptographic software written by
+ *     Eric Young (eay@cryptsoft.com)"
+ *    The word 'cryptographic' can be left out if the rouines from the library
+ *    being used are not cryptographic related :-).
+ * 4. If you include any Windows specific code (or a derivative thereof) from 
+ *    the apps directory (application code) you must include an acknowledgement:
+ *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
+ * 
+ * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * 
+ * The licence and distribution terms for any publically available version or
+ * derivative of this code cannot be changed.  i.e. this code cannot simply be
+ * copied and put under another distribution licence
+ * [including the GNU Public Licence.]
+ */
+
+
+ISC license used for completely new code in BoringSSL:
+
+/* Copyright (c) 2015, Google Inc.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+ * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
+
+
+Some files from Intel carry the following license:
+
+# Copyright (c) 2012, Intel Corporation
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# *  Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# *  Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the
+#    distribution.
+#
+# *  Neither the name of the Intel Corporation nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+#
+# THIS SOFTWARE IS PROVIDED BY INTEL CORPORATION ""AS IS"" AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL CORPORATION OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/vendor/ring/Makefile

@@ -0,0 +1,35 @@
+# Copyright 2015 Brian Smith.
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND BRIAN SMITH AND THE AUTHORS DISCLAIM
+# ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL BRIAN SMITH OR THE AUTHORS
+# BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+# DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+# AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+include mk/top_of_makefile.mk
+
+RING_PREFIX =
+
+include mk/ring.mk
+
+OBJS += \
+  $(RING_OBJS) \
+  $(RING_TEST_LIB_OBJS) \
+  $(RING_TEST_MAIN_OBJS) \
+  $(NULL)
+
+LIBS += \
+  $(RING_LIB) \
+  $(NULL)
+
+EXES += $(RING_TEST_EXES)
+
+check:: check-ring
+
+include mk/bottom_of_makefile.mk

data/vendor/ring/PORTING.md

@@ -0,0 +1,163 @@
+# Porting from OpenSSL to BoringSSL
+
+BoringSSL is an OpenSSL derivative and is mostly source-compatible, for the
+subset of OpenSSL retained. Libraries ideally need little to no changes for
+BoringSSL support, provided they do not use removed APIs. In general, see if the
+library compiles and, on failure, consult the documentation in the header files
+and see if problematic features can be removed.
+
+In some cases, BoringSSL-specific code may be necessary. In that case, the
+`OPENSSL_IS_BORINGSSL` preprocessor macro may be used in `#ifdef`s. This macro
+should also be used in lieu of the presence of any particular function to detect
+OpenSSL vs BoringSSL in configure scripts, etc., where those are necessary.
+
+For convenience, BoringSSL defines upstream's `OPENSSL_NO_*` feature macros
+corresponding to removed features. These may also be used to disable code which
+uses a removed feature.
+
+Note: BoringSSL does *not* have a stable API or ABI. It must be updated with its
+consumers. It is not suitable for, say, a system library in a traditional Linux
+distribution. For instance, Chromium statically links the specific revision of
+BoringSSL it was built against. Likewise, Android's system-internal copy of
+BoringSSL is not exposed by the NDK and must not be used by third-party
+applications.
+
+
+## Major API changes
+
+### Integer types
+
+Some APIs have been converted to use `size_t` for consistency and to avoid
+integer overflows at the API boundary. (Existing logic uses a mismash of `int`,
+`long`, and `unsigned`.)  For the most part, implicit casts mean that existing
+code continues to compile. In some cases, this may require BoringSSL-specific
+code, particularly to avoid compiler warnings.
+
+Most notably, the `STACK_OF(T)` types have all been converted to use `size_t`
+instead of `int` for indices and lengths.
+
+### Reference counts
+
+Some external consumers increment reference counts directly by calling
+`CRYPTO_add` with the corresponding `CRYPTO_LOCK_*` value.
+
+These APIs no longer exist in BoringSSL. Instead, code which increments
+reference counts should call the corresponding `FOO_up_ref` function, such as
+`EVP_PKEY_up_ref`. Note that not all of these APIs are present in OpenSSL and
+may require `#ifdef`s.
+
+### Error codes
+
+OpenSSL's errors are extremely specific, leaking internals of the library,
+including even a function code for the function which emitted the error! As some
+logic in BoringSSL has been rewritten, code which conditions on the error may
+break (grep for `ERR_GET_REASON` and `ERR_GET_FUNC`). This danger also exists
+when upgrading OpenSSL versions.
+
+Where possible, avoid conditioning on the exact error reason. Otherwise, a
+BoringSSL `#ifdef` may be necessary. Exactly how best to resolve this issue is
+still being determined. It's possible some new APIs will be added in the future.
+
+Function codes have been completely removed. Remove code which conditions on
+these as it will break with the slightest change in the library, OpenSSL or
+BoringSSL.
+
+### `*_ctrl` functions
+
+Some OpenSSL APIs are implemented with `ioctl`-style functions such as
+`SSL_ctrl` and `EVP_PKEY_CTX_ctrl`, combined with convenience macros, such as
+
+    # define SSL_CTX_set_mode(ctx,op) \
+            SSL_CTX_ctrl((ctx),SSL_CTRL_MODE,(op),NULL)
+
+In BoringSSL, these macros have been replaced with proper functions. The
+underlying `_ctrl` functions have been removed.
+
+For convenience, `SSL_CTRL_*` values are retained as macros to `doesnt_exist` so
+existing code which uses them (or the wrapper macros) in `#ifdef` expressions
+will continue to function. However, the macros themselves will not work.
+
+Switch any `*_ctrl` callers to the macro/function versions. This works in both
+OpenSSL and BoringSSL. Note that BoringSSL's function versions will be
+type-checked and may require more care with types.
+
+### HMAC `EVP_PKEY`s
+
+`EVP_PKEY_HMAC` is removed. Use the `HMAC_*` functions in `hmac.h` instead. This
+is compatible with OpenSSL.
+
+### DSA `EVP_PKEY`s
+
+`EVP_PKEY_DSA` is deprecated. It is currently still possible to parse DER into a
+DSA `EVP_PKEY`, but signing or verifying with those objects will not work.
+
+### DES
+
+The `DES_cblock` type has been switched from an array to a struct to avoid the
+pitfalls around array types in C. Where features which require DES cannot be
+disabled, BoringSSL-specific codepaths may be necessary.
+
+### TLS renegotiation
+
+OpenSSL enables TLS renegotiation by default and accepts renegotiation requests
+from the peer transparently. Renegotiation is an extremely problematic protocol
+feature, so BoringSSL rejects peer renegotiations by default.
+
+To enable renegotiation, call `SSL_set_reject_peer_renegotiations` and set it to
+off. Renegotiation is only supported as a client in SSL3/TLS and the
+HelloRequest must be received at a quiet point in the application protocol. This
+is sufficient to support the common use of requesting a new client certificate
+between an HTTP request and response in (unpipelined) HTTP/1.1.
+
+Things which do not work:
+
+* There is no support for renegotiation as a server.
+
+* There is no support for renegotiation in DTLS.
+
+* There is no support for initiating renegotiation; `SSL_renegotiate` always
+  fails and `SSL_set_state` does nothing.
+
+* Interleaving application data with the new handshake is forbidden.
+
+* If a HelloRequest is received while `SSL_write` has unsent application data,
+  the renegotiation is rejected.
+
+### Lowercase hexadecimal
+
+BoringSSL's `BN_bn2hex` function uses lowercase hexadecimal digits instead of
+uppercase. Some code may require changes to avoid being sensitive to this
+difference.
+
+
+## Optional BoringSSL-specific simplifications
+
+BoringSSL makes some changes to OpenSSL which simplify the API but remain
+compatible with OpenSSL consumers. In general, consult the BoringSSL
+documentation for any functions in new BoringSSL-only code.
+
+### Return values
+
+Most OpenSSL APIs return 1 on success and either 0 or -1 on failure. BoringSSL
+has narrowed most of these to 1 on success and 0 on failure. BoringSSL-specific
+code may take advantage of the less error-prone APIs and use `!` to check for
+errors.
+
+### Initialization
+
+OpenSSL has a number of different initialization functions for setting up error
+strings and loading algorithms, etc. All of these functions still exist in
+BoringSSL for convenience, but they do nothing and are not necessary.
+
+The one exception is `CRYPTO_library_init`. In `BORINGSSL_NO_STATIC_INITIALIZER`
+builds, it must be called to query CPU capabitilies before the rest of the
+library. In the default configuration, this is done with a static initializer
+and is also unnecessary.
+
+### Threading
+
+OpenSSL provides a number of APIs to configure threading callbacks and set up
+locks. Without initializing these, the library is not thread-safe. Configuring
+these does nothing in BoringSSL. Instead, BoringSSL calls pthreads and the
+corresponding Windows APIs internally and is always thread-safe where the API
+guarantees it.