jonathanwilbur / pem-ts

TypeScript Privacy Enhanced Mail (PEM) file library for web or NodeJS

PEM TypeScript Library

• Author: Jonathan M. Wilbur <[email protected]>
• Copyright Year: 2019
• License: MIT License

Building

You can build this library by running npm run build.

The outputs will all be in dist.

• ./dist/pem.min.js is the entire PEM library for the web browser, which is minified.
• ./dist/index.js is the entire NodeJS library.

Library Usage

Decoding PEM Files

There are two methods in the PEMObject that are used for decoding PEM objects. The first, decode(), only decodes a single PEM object, which must start with the pre-encapsulation header and end with a post-encapsulation header. (Whitespace is trimmed, so it is fine if you have a trailing newline.)

const text : string =
`-----BEGIN CERTIFICATE-----
MIICUTCCAfugAwIBAgIBADANBgkqhkiG9w0BAQQFADBXMQswCQYDVQQGEwJDTjEL
MAkGA1UECBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMC
VU4xFDASBgNVBAMTC0hlcm9uZyBZYW5nMB4XDTA1MDcxNTIxMTk0N1oXDTA1MDgx
NDIxMTk0N1owVzELMAkGA1UEBhMCQ04xCzAJBgNVBAgTAlBOMQswCQYDVQQHEwJD
TjELMAkGA1UEChMCT04xCzAJBgNVBAsTAlVOMRQwEgYDVQQDEwtIZXJvbmcgWWFu
ZzBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQCp5hnG7ogBhtlynpOS21cBewKE/B7j
V14qeyslnr26xZUsSVko36ZnhiaO/zbMOoRcKK9vEcgMtcLFuQTWDl3RAgMBAAGj
gbEwga4wHQYDVR0OBBYEFFXI70krXeQDxZgbaCQoR4jUDncEMH8GA1UdIwR4MHaA
FFXI70krXeQDxZgbaCQoR4jUDncEoVukWTBXMQswCQYDVQQGEwJDTjELMAkGA1UE
CBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMCVU4xFDAS
BgNVBAMTC0hlcm9uZyBZYW5nggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEE
BQADQQA/ugzBrjjK9jcWnDVfGHlk3icNRq0oV7Ri32z/+HQX67aRfgZu7KWdI+Ju
Wm7DCfrPNGVwFWUQOmsPue9rZBgO
-----END CERTIFICATE-----`;
const pem : PEMObject = new PEMObject();
pem.decode(text);
console.log(pem.label === "CERTIFICATE"); // logs "true"
console.log(pem.data); // logs the Uint8Array of bytes decoded from the base-64 data

The second, parse(), is a static method that retrieves and decodes all of the PEM objects from a file. This is usually what you should use to decode PEM data, as it complies strictly to RFC 7468. This is important, because PEM files can contain explanatory text and/or whitespace before, between, or after objects.

const text : string =
`---OOSH, you thought this was a line? try again, bub.
-----BEGIN CERTIFICATE-----


MIICUTCCAfugAwIBAgIBADANBgkqhkiG9w0BAQQFADBXMQswCQYDVQQGEwJDTjEL
MAkGA1UECB
MCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMC
VU4xFDASBgNVBAMTC0hlcm9uZyBZYW5nMB4XDTA1MDcxNTIxMTk0N1oXDTA1MDgx
NDIxMTk0N1owVzELMAkGA1UEBhMCQ04xCzAJBgNVBAgTAlBOMQswCQYDVQQHEwJD
TjELMAkGA1UEChMCT04xCzAJBgNVBAsTAlVOMRQwEgYDVQQDEwtIZXJvbmcgWWFu
ZzBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQCp5hnG7ogBhtlynpOS21cBewKE/B7j
V14qeyslnr26xZUsSVko36ZnhiaO/zbMOoRcKK9vEcgMtcLFuQTWDl3RAgMBAAGj
gbEwga4wHQYDVR0OBBYEFFXI70krXeQDxZ
gbaCQoR4jUDncEMH8GA1UdIwR4MHaA
FFXI70krXeQDxZgbaCQoR4jUDncEoVukWTBXMQswCQYDVQQGEwJDTjELMAkGA1UE
CBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMCVU4xFDAS
BgNVBAMTC0hlcm9uZyBZYW5nggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEE
BQADQQA/ugzBrjjK9jcWnDVfGHlk3icNRq0oV7Ri32z/+HQX67aRfgZu7KWdI+Ju
Wm7DCfrPNGVwFWUQOmsPue9rZBgO
-----END CERTIFICATE-----
Explanatory text
-----BEGIN CERTIFICATE-----

MIICUTCCAfugAwIBAgIBADANBgkqhkiG9w0BAQQFADBXMQswCQYDVQQGEwJDTjEL
MAkGA1UECBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMC
VU4xFDASBgNVBAMTC0hlcm9uZyBZ
YW5nMB4XDTA1MDcxNTIxMTk0N1oXDTA1MDgx
NDIxMTk0N1owVzELMAkGA1UEBhMCQ04xCzAJBgNVBAgTAlBOMQswCQYDVQQHEwJD
TjELMAkGA1UEChMCT04xCzAJBgNVBAsTAlVOMRQwEgYDVQQDEwtIZXJvbmcgWWFu
ZzBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQCp5hnG7ogBhtlynpOS21cBewKE/B7j
V14qeyslnr26xZUsSVko36ZnhiaO/zbMOoRcKK9vEcgMtcLFuQTWDl3RAgMBAAGj
gbEwga4wHQYDVR0OBBYEFFXI70krXeQDxZgbaCQoR4jUDncEMH8GA1UdIwR4MHaA
FFXI70krXeQDxZgbaCQoR4jUDncEoVukWTBXMQswCQYDVQQGEwJDTjELMAkGA1UE
CBMCUE4xCzAJBgNVBAcTA
kNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMCVU4xFDAS
BgNVBAMTC0hlcm9uZyBZYW5nggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEE
BQADQQA/ugzBrjjK9jcWnDVfGHlk3icNRq0oV7Ri32z/+HQX67aRfgZu7KWdI+Ju
Wm7DCfrPNGVwFWUQOmsPue9rZBgO
-----END CERTIFICATE-----

 GOTTA GO FASTT

`;
const pems : PEMObject[] = PEMObject.parse(text);
console.log(pems[0].label === "CERTIFICATE"); // logs "true"
console.log(pems[1].label === "CERTIFICATE"); // logs "true"
console.log(pems[0].data); // logs the Uint8Array of bytes decoded from the base-64 data

Encoding (Creating) PEM Files

Creating PEM files is simple: set the label, set the data, and access the encoded property, like so:

const pem : PEMObject = new PEMObject();
pem.label = "CERTIFICATE";
pem.data = new Uint8Array([ 0xFF, 0x00, 0xFF, 0x00 ]);
console.log(pem.encoded); // Logs the PEM encoded object

Validating PEM Files

You can validate PEM object labels like so:

const pem : PEMObject = new PEMObject();
pem.label = "CERTIFICATE";
console.log(pem.hasRFC7468CompliantLabel); // Logs "true"
pem.label = "BLORPIFICATE";
console.log(pem.hasRFC7468CompliantLabel); // Logs "false"

Hacking PEM Files

I don't know why you would want to do this, but every part of the PEM file is accessible as an accessor, like so:

const pem : PEMObject = new PEMObject();
pem.label = "CERTIFICATE";
pem.data = new Uint8Array([ 0xFF, 0x00, 0xFF, 0x00 ]);
console.log(pem.label); // Logs "CERTIFICATE"
console.log(pem.preEncapsulationBoundary); // Logs "-----BEGIN CERTIFICATE-----"
console.log(pem.postEncapsulationBoundary); // Logs "-----END CERTIFICATE-----"
console.log(pem.encapsulatedTextPortion); // Logs the base-64 encoding of pem.data

See Also

• RFC 7468

pem-ts's Issues

Trailing zeroes in decoded data

The dependency for decoding Base64, base64-ts, leaves trailing zeroes in decoded data. See this issue.

named capture groups not supported

Named capture groups not supported in the environment I need to work against.

Would you accept a PR to remove them?

Version issue

In the following commit, there is a major version bump of typescript. So, can you please revert this and publish a major version.
313efce

Fails to decode Base64 that does not have padding

The dependency for decoding Base64, base64-ts, fails to decode Base64 that does not have padding. See this issue.

Incorrectly decodes Base64

This certificate

-----BEGIN CERTIFICATE-----
MIICpDCCAYwCCQCRLR/T6ysqMjANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDDAlU
ZXN0IFVzZXIwHhcNMTgxMDI5MDI1ODQ3WhcNMTgxMTI4MDI1ODQ3WjAUMRIwEAYD
VQQDDAlUZXN0IFVzZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDI
tsiz3kSXTjDXJsQ2hadj5v3duAo0cRkY9xhd4rxUsKUIEMYAgBYB7YHEATiw0HWP
rBNRt+OMZL1eXK0hiX/S5o/WPXXm1jHfjxyqfa9xX1Jb4+X6+n8AqRffyaEAxryO
aM5ebd0HurjfAHHv6x8qW78UwLef4E9+XWPiqZc6fZB0wi3wjtHw8wU+NJ9RduVf
utQzqaANXlCaexFLfQEGLnimnHMwp3j12h4H+l4HYtgS8p9XgioeaLuVRtCo9zTX
nJdWF8N1p4aBLPlB6vV8F09+WIk9uHSi7UDyDGky0pv4O7lSAsd/CTY0++NGenxj
z3GbEqFTnS6wCap66zcVAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAMQkGilUl3Hm
Uw3eyM2xg/WWFKjTgZXDTyVZHq8M9u4PAh01TyouH22waQ387ox/ZaWnCAXihsWQ
jT07bB36ziuP6SHQdZ4EEkX6mIo2h6CIegSlRgtWlSgkCUDd+tPVlVIp3HjaJ7vW
XyTcORGV5vSODdYv8gBJBYUf9S7+9FFrDcMH8INC5Rfr7cbzue3INGCRCTT9vBe/
OFn9Yf87yYU8j2sj8bi8wdhsFd/rHXGu4sSNLhE1V7lFto43mE2pQtmItJesVDaf
Nr5Du1sYWW0YATPjbIX3samRK72HNFYD0wpJKnYB2m3vwzPxcm4Is6cWXjpfUz8D
SKM5ntuAPlI=
-----END CERTIFICATE-----

decodes to these bytes

30 c2 82 02 c2 a4 30 c2 82 01 c2 8c 02 09 00 c2 91 2d 1f c3 93 c3 ab 2b 2a 32 30 0d 06 09 2a c2 86 48 c2 86 c3 b7 0d 01 01 0b 05 00 30 14 31 12 30 10 06 03 55 04 03 0c 09 54 65 73 74 20 55 73 65 72 30 1e 17 0d 31 38 31 30 32 39 30 32 35 38 34 37 5a 17 0d 31 38 31 31 32 38 30 32 35 38 34 37 5a 30 14 31 12 30 10 06 03 55 04 03 0c 09 54 65 73 74 20 55 73 65 72 30 c2 82 01 22 30 0d 06 09 2a c2 86 48 c2 86 c3 b7 0d 01 01 01 05 00 03 c2 82 01 0f 00 30 c2 82 01 0a 02 c2 82 01 01 00 c3 88 c2 b6 c3 88 c2 b3 c3 9e 44 c2 97 4e 30 c3 97 26 c3 84 36 c2 85 c2 a7 63 c3 a6 c3 bd c3 9d c2 b8 0a 34 71 19 18 c3 b7 18 5d c3 a2 c2 bc 54 c2 b0 c2 a5 08 10 c3 86 00 c2 80 16 01 c3 ad c2 81 c3 84 01 38 c2 b0 c3 90 75 c2 8f c2 ac 13 51 c2 b7 c3 a3 c2 8c 64 c2 bd 5e 5c c2 ad 21 c2 89 7f c3 92 c3 a6 c2 8f c3 96 3d 75 c3 a6 c3 96 31 c3 9f c2 8f 1c c2 aa 7d c2 af 71 5f 52 5b c3 a3 c3 a5 c3 ba c3 ba 7f 00 c2 a9 17 c3 9f c3 89 c2 a1 00 c3 86 c2 bc c2 8e 68 c3 8e 5e 6d c3 9d 07 c2 ba c2 b8 c3 9f 00 71 c3 af c3 ab 1f 2a 5b c2 bf 14 c3 80 c2 b7 c2 9f c3 a0 4f 7e 5d 63 c3 a2 c2 a9 c2 97 3a 7d c2 90 74 c3 82 2d c3 b0 c2 8e c3 91 c3 b0 c3 b3 05 3e 34 c2 9f 51 76 c3 a5 5f c2 ba c3 94 33 c2 a9 c2 a0 0d 5e 50 c2 9a 7b 11 4b 7d 01 06 2e 78 c2 a6 c2 9c 73 30 c2 a7 78 c3 b5 c3 9a 1e 07 c3 ba 5e 07 62 c3 98 12 c3 b2 c2 9f 57 c2 82 2a 1e 68 c2 bb c2 95 46 c3 90 c2 a8 c3 b7 34 c3 97 c2 9c c2 97 56 17 c3 83 75 c2 a7 c2 86 c2 81 2c c3 b9 41 c3 aa c3 b5 7c 17 4f 7e 58 c2 89 3d c2 b8 74 c2 a2 c3 ad 40 c3 b2 0c 69 32 c3 92 c2 9b c3 b8 3b c2 b9 52 02 c3 87 7f 09 36 34 c3 bb c3 a3 46 7a 7c 63 c3 8f 71 c2 9b 12 c2 a1 53 c2 9d 2e c2 b0 09 c2 aa 7a c3 ab 37 15 02 03 01 00 01 30 0d 06 09 2a c2 86 48 c2 86 c3 b7 0d 01 01 0b 05 00 03 c2 82 01 01 00 c3 84 24 1a 29 54 c2 97 71 c3 a6 53 0d c3 9e c3 88 c3 8d c2 b1 c2 83 c3 b5 c2 96 14 c2 a8 c3 93 c2 81 c2 95 c3 83 4f 25 59 1e c2 af 0c c3 b6 c3 ae 0f 02 1d 35 4f 2a 2e 1f 6d c2 b0 69 0d c3 bc c3 ae c2 8c 7f 65 c2 a5 c2 a7 08 05 c3 a2 c2 86 c3 85 c2 90 c2 8d 3d 3b 6c 1d c3 ba c3 8e 2b c2 8f c3 a9 21 c3 90 75 c2 9e 04 12 45 c3 ba c2 98 c2 8a 36 c2 87 c2 a0 c2 88 7a 04 c2 a5 46 0b 56 c2 95 28 24 09 40 c3 9d c3 ba c3 93 c3 95 c2 95 52 29 c3 9c 78 c3 9a 27 c2 bb c3 96 5f 24 c3 9c 39 11 c2 95 c3 a6 c3 b4 c2 8e 0d c3 96 2f c3 b2 00 49 05 c2 85 1f c3 b5 2e c3 be c3 b4 51 6b 0d c3 83 07 c3 b0 c2 83 42 c3 a5 17 c3 ab c3 ad c3 86 c3 b3 c2 b9 c3 ad c3 88 34 60 c2 91 09 34 c3 bd c2 bc 17 c2 bf 38 59 c3 bd 61 c3 bf 3b c3 89 c2 85 3c c2 8f 6b 23 c3 b1 c2 b8 c2 bc c3 81 c3 98 6c 15 c3 9f c3 ab 1d 71 c2 ae c3 a2 c3 84 c2 8d 2e 11 35 57 c2 b9 45 c2 b6 c2 8e 37 c2 98 4d c2 a9 42 c3 99 c2 88 c2 b4 c2 97 c2 ac 54 36 c2 9f 36 c2 be 43 c2 bb 5b 18 59 6d 18 01 33 c3 a3 6c c2 85 c3 b7 c2 b1 c2 a9 c2 91 2b c2 bd c2 87 34 56 03 c3 93 0a 49 2a 76 01 c3 9a 6d c3 af c3 83 33 c3 b1 72 6e 08 c2 b3 c2 a7 16 5e 3a 5f 53 3f 03 48 c2 a3 39 c2 9e c3 9b c2 80 3e 52

The seemingly random c2 bytes throughout are a result of incorrect decoding of Base64. This issue is described here.