1 files changed, 79 insertions, 0 deletions
diff --git a/docs/pem.md b/docs/pem.md
new file mode 100644
index 0000000..4f4bca7
--- /dev/null
+++ b/docs/pem.md
@@ -0,0 +1,79 @@
+# PEM Decoder and Encoder
+
+Often times DER-encoded data is wrapped in PEM encoding. This allows the binary
+DER data to be identified and reliably sent over various communication channels.
+
+The `asn1crypto.pem` module includes three functions:
+
+ - `detect(byte_string)`
+ - `unarmor(pem_bytes, multiple=False)`
+ - `armor(type_name, der_bytes, headers=None)`
+
+## detect()
+
+The `detect()` function accepts a byte string and looks for a `BEGIN` block
+line. This is useful to determine in a byte string needs to be PEM-decoded
+before parsing.
+
+```python
+from asn1crypto import pem, x509
+
+with open('/path/to/cert', 'rb') as f:
+    der_bytes = f.read()
+    if pem.detect(der_bytes):
+        _, _, der_bytes = pem.unarmor(der_bytes)
+```
+
+## unarmor()
+
+The `unarmor()` function accepts a byte string and the flag to indicates if
+more than one PEM block may be contained in the byte string. The result is
+a three-element tuple.
+
+ - The first element is a unicode string of the type of PEM block. Examples
+   include: `CERTIFICATE`, `PRIVATE KEY`, `PUBLIC KEY`.
+ - The second element is a `dict` of PEM block headers. Headers are typically
+   only used by encrypted OpenSSL private keys, and are in the format
+   `Name: Value`.
+ - The third element is a byte string of the decoded block contents.
+
+```python
+from asn1crypto import pem, x509
+
+with open('/path/to/cert', 'rb') as f:
+    der_bytes = f.read()
+    if pem.detect(der_bytes):
+        type_name, headers, der_bytes = pem.unarmor(der_bytes)
+
+cert = x509.Certificate.load(der_bytes)
+```
+
+If the `multiple` keyword argument is set to `True`, a generator will be
+returned.
+
+```python
+from asn1crypto import pem, x509
+
+certs = []
+with open('/path/to/ca_certs', 'rb') as f:
+    for type_name, headers, der_bytes in pem.unarmor(f.read(), multiple=True):
+        certs.append(x509.Certificate.load(der_bytes))
+```
+
+## armor()
+
+The `armor()` function accepts three parameters: a unicode string of the block
+type name, a byte string to encode and an optional keyword argument `headers`,
+that should be a `dict` of headers to add after the `BEGIN` line. Headers are
+typically only used by encrypted OpenSSL private keys.
+
+```python
+from asn1crypto import pem, x509
+
+# cert is an instance of x509.Certificate
+
+with open('/path/to/cert', 'wb') as f:
+    der_bytes = cert.dump()
+    pem_bytes = pem.armor('CERTIFICATE', der_bytes)
+    f.write(pem_bytes)
+```