-The syntax of raw extensions is governed by the extension code: it can
-for example contain data in multiple sections. The correct syntax to
-use is defined by the extension code itself: check out the certificate
-policies extension for an example.
+If an extension is multi-value and a field value must contain a comma the long
+form must be used otherwise the comma would be misinterpreted as a field
+separator. For example:
+
+ subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+
+will produce an error but the equivalent form:
+
+ [extensions]
+ subjectAltName = @subject_alt_section
+
+ [subject_alt_section]
+ subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+
+is valid.
+
+OpenSSL does not support multiple occurences of the same field within a
+section. In this example:
+
+ [extensions]
+ subjectAltName = @alt_section
+
+ [alt_section]
+ email = steve@here
+ email = steve@there
+
+will only recognize the last value. To specify multiple values append a
+numeric identifier, as shown here:
+
+ [extensions]
+ subjectAltName = @alt_section
+
+ [alt_section]
+ email.1 = steve@here
+ email.2 = steve@there
+
+The syntax of raw extensions is defined by the source code that parses
+the extension but should be documened.
+See L</Certificate Policies> for an example of a raw extension.