# Specification: Ballerina Crypto Library

*Owners*: @shafreenAnfar @bhashinee

*Reviewers*: @shafreenAnfar

*Created*: 2022/08/23

*Updated*: 2022/08/25

*Edition*: Swan Lake

## Introduction

This is the specification for the Crypto standard library of Ballerina language, which provides Crypto functionalities.

The Crypto library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under `/docs/proposals`

. Proposals under discussion can be found with the label `type/proposal`

in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

## Contents

- Overview
- Hash
- HMAC
- Decode private/public key
- Encrypt-Decrypt
- 5.1. Encryption
- 5.2. Decryption

- Sign and Verify
- 6.1. Sign messages
- 6.1.1. RSA-MD5
- 6.1.2. RSA-SHA1
- 6.1.3. RSA-SHA256
- 6.1.4. RSA-SHA384
- 6.1.5. RSA-SHA512

- 6.2. Verify signature
- 6.2.1. RSA-MD5
- 6.2.2. RSA-SHA1
- 6.2.3. RSA-SHA256
- 6.2.4. RSA-SHA384
- 6.2.5. RSA-SHA512

- 6.1. Sign messages

## 1. Overview

The Ballerina `crypto`

library facilitates APIs to do operations like hashing, HMAC generation, checksum generation, encryption, decryption, signing data digitally, verifying digitally signed data, etc., with different cryptographic algorithms.

## 2. Hash

The `crypto`

library supports generating hashes with 5 different hash algorithms MD5, SHA1, SHA256, SHA384, and SHA512. Also, it supports generating the CRC32B checksum.

### 2.1. MD5

This API can be used to create the MD5 hash of the given data.

### 2.2. SHA1

This API can be used to create the SHA-1 hash of the given data.

### 2.3. SHA256

This API can be used to create the SHA-256 hash of the given data.

### 2.4. SHA384

This API can be used to create the SHA-384 hash of the given data.

### 2.5. SHA512

This API can be used to create the SHA-512 hash of the given data.

### 2.6. CRC32B

This API can be used to create the Hex-encoded CRC32B value of the given data.

## 3. HMAC

The `crypto`

library supports generating HMAC with 5 different hash algorithms: MD5, SHA1, SHA256, SHA384, and SHA512.

### 3.1. MD5

This API can be used to create HMAC using the MD5 hash function of the given data.

### 3.2. SHA1

This API can be used to create HMAC using the SHA-1 hash function of the given data.

### 3.3. SHA256

This API can be used to create HMAC using the SHA-256 hash function of the given data.

### 3.4. SHA384

This API can be used to create HMAC using the SHA-384 hash function of the given data.

### 3.5. SHA512

This API can be used to create HMAC using the SHA-512 hash function of the given data.

## 4. Decode private/public key

The `crypto`

library supports decoding the RSA private key from a `.p12`

file and a key file in the `PEM`

format. Also, it supports decoding a public key from a `.p12`

file and a certificate file in the `X509`

format. Additionally, this supports building an RSA public key with the modulus and exponent parameters.

### 4.1. Decode Private key from PKCS12 file

This API can be used to decode the private key from the given PKCS#12 file.

### 4.2. Decode RSA Private key using Private key and Password

This API can be used to decode the RSA private key from the given private key and private key password.

### 4.3. Decode RSA Public key from PKCS12 file

This API can be used to decode the RSA public key from the given PKCS#12 archive file.

### 4.4. Decode RSA Public key from the certificate file

This API can be used to decode the RSA public key from the given public certificate file.

### 4.5. Build RSA Public key from modulus and exponent parameters

This API can be used to build the RSA public key from the given modulus and exponent parameters.

## 5. Encrypt-Decrypt

The `crypto`

library supports both symmetric key encryption/decryption and asymmetric key encryption/decryption. The RSA algorithm can be used for asymmetric-key encryption/decryption with the use of private and public keys. The AES algorithm can be used for symmetric-key encryption/decryption with the use of a shared key.

### 5.1. Encryption

#### 5.1.1. RSA

This API can be used to create the RSA-encrypted value of the given data.

#### 5.1.2. AES-CBC

This API can be used to create the AES-CBC-encrypted value for the given data.

#### 5.1.3. AES-ECB

This API can be used to create the AES-ECB-encrypted value for the given data.

#### 5.1.4. AES-GCM

This API can be used to create the AES-GCM-encrypted value for the given data.

### 5.2. Decryption

#### 5.2.1. RSA-ECB

This API can be used to create the RSA-decrypted value for the given RSA-encrypted data.

#### 5.2.2. AES-CBC

This API can be used to create the AES-CBC-decrypted value for the given AES-CBC-encrypted data.

#### 5.2.3. AES-ECB

This API can be used to create the AES-ECB-decrypted value for the given AES-ECB-encrypted data.

#### 5.2.4. AES-GCM

This API can be used to create the AES-GCM-decrypted value for the given AES-GCM-encrypted data.

## 6. Sign and Verify

The `crypto`

library supports signing data using the RSA private key and verification of the signature using the RSA public key. This supports MD5, SHA1, SHA256, SHA384, and SHA512 digesting algorithms as well.

### 6.1. Sign messages

#### 6.1.1. RSA-MD5

This API can be used to create the RSA-MD5 based signature value for the given data.

#### 6.1.2. RSA-SHA1

This API can be used to create the RSA-SHA1 based signature value for the given data.

#### 6.1.3. RSA-SHA256

This API can be used to create the RSA-SHA256 based signature value for the given data.

#### 6.1.4. RSA-SHA384

This API can be used to create the RSA-SHA384 based signature value for the given data.

#### 6.1.5. RSA-SHA512

This API can be used to create the RSA-SHA512 based signature value for the given data.

### 6.2. Verify signature

#### 6.2.1. RSA-MD5

This API can be used to verify the RSA-MD5 based signature.

#### 6.2.2. RSA-SHA1

This API can be used to verify the RSA-SHA1 based signature.

#### 6.2.3. RSA-SHA256

This API can be used to verify the RSA-SHA256 based signature.

#### 6.2.4. RSA-SHA384

This API can be used to verify the RSA-SHA384 based signature.

#### 6.2.5. RSA-SHA512

This API can be used to verify the RSA-SHA512 based signature.