Cryptography Cheat Sheet for Developers

PKCS8 https://datatracker.ietf.org/doc/html/rfc5958 in usually used as syntax of unencrypted RSA private key,

you can simply generate a RSA key via openssl:

nix-shell -p openssl
[nix-shell:/tmp]$ openssl genpkey -algorithm rsa -out test.key
[nix-shell:/tmp]$ cat test.key
-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC6LU2ZNdy32+HL
...
c581/XSSIu1kZpptICNGM4MiDJyGoysNX7417wXgwr8YEb6fbMAMGjjYKbF9BlpY
yRdkNiEmIKL4/ZQoTLdyQR4vJQ==
-----END PRIVATE KEY-----

[nix-shell:/tmp]$ openssl rsa -in test.key -noout -text
RSA Private-Key: (2048 bit, 2 primes)
modulus:
    00:e9:6a:68:ab:7b:73:f0:14:72:24:e5:35:f1:c2:
    ...
publicExponent: 65537 (0x10001)
privateExponent:
    00:c0:6f:a1:11:d7:ba:f2:f0:f8:56:20:be:c3:ad:
    ...
prime1:
    00:fb:d7:d5:fd:2c:b5:b2:cd:92:b0:ea:60:83:29:
    ...
prime2:
    ...
exponent1:
    00:e5:8f:16:15:92:9d:85:00:71:c8:25:bc:17:92:
    ...
exponent2:
    3e:6e:01:ad:b7:63:36:96:90:f9:ed:38:c4:10:bf:
    ...
coefficient:
    00:89:e1:69:2b:78:97:a9:91:88:39:7a:75:08:f0:
    ...

The output is readable text but the original PKCS8 is in Abstract Syntax Notation One(ASN.1) https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx syntax and DER encoded.

Private key is kind of too long as example, lets use public key to explain.

RSA Public key can be generate from private key:

[nix-shell:/tmp]$ openssl rsa -in test.key -outform PEM -pubout
writing RSA key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6Wpoq3tz8BRyJOU18cJK
D+4lVGBz94lpRLfAAK3mjEWbIbeQ/uElnyGbq0Fe+XRMBdVpI5B5PQbM8kf6sNYv
n7BM+dRVq1LuRGmxjL/i+CW7VRWiIZxHWNF/eCaqn3j2hij81NK22m13eFMSOELo
76G6TDtEbv5rqJdhrJw6BlCbslHXNr4rT+q0R2ajricbY/xig/bz6mOetjgxoL6X
WiuJibtAYqGa7+iQse1icFz3SWCwwZjYE46uW1rUI7iyugRBhdVMiypPDj00wdak
77NiaiFw91Vl1EfZo09b8ztcSjBKWeE0tte8Iy5+AhKsC59/hE2wIFj5TnxVE4JC
kwIDAQAB
-----END PUBLIC KEY-----

The output of the public key is in PKCS1 in ASN.1 syntax DER encoded in PEM format.

PKCS1 represent RSA public key ASN.1 as

RSAPublicKey:

      RSAPublicKey ::= SEQUENCE {
          modulus           INTEGER,  -- n
          publicExponent    INTEGER   -- e
      }

You can read the same information as ASN.1 from

[nix-shell:/tmp]$ openssl rsa -in test.key -pubout -out test.pem
[nix-shell:/tmp]$ openssl rsa -in test.pem -pubin -noout -text
RSA Public-Key: (2048 bit)
Modulus:
    00:e9:6a:68:ab:7b:73:f0:14:72:24:e5:35:f1:c2:
    4a:0f:ee:25:54:60:73:f7:89:69:44:b7:c0:00:ad:
    e6:8c:45:9b:21:b7:90:fe:e1:25:9f:21:9b:ab:41:
    5e:f9:74:4c:05:d5:69:23:90:79:3d:06:cc:f2:47:
    fa:b0:d6:2f:9f:b0:4c:f9:d4:55:ab:52:ee:44:69:
    b1:8c:bf:e2:f8:25:bb:55:15:a2:21:9c:47:58:d1:
    7f:78:26:aa:9f:78:f6:86:28:fc:d4:d2:b6:da:6d:
    77:78:53:12:38:42:e8:ef:a1:ba:4c:3b:44:6e:fe:
    6b:a8:97:61:ac:9c:3a:06:50:9b:b2:51:d7:36:be:
    2b:4f:ea:b4:47:66:a3:ae:27:1b:63:fc:62:83:f6:
    f3:ea:63:9e:b6:38:31:a0:be:97:5a:2b:89:89:bb:
    40:62:a1:9a:ef:e8:90:b1:ed:62:70:5c:f7:49:60:
    b0:c1:98:d8:13:8e:ae:5b:5a:d4:23:b8:b2:ba:04:
    41:85:d5:4c:8b:2a:4f:0e:3d:34:c1:d6:a4:ef:b3:
    62:6a:21:70:f7:55:65:d4:47:d9:a3:4f:5b:f3:3b:
    5c:4a:30:4a:59:e1:34:b6:d7:bc:23:2e:7e:02:12:
    ac:0b:9f:7f:84:4d:b0:20:58:f9:4e:7c:55:13:82:
    42:93
Exponent: 65537 (0x10001)

So far all these PKCS are UNENCRYPTED, they are just encoded in certain format.

There is a common standard for store and exchange certs and keys that is encypted - PKCS #12 Personal Information Exchange Syntax https://datatracker.ietf.org/doc/html/rfc7292 aka PFX This is the common format when you get a new cert.

JWS https://datatracker.ietf.org/doc/html/rfc7515 is commonly used in OIDC https://openid.net/specs/openid-connect-core-1_0.html as id_token and sometimes access_token too.

The message is NOT ENCTYPTED, so anyone can actually see the claims in the JSON.

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature)

A example of JWS:(with line breaks for display purposes only):

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

JWS Signature basically is MAC, of header || payload

As the name indicate JWE https://datatracker.ietf.org/doc/html/rfc7516 can be use to encrypt messages, JWE is in the following format, where Ciphertext is the encrypted message.

BASE64URL(UTF8(JWE Protected Header)) ||
      '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE
      Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.'
      || BASE64URL(JWE Authentication Tag)

example:(with line breaks for display purposes only)

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.
OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe
ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb
Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV
mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg.
48V1_ALb6US04U3b.
5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji
SdiwkIr3ajwQzaBtQD_A.
XFBoMYUZodetZdvTiFvSkQ

AES requires a initial vector(IV), aka nonce. The following is a example of AES 256 CTR mode with a random 256-bit key and 0 as IV:

ghci> import Crypto.Random
ghci> import Crypto.Cipher.Types
ghci> import Crypto.Cipher.AES (AES256)
ghci> import Crypto.Error
ghci> do
ghci| cipher <- (getRandomBytes 32 :: IO ByteString) >>= (throwCryptoErrorIO . cipherInit) :: IO AES256
ghci| return $ ctrCombine cipher nullIV ("message"::ByteString)
ghci| 
"\208\207\SI\191\206\DELN"

CTR is good enough for common encryption case, while GCM https://csrc.nist.gov/publications/detail/sp/800-38d/final -SIV https://datatracker.ietf.org/doc/html/rfc8452 added Authenticated Encryption with Additional Data (AEAD) https://datatracker.ietf.org/doc/html/rfc5116 , and SIV to nonce misuse-resistant.

AEAD basically bind extra data, or context to cipher text and generate a MAC, aka authentication tag, to be able to verify cipher text's integrity(not tampered), and authenticity(not cut-and-paste).

The following is example of AES-GCM-SIV encryption of "message" with additional data "context" and a nonce.

ghci> import Crypto.Cipher.AESGCMSIV
ghci> do
ghci| key :: ByteString <- getRandomBytes 32
ghci| nonce <- generateNonce
ghci| throwCryptoErrorIO $ do
ghci| aes :: AES256 <- cipherInit key
ghci| return $ encrypt aes nonce ("context" :: ByteString) ("message" :: ByteString) 
ghci| 
(AuthTag {unAuthTag = "\239|\229V\USNT3\ACKf\NAK\STXC\251\134\FS"},"\149\229\142SW\209Z")

ChaCha20-Poly1305 https://datatracker.ietf.org/doc/html/rfc8439 requires very similar inputs to AES:

• a 32 bytes (256-bit) key, can derive key from password with a secure KDF
• a 12 bytes (96-bit) nonce aka IV

There are more steps to encrypt a message due to it is stream cipher aka state cipher, which is different from block cipher such as AES, block cipher generate fixed length key to encrypt fixed length message, while stream cipher can produce state to generate keystream for next chunk of data.

• AEAD need to add and finalize before encrypt, and cannot modify later on
• encrypt can call multiple times based on current state
• finalise a state will generate auth tag

ghci> import Crypto.Error
ghci> import Crypto.Cipher.ChaChaPoly1305
ghci| do
ghci| key <- getRandomBytes 32 :: IO ByteString
ghci| nonce <- getRandomBytes 12 :: IO ByteString
ghci| throwCryptoErrorIO $ do
ghci| st1 <- nonce12 nonce >>= initialize key
ghci| let
ghci|   st2 = finalizeAAD $ appendAAD ("context":: ByteString) st1
ghci|   (out, st3) = encrypt ("message":: ByteString) st2
ghci|   auth = finalize st3
ghci| return $ (convertToBase Base16 out :: ByteString, convertToBase Base16 auth :: ByteString)
("f0dd593fb3cac0","4a29dd7ae8b51ac748b37092ed485e88")

ECDH process is very simple:

1. choose a curve, there are a lot of curves available.

      ghci> :info CurveName
   type CurveName :: *
   data CurveName
     = SEC_p112r1
     | SEC_p112r2
     | SEC_p128r1
     ...
   

2. Alice generate a private key
3. Bob generate a private key
4. Alice's private key * Base point * Bob's public key = share key = Alice's public key * Base point * Bob's private key

ghci> import Crypto.PubKey.ECC.DH
ghci> import Crypto.PubKey.ECC.Types
ghci> let curve = getCurveByName SEC_p384r1
ghci> do
ghci| alicePrivateKey <- generatePrivate curve
ghci| let alicePublicKey = calculatePublic curve alicePrivateKey
ghci| bobPrivateKey <- generatePrivate curve
ghci| let bobPublicKey = calculatePublic curve bobPrivateKey
ghci| let aliceSharedKey = getShared curve alicePrivateKey bobPublicKey
ghci| let bobSharedKey = getShared curve bobPrivateKey alicePublicKey
ghci| return (aliceSharedKey == bobSharedKey)
ghci| 
True

Another popular curve is Curve25519, which is 128-bit level, Curve448 is 256-bit level security. https://datatracker.ietf.org/doc/html/rfc7748

do
alicePrivateKey <- generateSecretKey
let alicePublicKey = toPublic alicePrivateKey
bobPrivateKey <- generateSecretKey
let bobPublicKey = toPublic bobPrivateKey
let aliceSharedKey = dh bobPublicKey alicePrivateKey
let bobSharedKey = dh alicePublicKey bobPrivateKey
return (aliceSharedKey == bobSharedKey)

ECDSA https://datatracker.ietf.org/doc/html/rfc6979 won't encrypt the message, but just generate signature from sender's private key.

The following example is how Alice sign the message with ECDSA on Curve25519 with her private key, and Bob can verify the message is from Alice public key.

ghci> import Crypto.PubKey.ECC.ECDSA
ghci> import Crypto.PubKey.ECC.Generate
ghci> import Crypto.Hash.Algorithms
ghci> do
ghci| (alicePublicKey, alicePrivateKey) <- generate curve
ghci| toBob <- sign alicePrivateKey SHA256 ("message to Bob"::ByteString)
ghci| return $ verify SHA256 alicePublicKey toBob ("message to Bob"::ByteString)
ghci| 
True

Usage of EdDSA https://datatracker.ietf.org/doc/html/rfc8032 is basically the same as ECDSA, but on another curve edwards25519 or edwards448