View Source ecms (ecms v1.0.0)

Implementation of (parts of) RFC 5652 Cryptographic Message Syntax (CMS)

Summary

Types

DER encoded X.509 'Certificate'

DER encoded 'PrivateKeyInfo'

Functions

Encrypt Data to Recipients

Encrypt Data to Recipients

(re)sign Data

Sign Data using SignCert and SignKey

Verify CMS DER binary InDER

Types

-type cipher() ::
          aes_128_ofb | aes_192_ofb | aes_256_ofb | aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
          aes_128_cbc | aes_192_cbc | aes_256_cbc.
-type cipher_aead() :: aes_128_gcm | aes_192_gcm | aes_256_gcm.
-type der_certificate() :: public_key:der_encoded().

DER encoded X.509 'Certificate'

-type der_private_key() :: public_key:der_encoded().

DER encoded 'PrivateKeyInfo'

-type digest_type() :: crypto:sha2().

Functions

Link to this function

decrypt(Encrypted, RecipientCert, RecipientKey)

View Source
-spec decrypt(Encrypted :: binary(),
              RecipientCert :: der_certificate(),
              RecipientKey :: der_private_key()) ->
                 {ok, Decrypted :: binary()} | {error, _}.

Decrypt CMS binary

Link to this function

encrypt(Data, Recipients)

View Source
-spec encrypt(Data :: binary(), Recipients :: [Certificate :: der_certificate(), ...]) ->
                 {ok, Encrypted :: binary()} | {error, _}.

Encrypt Data to Recipients

Equivalent to encrypt(Data, Recipients, #{ })

Link to this function

encrypt(Data, Recipients, Opts)

View Source
-spec encrypt(Data :: binary(),
              Recipients :: [der_certificate()],
              Opts ::
                  #{digest_type => digest_type(),
                    auth_attrs => [#{attrType := tuple(), attrValues := [binary()]}, ...],
                    cipher => cipher() | cipher_aead()}) ->
                 {ok, Encrypted :: binary()} | {error, _}.

Encrypt Data to Recipients

When not set in Opts: digest_type defaults to 'sha256' and cipher to 'aes_256_cbc'.

For cipher set to 'aes_128_gcm', 'aes_192_gcm', or 'aes_256_gcm' the encoded content is AuthEnvelopedData and AuthAttributes can be set as auth_attrs in Opts.

The encoded recipientInfos contain a KeyAgreeRecipientInfo for each Elliptic Curve certificate and a KeyTransRecipientInfo for each RSA certificate in Recipients.

RSA-OAEP is used in KeyTransRecipientInfos; the value of digest_type sets the Hash and MaskGen algorithms.

KeyAgreeRecipientInfo uses RFC3394 AES Key Wrap and dhSinglePass-stdDH Key Derivation, the value of digest_type sets Hash algorithm

-spec sign(Data :: binary(),
           Opts ::
               #{digest_type => digest_type(),
                 singning_time => calendar:datetime(),
                 resign => boolean(),
                 included_certs => [Certificate :: der_certificate()],
                 signers := [{SignCert :: der_certificate(), SignKey :: der_private_key()}, ...]}) ->
              {ok, Signed :: binary()} | {error, _}.

(re)sign Data

When not set in Opts: digest_type defaults to sha256, signing_time to the current time, resign to 'false' and included_certs to [].

digest_type controls DigestAlgorithm, DSA/EC SigatureAlgorithm and for RSA signatures also Hash and MaskGen algorithm in RSA-PSS parameters.

If resign is set to 'true', Data must contain SignedData. Additional signatures from keys in Signers, the certificates in Signers and any included_certs are added to the existing SignedData.

Link to this function

sign(Data, SignCert, SignKey)

View Source
-spec sign(Data :: binary(), SignCert :: der_certificate(), SignKey :: der_private_key()) ->
              {ok, Signed :: binary()} | {error, _}.

Sign Data using SignCert and SignKey

Equivalent to sign(Data, #{ signers => [{SignCert, SignKey}])

-spec verify(InDER :: binary(), Trusted :: [der_certificate(), ...]) ->
                {ok, EContent :: binary()} | {error, _}.

Verify CMS DER binary InDER

returns {ok, EContent} if at least one signature is from a certificate in Trusted or from an included certificate that has been chain-validated against a certificate in Trusted.