Merge pull request #27 from DirectProjectJavaRI/gh-pages-migration

Copyedit security and trust documentation

Author: gm2552

docs/agent-architecture.md

@@ -8,9 +8,9 @@ At a high level the agent can be viewed as a black box that implements the Direc
 
 ![highLevelArch](assets/highLevelArch.png)
 
-Each component within the agent functions independently whilst the agent orchestrates the business logic between the internal components.
+Each component within the agent functions independently while the agent orchestrates the business logic between the internal components.
 
-##### Core Components and Interfaces
+## Core Components and Interfaces
 
 * [NHINDAgent](nhind-agent): Interface specification for the security and trust agent. Incoming and outgoing messages are processed by the agent according to the DirectProject [specification](http://wiki.directproject.org/w/images/e/e6/Applicability_Statement_for_Secure_Health_Transport_v1.2.pdf). [JavaDoc](http://api.directproject.info/agent/2.2.1/apidocs/org/nhindirect/stagent/NHINDAgent.html)
 * [Cryptographer](cryptographer): Interface specification for message encryption/decryption and message signature operations. [JavaDoc](http://api.directproject.info/agent/2.2.1/apidocs/org/nhindirect/stagent/cryptography/Cryptographer.html)

docs/cert-gen.md

@@ -45,14 +45,14 @@ public interface Cryptographer
 }
 ```
 
-Although the cryptography classes do not enforce the content type of the messages provided to the each method, the security and trust agent uses the following series of cryptography tasks in order:
+Although the cryptography classes do not enforce the content type of the messages provided to each method, the security and trust agent uses the following series of cryptography tasks, in order:
 
 **Outgoing Messages**
 
 1. Sign Message
 2. Encrypt Message
 
-**Incoming Message**
+**Incoming Messages**
 
 1. Decrypt Message
 2. Validate Signature
@@ -61,37 +61,37 @@ Although the cryptography classes do not enforce the content type of the message
 
 ## Encrypt
 
-The Encrypt method and its variants accept a message that needs to be encrypted and the public certificate of each recipient. The methods generates a random symmetric key to encrypt the message based on the implementation's configured encryption algorithm such as AES128. The message is encrypted using the symmetric key, and the key is then encrypted using each public certificate. Each encrypted version of the symmetric key is stored in the final message and can only be decrypted be the recipients' private key.
+The Encrypt method and its variants accept a message that needs to be encrypted and the public certificate of each recipient. The method generates a random symmetric key to encrypt the message based on the implementation's configured encryption algorithm, such as AES128. The message is encrypted using the symmetric key, and the key is then encrypted using each public certificate. Each encrypted version of the symmetric key is stored in the final message and can only be decrypted by the corresponding recipient's private key.
 
-All variants result in the same output: an MimeEntity that contains an SMIME encrypted version of the original message. The raw representation is base64 encoded.
+All variants result in the same output: a MimeEntity that contains an SMIME-encrypted version of the original message. The raw representation is base64 encoded.
 
 ## Decrypt
 
-The Decrypt method and its variants accept a message that needs to be decrypted and the private certificate of reach recipient. The message must be a valid encrypted message using the cryptographer's expected format such as SMIME. This method uses the recipients' private keys to extract the symmetric key from the message. Only one valid private key needs to be found in the collection of certificates to extract the symmetric key. Once the symmetric key is extracted, the message content is then decrypted using the algorithm specified in the message.
+The Decrypt method and its variants accept a message that needs to be decrypted and the private certificate of each recipient. The message must be a valid encrypted message using the cryptographer's expected format, such as SMIME. This method uses the recipients' private keys to extract the symmetric key from the message. Only one valid private key needs to be found in the collection of certificates to extract the symmetric key. Once the symmetric key is extracted, the message content is decrypted using the algorithm specified in the message.
 
-All variants result in the same output: an MimeEntity that contains the decrypted version of the original message.
+All variants result in the same output: a MimeEntity that contains the decrypted version of the original message.
 
 ## Sign
 
-The Sign method and its variants accept a message that needs to be signed and private certificate(s) of the sender. The methods generates a digest of the message based on the implementation's configured digest algorithm such as SHA256. The message also provides other attributes such as the signers public key(s) and produces a digital signature using the provided private key.
+The Sign method and its variants accept a message that needs to be signed and the private certificate(s) of the sender. The method generates a digest of the message based on the implementation's configured digest algorithm, such as SHA256. It also uses other attributes, such as the signer's public key(s), to produce a digital signature using the provided private key.
 
-All variants result in the same output: an SignedEntity object that contains the original message and a signature block. The raw representation of the or the SignedEnity is a multipart MIME that contains two parts: the original message in the first part and a detached signature in the second part. The signature block is base64 encoded.
+All variants result in the same output: a SignedEntity object that contains the original message and a signature block. The raw representation of the SignedEntity is a multipart MIME that contains two parts: the original message in the first part and a detached signature in the second part. The signature block is base64 encoded.
 
 ## CheckSignature
 
-The CheckSignature method asserts the validity and integrity of a signed message using the sender's public certificate. The method validates that the signature in the messages signature block matches the provided public certificate and validates that the message has not been tampered with using the message digest. 
+The CheckSignature method asserts the validity and integrity of a signed message using the sender's public certificate. The method validates that the signature in the message's signature block matches the provided public certificate and validates that the message has not been tampered with, using the message digest.
 
-This method returns without incident if the signature can be validated. Otherwise an exception is thrown.
+This method returns without incident if the signature can be validated. Otherwise, an exception is thrown.
 
-**NOTE:** The default agent implementation does not use this method. Instead it uses the MessageSignature interface to validate signatures on incoming messages during the trust validation stage.
+**NOTE:** The default agent implementation does not use this method. Instead, it uses the MessageSignature interface to validate signatures on incoming messages during the trust validation stage.
 
 ## DeserializeSignatureEnvelope
 
-The DeserializeSignatureEnvelope method and its variants are utility functions to extract the CMS data embedded in the message signature block. The latest version of CMS is decribed by [RFC5652](http://tools.ietf.org/html/rfc5652)
+The DeserializeSignatureEnvelope method and its variants are utility functions for extracting the CMS data embedded in the message signature block. The latest version of CMS is described by [RFC5652](http://tools.ietf.org/html/rfc5652).
 
 ## SMIMECryptographerImpl
 
-The SMIMECryptographerImpl is an SMIME specific implementation of the Cryptographer interface. Internal algorithms use the SMIME specification to generate encrypted and signed message representation. It includes multiple constructors depending on the consumer's needs. 
+The SMIMECryptographerImpl is an SMIME-specific implementation of the Cryptographer interface. Its internal algorithms use the SMIME specification to generate encrypted and signed message representations. It includes multiple constructors depending on the consumer's needs.
 
 The class provides multiple constructors for various needs:
 
@@ -113,17 +113,17 @@ The following are the default values for each variable:
 
 **Strong Cryptographic Algorithms Enforcement**
 
-Version 1.2 of applicability statement removed allowance of SHA-1 as a digest algorithm for outgoing messages, however, for backward compatibility it allows for receiving messages that use lesser strength digests. Similar statements can be made for encryption algorithms, however no change has been made in version 1.2 on the strength of allowed encryption algorithms (AES128 is still the minimum allowed for sending).
+Version 1.2 of the applicability statement removed the allowance of SHA-1 as a digest algorithm for outgoing messages; however, for backward compatibility, it allows for receiving messages that use lesser-strength digests. A similar statement can be made for encryption algorithms; however, no change has been made in version 1.2 to the strength of allowed encryption algorithms (AES128 is still the minimum allowed for sending).
 
-For institutional or policy reasons, agent implementors may which to choose to enforce receiving messages only from other systems that comply with the higher strength cryptographic algorithms. This policy can be set using the *ENFORCESTRONGDIGESTS* and *ENFORCESTRONGENCRYPTION* options parameters. For behavioral passivity reasons, these policies are set to false by default.
+For institutional or policy reasons, agent implementors may choose to enforce receiving messages only from other systems that comply with the higher-strength cryptographic algorithms. This policy can be set using the *ENFORCESTRONGDIGESTS* and *ENFORCESTRONGENCRYPTION* options parameters. For backward behavioral compatibility, these policies are set to false by default.
 
 ## PKCS11 Token Support
 
-Some institutional and agency policies require a high level of protection of sensitive cryptographic material, specifically asymmetric private keys. A common protection method is to use a PCKS11 token such as a hardware security module (HSM) where the private key is loaded into the token and the cryptographic operations that utilize the key are performed on the token instead of in the agent's process memory. The method for loading keys into the token are arbitrary, but generally policies do not allow the private keys to be exposed in a non-encrypted format when not present in the token. Once loaded into the token and "activated", the private key is only accessible to the token meaning that cryptographic operations MUST be performed on the token.
+Some institutional and agency policies require a high level of protection for sensitive cryptographic material, specifically asymmetric private keys. A common protection method is to use a PKCS11 token, such as a hardware security module (HSM), where the private key is loaded into the token and the cryptographic operations that utilize the key are performed on the token instead of in the agent's process memory. The method for loading keys into the token is arbitrary, but generally, policies do not allow the private keys to be exposed in an unencrypted format when not present in the token. Once loaded into the token and "activated," the private key is only accessible to the token, meaning that cryptographic operations MUST be performed on the token.
 
-Using PKCS11 tokens for cryptographic operations is supported by the agent, however it has the ability to optimize the process. What does this mean? Both SMIME message decryption and signing use a two phase process where cryptographic operations are performed in both phases. For message signing, the first phase consists of computing a message digest and the second phase digitally signs the digest using the sender's asymmetric private key. For message decryption, the first phase uses the recipeint's asymmetric private key to decrypt a symmetric secret key and this symmetric key is then used to decrypt the entire message in the second phase. In both scenarios the private key phase only operates on a small piece of information where as the other phase acts on the entire message. Because the small operations are the only ones that utilize the protect asymmetric private key, they are the only ones that really need to performed on the token. Performing potentially large digest and message decryption operations on the the token can quickly lead to performance bottlenecks especially in deployments where the token is configured as a network appliance.
+The agent supports using PKCS11 tokens for cryptographic operations, and it has the ability to optimize the process. What does this mean? Both SMIME message decryption and signing use a two-phase process, where cryptographic operations are performed in both phases. For message signing, the first phase consists of computing a message digest, and the second phase digitally signs the digest using the sender's asymmetric private key. For message decryption, the first phase uses the recipient's asymmetric private key to decrypt a symmetric secret key, and this symmetric key is then used to decrypt the entire message in the second phase. In both scenarios, the private-key phase only operates on a small piece of information, whereas the other phase acts on the entire message. Because the small operations are the only ones that utilize the protected asymmetric private key, they are the only ones that really need to be performed on the token. Performing potentially large digest and message decryption operations on the token can quickly lead to performance bottlenecks, especially in deployments where the token is configured as a network appliance.
 
-In Java, cryptographic operations are performed by JCE provider implementations, and these providers are configurable using various methods keyed by a provider name. PKCS11 tokens are mapped to JCE providers via the provider name, and routing cryptographic operations to a token is done by specifying the mapped JCE provider name to the appropriate cryptographic API call. The BouncyCastle libraries, utilized by the SMIMECryptographerImpl class, only allow for signing and decryption operations to be routed to a single JCE provider. Because SMIME signing and decryption is actually a two phase process, a different JCE provider could be used in each phase.
+In Java, cryptographic operations are performed by JCE provider implementations, and these providers are configurable using various methods keyed by a provider name. PKCS11 tokens are mapped to JCE providers via the provider name, and routing cryptographic operations to a token is done by specifying the mapped JCE provider name in the appropriate cryptographic API call. The BouncyCastle libraries, utilized by the SMIMECryptographerImpl class, only allow signing and decryption operations to be routed to a single JCE provider. Because SMIME signing and decryption is actually a two-phase process, a different JCE provider could be used in each phase.
 
 **Concurrent Programming**
 

docs/cert-resolver.md

@@ -4,11 +4,11 @@ title: DNS Certificate Dumper
 
 # DNS Certificate Dumper
 
-The reference implementation source tree provides a tool retrieving user and organizational certificates by email address or domain over DNS and writing the certificate to a DER encoded file. The tool is located under the agent/tools directory in the source tree and is named dnsCertDumper.sh for unix/linux based systems and dnsCertDumper.bat for Windows.
+The reference implementation source tree provides a tool for retrieving user and organizational certificates by email address or domain over DNS and writing the certificate to a DER-encoded file. The tool is located under the agent/tools directory in the source tree and is named dnsCertDumper.sh for Unix/Linux-based systems and dnsCertDumper.bat for Windows.
 
 ## DNS Certificate Resolution
 
-The Direct Project defines a method for resolving public certificates using DNS CERT RR records. In some cases, it may be desirable to manually download a public certificate using DNS and dump it to a file. The dnsCertDumper tool uses the DNSCertificateResolver to locate certificates using an email address or a domain name. Certificates are located using the resolution algorithms defined by the Direct Project meaning the resolver will look for user level certificates first then fall back to searching for organizational certificates if a user level certificate can not be found.
+The Direct Project defines a method for resolving public certificates using DNS CERT RR records. In some cases, it may be desirable to manually download a public certificate using DNS and dump it to a file. The dnsCertDumper tool uses the DNSCertificateResolver to locate certificates using an email address or a domain name. Certificates are located using the resolution algorithms defined by the Direct Project, meaning the resolver will look for user-level certificates first, then fall back to searching for organizational certificates if a user-level certificate cannot be found.
 
 ### dnsCertDumper
 
@@ -26,7 +26,7 @@ Unix/Linux/MAC
 ./dnsCertDumper.sh
 ```
 
-Running the tools without and parameters will display the options:
+Running the tool without any parameters will display the options:
 
 ```
 Usage:
@@ -42,8 +42,8 @@ options:
 			Default: <email address>(<cert num>).der
 ```
 
-* **Address:** This is the email address associated to the certificate that you are search for. This can also be a domain name if you are searching for an org level certificate only.
-* **Server:** If the server parameter is supplied, the underlying DNS resolver will use the supplied DNS server instead of the local machine's configured DNS server. This may be desirable if you are experiencing difficulties with your DNS provier.
-* **Out:** The name of the file that will be generated. By default the tool uses the email or domain name followed by the .der extension. In some cases multiple certificates may be discovered. In this case The tool will append a incrementing number starting with 1 enclosed in parenthesis to the out file name.
+* **Address:** This is the email address associated with the certificate you are searching for. This can also be a domain name if you are searching for an org-level certificate only.
+* **Server:** If the server parameter is supplied, the underlying DNS resolver will use the supplied DNS server instead of the local machine's configured DNS server. This may be desirable if you are experiencing difficulties with your DNS provider.
+* **Out:** The name of the file that will be generated. By default, the tool uses the email or domain name followed by the .der extension. In some cases, multiple certificates may be discovered; in this case, the tool will append an incrementing number, starting with 1, enclosed in parentheses to the out file name.
 
-If one or more certificates are discovered, the files are written to DER encoded files. If a file with the same name as the out file already exists, the tool will over write the file with a new file.
+If one or more certificates are discovered, the files are written as DER-encoded files. If a file with the same name as the out file already exists, the tool will overwrite it.