chore: fix typos (#1236)

docs/hydra/security-architecture.md

@@ -3,18 +3,17 @@ id: security-architecture
 title: Security architecture
 ---
 
-Hydra is built with tough security in mind.
+Ory Hydra is built with tough security in mind.
 
 ## OAuth 2.0 security overview
 
-Hydra is an implementation of the security-first Fosite OAuth 2.0 SDK
-([https://github.com/ory/fosite](https://github.com/ory/fosite)). Fosite respects the
-[OAuth 2.0 Threat Model and Security Considerations](https://tools.ietf.org/html/rfc6819) by the IETF, specifically:
+Ory Hydra is an implementation of the security-first [Ory Fosite OAuth 2.0 SDK](https://github.com/ory/fosite). Ory Fosite
+respects the [OAuth 2.0 Threat Model and Security Considerations](https://tools.ietf.org/html/rfc6819) by the IETF, specifically:
 
 - No Cleartext Storage of Credentials
 - Encryption of Credentials
 - Use Short Expiration Time
-- Limit Number of Usages or One-Time Usage
+- Limit the Number of Usages or One-Time Usage
 - Bind Token to Client id
 - Automatic Revocation of Derived Tokens If Abuse Is Detected
 - Binding of Refresh Token to "client_id"
@@ -29,19 +28,19 @@ Hydra is an implementation of the security-first Fosite OAuth 2.0 SDK
 - Use of Asymmetric Cryptography
 - Enforcing random states: Without a random-looking state or OpenID Connect nonce the request will fail.
 
-Additionally these safeguards are implemented:
+Additionally, these safeguards are implemented:
 
 - Advanced Token Validation: Tokens are laid out as <key>.<signature> where <signature> is created using
   HMAC-SHA256 using a global secret.
 
 ### Advanced token validation (datastore security)
 
-For a OAuth2 access token, refresh token or authorize code to be valid, one requires both the key and the signature (formatted as
-<key>.<signature>). Only the signature is stored in the datastore (SQL), thus a compromised datastore won't allow an
+For an OAuth2 access token, refresh token or authorize code to be valid, one requires both the key and the signature (formatted as
+<key>.<signature>). Only the signature is stored in the data store (SQL), thus a compromised datastore won't allow an
 attacker to gain access to any valid authorize codes, access tokens, or refresh tokens.
 
-Because HMAC-SHA256 is used, the System Secret is required to create valid key-signature pairs, rendering an attacker unable to
-inject new codes or tokens into a compromised datastore.
+Because HMAC-SHA256 is used, the System Secret is required to create valid key signature pairs, rendering an attacker unable to
+inject new codes or tokens into a compromised data store.
 
 ## Token Prefixes
 
@@ -56,54 +55,54 @@ JSON Web Tokens. Adding prefixes to JSON Web Tokens would invalidate the JSON We
 
 ## Cryptography
 
-Hydra uses different cryptographic methods, this is an overview of all of them.
+Ory Hydra uses different cryptographic methods, and this is an overview of all of them.
 
 ### AES-GCM
 
 AES-GCM is used to encrypt JWKs at rest using a key size of 256 bit which exceeds requirements by Lenstra, ECRYPT II, NIST, ANSSI,
 and BSI, see [https://www.keylength.com/en/compare/](https://www.keylength.com/en/compare/).
 
 GCM (Galois/Counter Mode) is an authenticated encryption algorithm designed to provide both data authenticity (integrity) and
-confidentiality. GCM uses a nonce (“IV”) that has an upper limit of 2^32 nonces. If more nonces are used, there is risk of
+confidentiality. GCM uses a nonce (“IV”) that has an upper limit of 2^32 nonces. If more nonces are used, there is a risk of
 repeats. This means that you risk collisions when storing more than 2^32 documents authenticated with GCM. Because AES-GCM is only
-used to encrypt data at rest, this is might only impose a problem if
+used to encrypt data at rest, this might only impose a problem if
 
 1. more than 2^32 documents are stored using AES-GCM
 2. an attacker gains access to the datastore where > 2^32 documents are stored
-3. the attacker is able to exploit repeats, for example by authenticating malicious documents
+3. the attacker can exploit repeats, for example by authenticating malicious documents
 
 ### RS256
 
 RSASSA-PKCS1-v1_5 using SHA-256 (RS256) is used to sign JWTs. Its use is recommended by the JWA specification, see
 [https://www.rfc-editor.org/rfc/rfc7518.txt](https://www.rfc-editor.org/rfc/rfc7518.txt)
 
-The RSA Key size is 4096 bit long, exceeding the minimum requirement of 2048 bit by
+The RSA Key size is 4096 bits long, exceeding the minimum requirement of 2048 bits by
 [https://www.rfc-editor.org/rfc/rfc7518.txt](https://www.rfc-editor.org/rfc/rfc7518.txt).
 
-Recommendations from NIST, ANSSI, IAD-NSA, BSI, Lenstra and others vary between 1300 and 2048 bit key lengths for asymmetric
+Recommendations from NIST, ANSSI, IAD-NSA, BSI, Lenstra, and others vary between 1300 and 2048-bit key lengths for asymmetric
 cryptography based on discrete logarithms (RSA). 4096 exceeds all recommendations for 2017 from all authorities, see
 [https://www.keylength.com/en/compare/](https://www.keylength.com/en/compare/).
 
 ### HMAC-SHA256
 
-HMAC (FIPS 198) with SHA256 (FIPS 180-4) is used to sign access tokens, authorize codes and refresh tokens. SHA-2 (with 256 bit)
+HMAC (FIPS 198) with SHA256 (FIPS 180-4) is used to sign access tokens, authorize codes, and refresh tokens. SHA-2 (with 256-bit)
 is encouraged by NIST, see [http://csrc.nist.gov/groups/ST/hash/policy.html](http://csrc.nist.gov/groups/ST/hash/policy.html)
 
 ### PBKDF2
 
 PBKDF2 is the default OAuth2 Client Secret hashing algorithm to strike a balance between security and performance. As most client
-secrets are auto-generated, using high hash costs is not useful. The password (OAuth2 Client Secret) is not user chosen and
+secrets are auto-generated, using high hash costs is not useful. The password (OAuth2 Client Secret) is not user-chosen and
 unlikely to be reused. As such, there is little point in using excessive hash costs to protect users. High hash costs in a system
 like Ory Hydra will cause high CPU costs from mostly automated traffic (OAuth2 Client interactions). It has also been a point of
-critizism from some who wish for better RPS on specific endpoints.
+criticism from some who wish for better RPS on specific endpoints.
 
 We suggest between 20.000 and 50.000 iterations for PBKDF2.
 
 ### BCrypt
 
 BCrypt can be used to hash client credentials at rest. It isn't officially recommended by NIST as it isn't based on hashing
 primitives such as SHA-2, but rather on Blowfish. However, BCrypt is much stronger than any other (salted) hashing method for
-passwords, has wide adoption and is an official golang/x library.
+passwords, has wide adoption, and is an official golang/x library.
 
 Be aware that BCrypt causes very high CPU loads, depending on the Workload Factor. We strongly advise reducing the number of
 requests that use Basic Authorization.