-
Notifications
You must be signed in to change notification settings - Fork 15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Port openssl package #1
Changes from 4 commits
3c99c36
f106b8e
35e17de
d296190
1bc1e79
8f47540
c68b472
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,14 +1,65 @@ | ||
# Project | ||
# go-crypto-openssl | ||
|
||
> This repo has been populated by an initial template to help get you started. Please | ||
> make sure to update the content to build a great experience for community-building. | ||
The `openssl` package implements Go crypto primitives using OpenSSL shared libraries and cgo. When configured correctly, OpenSSL can be executed in FIPS mode, making the `openssl` package FIPS compliant. | ||
|
||
As the maintainer of this project, please make a few updates: | ||
The `openssl` package is designed to be used as a drop-in replacement for the [boring](https://pkg.go.dev/crypto/internal/boring) package in order to facilitate integrating `openssl` inside a forked Go toolchain. | ||
|
||
- Improving this README.MD file to provide a great experience | ||
- Updating SUPPORT.MD with content about this project's support experience | ||
- Understanding the security reporting process in SECURITY.MD | ||
- Remove this section from the README | ||
## Background | ||
|
||
FIPS 140-2 is a U.S. government computer security standard used to approve cryptographic modules. FIPS compliance may come up when working with U.S. government and other regulated industries. | ||
|
||
### Go FIPS compliance | ||
|
||
The Go `crypto` package is not FIPS certified, and the Go team has stated that it won't be, e.g. in [golang/go/issues/21734](https://github.com/golang/go/issues/21734#issuecomment-326980213) Adam Langley says: | ||
|
||
> The status of FIPS 140 for Go itself remains "no plans, basically zero chance". | ||
|
||
On the other hand, Google maintains a branch that uses cgo and BoringSSL to implement various crypto primitives: https://github.com/golang/go/blob/dev.boringcrypto/README.boringcrypto.md. As BoringSSL is FIPS 140-2 certified, an application using that branch is more likely to be FIPS 140-2 compliant, yet Google does not provide any liability about the suitability of this code in relation to the FIPS 140-2 standard. | ||
|
||
## Features | ||
|
||
### Multiple OpenSSL versions supported | ||
|
||
OpenSSL does not maintain ABI compatibility between different releases, even if only the last digit is increased. The `openssl` package has support for multiple OpenSSL versions, yet each version has a different amount of automated validation: | ||
|
||
- OpenSSL 1.1.1: the Microsoft CI builds official releases and runs automated tests with this version. | ||
- OpenSSL 1.0.1: the Microsoft CI builds official releases, but doesn't run tests, so it may not produce working applications. | ||
- OpenSSL 1.1.0 and 3.0: the Microsoft CI does not build nor test these versions, so they may or may not work. | ||
|
||
Versions not listed above are not supported at all. | ||
|
||
### Dynamic OpenSSL loading | ||
|
||
The OpenSSL shared library `libcrypto` is loaded at runtime using [dlopen](https://man7.org/linux/man-pages/man3/dlopen.3.html) when calling `openssl.Init`. Therefore, dlopen's shared library search conventions also apply here. | ||
|
||
The `libcrypto` shared library file name varies among different platforms, so a best effort is done to find and load the right file: | ||
|
||
- The base name is always `libcrypto.so`. | ||
- Well-known version strings are appended to the base name, until the file is found, in the following order: `3` -> `1.1` -> `11` -> `111` -> `1.0.2` -> `1.0.0`. | ||
|
||
This algorithm can be overridden by setting the environment variable `GO_OPENSSL_VERSION_OVERRIDE` to the desired version string. For example, `GO_OPENSSL_VERSION_OVERRIDE="1.1.1k-fips"` makes the runtime look for the shared library `libcrypto.so.1.1.1k-fips` before running the checks for well-known versions. | ||
|
||
### Portable OpenSSL | ||
|
||
The OpenSSL bindings are implemented in such a way that the OpenSSL version used when building a program does not have to match with the OpenSSL version used when running it. | ||
|
||
This feature does not require any additional configuration, but it only works with OpenSSL versions known and supported by the Go toolchain. | ||
|
||
## Limitations | ||
|
||
OpenSSL is used for a given build only in limited circumstances: | ||
|
||
- The platform must be GOOS=linux. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm, do you know if this will probably work on arm64 etc.? Nothing comes to mind that would prevent it from working just like it does on amd64, but this made me curious. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It should work on any platform that is supported by OpenSSL and that can use |
||
- The build must have cgo enabled. | ||
- The android build tag must not be specified. | ||
|
||
## Acknowledgements | ||
|
||
The work done to support FIPS compatibility mode leverages code and ideas from other open-source projects: | ||
|
||
- All crypto stubs are a mirror of Google's [dev.boringcrypto branch](https://github.com/golang/go/tree/dev.boringcrypto) and the release branch ports of that branch. | ||
- The mapping between BoringSSL and OpenSSL APIs is taken from Fedora's [Go fork](https://pagure.io/go). | ||
- The portable OpenSSL implementation is ported from Microsoft's [.NET runtime](https://github.com/dotnet/runtime) cryptography module. | ||
|
||
## Contributing | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
module github.com/microsoft/go-crypto-openssl | ||
|
||
go 1.16 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The end of this sentence sort of implies that we do provide liability, but it's not explicitly called out. Should we clarify our stance?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Or at least, OpenSSL does. Either way, as a consumer, it's a bit confusing as to what exactly the guarantees are here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree that we should be more explicit regarding the FIPS guarantees when using this package, but I'm afraid we don't have them clear yet. Meanwhile I've added a disclaimer into the README which should help on creating the right expectations.
@jaredpar do you have any insights here?