comments

umad-02-keys-and-authentication.md

@@ -2,7 +2,7 @@
 
 ## Keys
 
-Before VASPs start sending and receiving UMA payments, they need to generate keys which are be used to authenticate
+Before VASPs start sending and receiving UMA payments, they need to generate keys which will be used to authenticate
 themselves to other VASPs and to receive and decrypt encrypted blobs for sensitive information (like payment and Travel
 Rule data).
 
@@ -25,48 +25,42 @@ section.
 
 ## Public Key Exchange
 
-TThe UMA protocol relies on X.509 certificates for public key exchange among VASPs. In order to obtain an X.509
-certificate, the VASP is required to submit a request to a trusted certificate authority (CA), which issues the
-certificate. The issuing CA must keep track of certificates that are revoked, and provide this information to other
+The UMA protocol relies on X.509 certificates for public key exchange among VASPs. If a VASP trusts the party that they
+wish to transact with, typically established through prior communication, self-signed certificates are a suitable
+solution for key exchange. VASPs can create self-signed certificates wrapping the public keys generated above using
+common tools such as `openssl`, and share these certificates with their counterparty. It is important to note that
+self-signed certificates don't provide a good revocation mechanism, so it is recommended to use a short caching
+duration (on the order of a few minutes) to minimize the risk of key compromise.
+
+In cases where VASPs don't recognize their counterparty's identity, it is recommended to use signed certificates
+issued by a trusted source, such as a VASP ID Authority or a Certificate Authority. When a VASP receives a signed
+certificate, they can check if an authority that they trust has signed the certificate, and hence, trust the underlying
+VASP. VASPs have the ability to invalidate their certificates in the case of key compromise or security-related key
+rotations. The issuing CA must keep track of certificates that are revoked, and provide this information to other
 parties via Certificate Revocation Lists (CRLs) or an Online Certificate Status Protocol (OCSP) server. The URLs for
-accessing a CA's CRL/OCSP can be found inside the certificate, and VASPs should ensure the validity of all of the
-certificates they receive to ensure compliance and security.
-
-It is not recommended for VASPs to use self-signed certificates when communicating with other VASPs outside their
-organization. They should only be used in test environments. To generate a self-signed X.509 certificate based on the
-key generated above, run:
-
-```bash
-# Generate a certificate based on the key we generated:
-$ openssl req -new -x509 -key ec_key.pem -sha256 -nodes -out ec_crt.crt -days <expiration in days>
-
-# Print out the certificate data:
-$ openssl x509 -in ec_crt.crt -noout -text
-```
+accessing a CA's CRL/OCSP can be found inside the certificate, and VASPs should periodically check the validity of the
+certificates they receive to ensure compliance and security. In the event that the counterparty's certificate is
+revoked, the VASP can request a new set of certificates and validate them. Optionally, the counterparty can specify an
+expiration timestamp at which the VASP is required to revalidate the certificates, in addition to periodic validation.
 
 VASPs expose their certificates to other VASPs by responding to `GET` requests at the endpoint
 `https://<vaspdomain>/.well-known/lnurlpubkey`. This endpoint returns a JSON object with the following structure:
 
 ```json
 {
-  // Used to verify signatures from VASP1. Base64-encoded X.509 certificate string.
+  // Used to verify signatures from VASP1. PEM-encoded X.509 certificate string.
   "signingCertificate": string,
-  // Used to encrypt TR info sent to VASP1. Base64-encoded X.509 certificate string.
+  // Used to encrypt TR info sent to VASP1. PEM-encoded X.509 certificate string.
   "encryptionCertificate": string,
   // [Optional] Sec since epoch at which these certificates must be revalidated or refreshed.
+  // If not specified, the certificates will not be cached.
   "expirationTimestamp": number
 }
 ```
 
-VASPs can revoke their certificates if their keys are compromised or if they want to rotate their keys for security
-reasons. For this reason, VASPs should periodically check certificates for revocation. In the event that the counter
-party's certificate is revoked, the VASP can request a new set of certificates at the same endpoint and validate them.
-Optionally, the counter party can specify an expiration timestamp at which the VASP is required to revalidate or
-refresh their certificates, outside of periodic validation.
-
 ## Authentication
 
-Some messages in the UMA protcol must be signed by the VASP who created the message using ECDSA and the secp256k1 keys
+Some messages in the UMA protocol must be signed by the VASP who created the message using ECDSA and the secp256k1 keys
 as described above. Signatures are created using a VASP's private signing key. The signature is then verified by the
 receiving VASP using the sending VASP's signing public key from the `signingCertificate`. The signature is included in
 the message itself, along with the sending VASP's domain if needed. The receiving VASP can then verify the signature