Skip to content

Commit 7d5db5b

Browse files
quarcksterquarckster
committed
add OpenSSLStrategicArchitecture.md
1 parent dd307f2 commit 7d5db5b

File tree

3 files changed

+297
-1
lines changed

3 files changed

+297
-1
lines changed

Diff for: ‎hooks.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
from mkdocs.structure.pages import Page
1313

1414
MAN_INDEXES = ["man1/index.md", "man3/index.md", "man5/index.md", "man7/index.md"]
15-
SKIP_FILES = ["index.md", "fips.md", "OpenSSL300Design.md"]
15+
SKIP_FILES = ["index.md", "fips.md", "OpenSSL300Design.md", "OpenSSLStrategicArchitecture.md"]
1616
LINKS_PATTERN = re.compile(r"\.\.\/\.\.\/man[1,3,5,7]{1}\/[a-zA-Z0-9_\-.]+")
1717
HEADINGS_PATTERN = re.compile(r" {0,3}(#{1,6})((?=\s)[^\n]*?|[^\n\S]*)(?:(?<=\s)(?<!\\)#+)?[^\n\S]*$\n?", flags=re.M)
1818
LINKS_MAP = {}
@@ -135,6 +135,7 @@ def on_nav(nav: Navigation, config: MkDocsConfig, files: Files) -> Navigation:
135135
"index": "Home",
136136
"fips": "FIPS-140",
137137
"OpenSSL300Design": "OpenSSL 3.0.0 Design (Draft)",
138+
"OpenSSLStrategicArchitecture": "OpenSSL Strategic Architecture",
138139
"man1": "Commands",
139140
"man3": "Libraries",
140141
"man5": "File Formats",

Diff for: ‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ site_url: https://docs.openssl.org/
33
repo_url: https://github.com/openssl/openssl
44
not_in_nav: |
55
/OpenSSL300Design.md
6+
/OpenSSLStrategicArchitecture.md
67
extra:
78
version:
89
provider: mike

Diff for: ‎scaffold/OpenSSLStrategicArchitecture.md

+294
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
---
2+
hide:
3+
- navigation
4+
author: OpenSSL Management Committee (OMC)
5+
date: January, 2019
6+
---
7+
8+
# OpenSSL Strategic Architecture
9+
10+
## Introduction
11+
12+
This document outlines the OpenSSL strategic architecture. It will take
13+
multiple releases, starting from 3.0.0, to move the architecture from
14+
the current "as-is" (1.1.1), to the future "to-be" architecture.
15+
16+
Numerous changes are anticipated in the to-be architecture. A migration
17+
path for handling the eventual transition will be provided. The OpenSSL
18+
3.0.0 release will have minimal impact to the vast majority of existing
19+
applications, almost all well-behaved applications will just need to be
20+
recompiled.
21+
22+
The current functionality provided by the engine interface will be
23+
replaced over time via a provider interface. OpenSSL 3.0.0 will continue
24+
to support engines. The to-be architecture will not be fully realised
25+
until OpenSSL 4.0.0 at the earliest.
26+
27+
## As-is architecture
28+
29+
Currently, OpenSSL is split into four principal components:
30+
31+
1. libcrypto. This is the core library for providing implementations of
32+
numerous cryptographic primitives. In addition it provides a set of
33+
supporting services which are used by libssl and libcrypto, as well
34+
as implementations of protocols such as CMS and OCSP.
35+
36+
2. Engine. The functionality of libcrypto can be extended through the
37+
Engine API.
38+
39+
Typically engines are dynamically loadable modules that are registered
40+
with libcrypto and use the available hooks to provide cryptographic
41+
algorithm implementations. Usually these are alternative implementations
42+
of algorithms already provided by libcrypto (e.g. to enable hardware
43+
acceleration of the algorithm), but they may also include algorithms not
44+
implemented in default OpenSSL (e.g. the GOST engine implements the GOST
45+
algorithm family). Some engines are provided as part of the OpenSSL
46+
distribution, and some are provided by external third parties (again,
47+
GOST).
48+
49+
3. libssl. This library depends on libcrypto and implements the TLS and
50+
DTLS protocols.
51+
52+
4. Applications. The applications are a set of command line tools that
53+
use the underlying libssl and libcrypto components to provide a set
54+
of cryptographic and other features such as:
55+
a. Key and parameter generation and inspection
56+
b. Certificate generation and inspection
57+
c. SSL/TLS test tools
58+
d. ASN.1 inspection
59+
e. Etc
60+
61+
Currently, OpenSSL has the following characteristics:
62+
63+
1. EVP. The EVP (envelope) API level provides the high-level abstract
64+
interface to cryptographic functionality separate from the concrete
65+
implementation binding. Direct use of concrete cryptographic
66+
algorithm implementations via interfaces other than the EVP layer is
67+
discouraged. The EVP layer also provides composite operations, such
68+
as signing and verifying. Certain composite operations are also
69+
provided as an EVP-level operation (such as HMAC-SHA256). EVP also
70+
allow use of cryptographic algorithms in an algorithm-agnostic
71+
manner (e.g. EVP\_DigestSign works for both RSA and ECDSA
72+
algorithms).
73+
74+
2. FIPS140 is not supported. FIPS140 it is only available in
75+
OpenSSL-1.0.2 which predates the as-is architecture and is not API
76+
or ABI compatible.
77+
78+
### Conceptual Component View
79+
80+
The existing architecture is a simple 4 level layering with the crypto
81+
layer at the bottom. The TLS layer depends on the crypto layer, and the
82+
applications depend on both the TLS and crypto layers.
83+
84+
Note: the existence of a component in the diagram does not indicate that
85+
the component is a public API or intended for end-user direct access or
86+
usage.
87+
88+
![](images/AsIsComponent.png)
89+
90+
### Packaging View
91+
92+
The components described above are packaged into libraries (libcrypto
93+
and libssl) and associated engine interfaces as well as an "openssl"
94+
command line executable for running the various applications. This is
95+
illustrated in the diagram below.
96+
97+
![](images/AsIsPackaging.png)
98+
99+
## To-be Architecture
100+
101+
The to-be architecture has the following features:
102+
103+
- Core Services form the building blocks usable by applications and
104+
providers. (e.g. BIO, X509, SECMEM, ASN1, etc).
105+
106+
- Providers implement cryptographic algorithms and supporting
107+
services. A provider has implementations of one or more of the
108+
following:
109+
110+
- The cryptographic primitives for an algorithm, e.g. how to
111+
encrypt/decrypt/sign/hash etc.
112+
- Serialisation for an algorithm, e.g. how to convert a private
113+
key into a PEM file. Serialisation could be to or from formats
114+
that are not currently supported.
115+
- Store loader back ends. OpenSSL currently has a store loader
116+
that reads keys, parameters and other items from files.
117+
Providers could have a loader to load from another location
118+
(e.g. LDAP directory).
119+
120+
A Provider may be entirely self-contained or it may use services that
121+
are provided by different providers or the Core Services. For example,
122+
an application may use the cryptographic primitives for an algorithm
123+
implemented by a hardware accelerated provider, but use the
124+
serialisation services of a different provider in order to export keys
125+
into PKCS\#12 format.
126+
127+
A default provider (which contains the core of the current OpenSSL
128+
cryptographic algorithm implementations) will be "built-in" but other
129+
providers will be able to be dynamically loadable at runtime.
130+
131+
Legacy provider module(s) will provide cryptographic implementations for
132+
older algorithms (e.g., DES, MDC2, MD2, Blowfish, CAST). The OMC will
133+
publish a policy for how and when algorithms are transitioned from the
134+
default provider to the legacy provider.
135+
136+
A FIPS provider that embodies the OpenSSL FIPS Cryptographic Module will
137+
be able to be dynamically loaded at runtime.
138+
139+
- The Core enables access to the services offered by providers to
140+
applications (and other providers). Providers make methods available
141+
to the Core. The Core is the mechanism via which concrete
142+
implementations of where things such as algorithms are located.
143+
144+
The Core will implement a property based look-up feature for finding
145+
algorithms, e.g. it might allow you find an algorithm where "fips=true",
146+
or "keysize=128, constant\_time=true". The details of this will be
147+
determined in later design documents.
148+
149+
- Protocol implementations. E.g. TLS, DTLS.
150+
151+
The to-be architecture has the following characteristics:
152+
153+
- The EVP layer becomes a thin wrapper for services implemented in the
154+
providers. Most calls are passed straight through with little/no
155+
pre- or post-processing.
156+
157+
- New EVP APIs will be provided to find the implementation of an
158+
algorithm in the Core to be used for any given EVP call.
159+
160+
- Information will be passed between the core library and the
161+
providers in an implementation agnostic way.
162+
163+
- Legacy APIs (e.g. low level cryptographic APIs that do not go via
164+
the EVP layer) will be deprecated. Note that there are legacy APIs
165+
to non legacy algorithms (e.g. AES is a non-legacy algorithm but
166+
AES\_encrypt is a legacy API).
167+
168+
- The OpenSSL FIPS Cryptographic Module will be implemented as a
169+
dynamically loaded provider. It will be self-contained (i.e. can
170+
only depend on system runtime libraries and services provided by the
171+
Core).
172+
173+
- Other interfaces may also be transitioned to use the Core over time
174+
(for example OSSL\_STORE might be considered for this).
175+
176+
- Engine usage will evolve to providers. "*Bye-bye-Engines,
177+
Hello-Providers".*
178+
179+
### Conceptual Component View
180+
181+
An overview of the conceptual components in the OpenSSL to-be
182+
architecture is as shown in the (pink nirvana) diagram below.
183+
184+
Note: the existence of a component in the diagram does not indicate that
185+
the component is a public API or intended for end-user direct access or
186+
usage.
187+
188+
![](images/ToBeComponent.png)
189+
190+
The components shown here are as follows:
191+
192+
- Applications: Command line applications, e.g. ca, ciphers, cms, dgst
193+
etc
194+
195+
- Protocols: Provides capabilities for communicating between endpoints
196+
according to standard protocols
197+
198+
- TLS Protocols: An implementation of all supported TLS/DTLS
199+
protocols and supporting infrastructure such as:
200+
- SSL BIO: A BIO for communication using TLS
201+
- Statem: The TLS state machine
202+
- Record: The TLS record layer
203+
- Other Protocols
204+
- CMS: An implementation of the Cryptographic Message Syntax
205+
standard
206+
- OCSP: An implementation of Online Certificate Status
207+
Protocol
208+
- TS: An implementation of the Timestamp Protocol
209+
- Supporting Services: Components specifically designed to support
210+
the implementation of protocol code
211+
- Packet: Internal component for reading protocol messages
212+
- Wpacket: Internal component for writing protocol messages
213+
214+
- Core: This is a fundamental component that connects requests for a
215+
service (such as encryption) to a provider of that service. It
216+
implements the ability for providers to register their services
217+
along with the properties of those services. It also provides the
218+
ability to locate a service given a set of properties that the
219+
service must fulfil. For example, properties of an encryption
220+
service might include "aead", "aes-gcm", "fips",
221+
"security-bits=128", etc.
222+
223+
- Default Provider: Implements a set of default services that are
224+
registered with the Core.
225+
226+
- Supporting Services
227+
- Low Level Implementations: This is the set of components
228+
that actually implement the cryptographic primitives.
229+
230+
- FIPS Provider: Implements a set of services that are FIPS validated
231+
and made available to the Core. This includes the following
232+
supporting services:
233+
234+
- POST: Power On Self Test
235+
- KAT: Known Answer Tests
236+
- Integrity Check
237+
- Low Level Implementations: This is the set of components that
238+
actually implement the cryptographic primitives (to meet the
239+
FIPS-mandated self-contained requirement).
240+
241+
- Legacy Provider: Provides implementations of older algorithms that
242+
will be exposed via EVP-level APIs.
243+
244+
- Third-Party Provider: Not part of the OpenSSL distribution. Third
245+
Parties may implement their own providers.
246+
247+
- Common Services: these form the building blocks usable by
248+
applications and providers. (e.g. BIO, X509, SECMEM, ASN1, etc).
249+
250+
- Legacy APIs. The "low-level" APIs. The "legacy" here refers to the
251+
API, not the algorithm itself. For example, AES is not a legacy
252+
algorithm but it has a legacy API (e.g. AES\_encrypt).
253+
254+
### Packaging View
255+
256+
The various components described in the conceptual component view above
257+
are physically packaged into:
258+
259+
- Executable application(s) for use by users
260+
261+
- Libraries for use by application(s)
262+
263+
- Dynamically loadable module(s) for use by the Core.
264+
265+
![](images/ToBePackaging.png)
266+
267+
The physical packages shown here are:
268+
269+
- Openssl executable. The command line application.
270+
271+
- Libssl. This contains everything directly related to TLS and DTLS.
272+
Its contents will be largely the same as libssl in the as-is
273+
architecture. Note that some supporting services will be moved to
274+
libcrypto.
275+
276+
- Libcrypto. This library contains the following components:
277+
278+
- Implementations of the core services such as: X509, ASN1, EVP,
279+
OSSL\_STORE etc
280+
- The Core
281+
- Protocols not related to TLS or DTLS
282+
- Protocol supporting services (e.g. Packet and Wpacket)
283+
- The default provider containing implementations of all the
284+
default algorithms
285+
286+
- Libcrypto-legacy. Provides the legacy "low-level" APIs.
287+
Implementations of the algorithms for these APIS may come from any
288+
provider.
289+
290+
- FIPS module. This contains the FIPS Provider that implements a set
291+
of services that are FIPS validated and are registered with the
292+
Core.
293+
294+
- Legacy module. This contains the legacy provider.

0 commit comments

Comments
 (0)