ballerina/crypto module

Module overview

This module provides the necessary utilities that are required to hash content using different hashing mechanisms and algorithms.

Samples

Hashing

The sample given below shows how to use hashing functions such as hashSha512 to calculate the hash value of a byte array and then encode the byte array using a common encoding algorithm.

import ballerina/io;
import ballerina/crypto;
import ballerina/encoding;

public function main() {
     // Input value for crypto operations
     string input = "Hello Ballerina";
     byte[] inputArr = input.toByteArray("UTF-8");
     byte[] output = [];

     // Hashing input value using different hashing algorithms, and printing hash value using Hex encoding.
     output = crypto:hashMd5(inputArr);
     io:println("Hash with MD5: " + encoding:encodeHex(output));

     output = crypto:hashSha1(inputArr);
     io:println("Hash with SHA1: " + encoding:encodeHex(output));

     output = crypto:hashSha256(inputArr);
     io:println("Hash with SHA256: " + encoding:encodeHex(output));

     output = crypto:hashSha384(inputArr);
     io:println("Hash with SHA384: " + encoding:encodeHex(output));

     output = crypto:hashSha512(inputArr);
     io:println("Hash with SHA512: " + encoding:encodeHex(output));
}

HMAC Generation

The sample given below shows how to use HMAC functions such as hmacSha512 to calculate the HMAC value of a byte array and then encode the byte array using a common encoding algorithm.

import ballerina/io;
import ballerina/crypto;
import ballerina/encoding;

public function main() {
     string charEncoding = "UTF-8";

     // Input value for crypto operations
     string input = "Hello Ballerina";
     byte[] inputArr = input.toByteArray(charEncoding);

     // The key used for HMAC generation.
     string key = "somesecret";
     byte[] keyArr = key.toByteArray(charEncoding);

     byte[] output = [];

     // HMAC generation for input value using different HMAC algorithms, and printing HMAC value using Hex encoding.
     output = crypto:hmacMd5(inputArr, keyArr);
     io:println("HMAC with MD5: " + encoding:encodeHex(output));

     output = crypto:hmacSha1(inputArr, keyArr);
     io:println("HMAC with SHA1: " + encoding:encodeHex(output));

     output = crypto:hmacSha256(inputArr, keyArr);
     io:println("HMAC with SHA256: " + encoding:encodeHex(output));

     output = crypto:hmacSha384(inputArr, keyArr);
     io:println("HMAC with SHA384: " + encoding:encodeHex(output));

     output = crypto:hmacSha512(inputArr, keyArr);
     io:println("HMAC with SHA512: " + encoding:encodeHex(output));
}

Calculating CRC32B Checksum

The sample given below shows how to use crc32b function to calculate the CRC32B checksum.

import ballerina/io;
import ballerina/crypto;

public function main() {
     // Input value for cryto operations
     string input = "Hello Ballerina";

     // Hex encoded CRC32B checksum generation for input value.
     io:println("CRC32B for text: " + crypto:crc32b(input));

     // The XML content to be hashed.
     xml xmlContent = xml `<foo>Hello Ballerina</foo>`;
     io:println("CRC32 for xml content: " + crypto:crc32b(xmlContent));
}

Signing

The sample given below shows how to use signing functions such as signRsaSha512 to get the signature value of a byte array and then encode the byte array using a common encoding algorithm.

import ballerina/io;
import ballerina/crypto;
import ballerina/encoding;

public function main() returns error? {
     // Input value for cryto operations
     string input = "Hello Ballerina";
     byte[] inputArr = input.toByteArray("UTF-8");

     // PrivateKey used for signing operations.
     crypto:KeyStore keyStore = { path: "/home/ballerina/keystore.p12", password: "ballerina" };
     crypto:PrivateKey privateKey = check crypto:decodePrivateKey(keyStore = keyStore, keyAlias = "ballerina",
                                                            keyPassword = "ballerina");


     // Signing input value using different signature algorithms, and printing the signature value
     // using Hex encoding.
     output = check crypto:signRsaMd5(inputArr, privateKey);
     io:println("RSA-MD5 signature: " + encoding:encodeHex(output));

     output = check crypto:signRsaSha1(inputArr, privateKey);
     io:println("RSA-SHA1 signature: " + encoding:encodeHex(output));

     output = check crypto:signRsaSha256(inputArr, privateKey);
     io:println("RSA-SHA256 signature: " + encoding:encodeHex(output));

     output = check crypto:signRsaSha384(inputArr, privateKey);
     io:println("RSA-SHA384 signature: " + encoding:encodeHex(output));

     output = check crypto:signRsaSha512(inputArr, privateKey);
     io:println("RSA-SHA512 signature: " + encoding:encodeHex(output));
}

Type Definitions

Type Values Description
KeyAlgorithm RSA

The key algorithms supported by crypto module.

Records Summary

Record Description
CryptoError Error relevant to crypto operations.
KeyStore Record for providing key store related configurations.
PrivateKey Private key used in cryptographic operations.
PublicKey Public key used in cryptographic operations.
TrustStore Record for providing trust store related configurations.

Functions Summary

Return Type Function and Description
string crc32b(any input)

Returns Hex encoded CRC32B value for the provided element. This accepts string, byte[], json and xml content.

PrivateKey | error<> decodePrivateKey(crypto:KeyStore? keyStore, string? keyAlias, string? keyPassword)

Read a private key from the provided PKCS#12 archive file.

PublicKey | error<> decodePublicKey(crypto:KeyStore? keyStore, string? keyAlias)

Read a public key from the provided PKCS#12 archive file.

byte[] hashMd5(byte[] input)

Returns the MD5 hash of the given data.

byte[] hashSha1(byte[] input)

Returns the SHA-1 hash of the given data.

byte[] hashSha256(byte[] input)

Returns the SHA-256 hash of the given data.

byte[] hashSha384(byte[] input)

Returns the SHA-384 hash of the given data.

byte[] hashSha512(byte[] input)

Returns the SHA-512 hash of the given data.

byte[] hmacMd5(byte[] input, byte[] key)

Returns the HMAC using MD-5 hash function of the given data.

byte[] hmacSha1(byte[] input, byte[] key)

Returns the HMAC using SHA-1 hash function of the given data.

byte[] hmacSha256(byte[] input, byte[] key)

Returns the HMAC using SHA-256 hash function of the given data.

byte[] hmacSha384(byte[] input, byte[] key)

Returns the HMAC using SHA-384 hash function of the given data.

byte[] hmacSha512(byte[] input, byte[] key)

Returns the HMAC using SHA-512 hash function of the given data.

byte[] | error<> signRsaMd5(byte[] input, crypto:PrivateKey privateKey)

Returns RSA-MD5 based signature value for the given data.

byte[] | error<> signRsaSha1(byte[] input, crypto:PrivateKey privateKey)

Returns RSA-SHA1 based signature value for the given data.

byte[] | error<> signRsaSha256(byte[] input, crypto:PrivateKey privateKey)

Returns RSA-SHA256 based signature value for the given data.

byte[] | error<> signRsaSha384(byte[] input, crypto:PrivateKey privateKey)

Returns RSA-SHA384 based signature value for the given data.

byte[] | error<> signRsaSha512(byte[] input, crypto:PrivateKey privateKey)

Returns RSA-SHA512 based signature value for the given data.

Constants

Name Data Type Value Description
RSA RSA

The RSA algorithm

public type CryptoError record

Error relevant to crypto operations.

Field Name Data Type Default Value Description
message string

Error message

public type KeyStore record

Record for providing key store related configurations.

Field Name Data Type Default Value Description
path string

Path to the key store file

password string

Key store password

public type PrivateKey record

Private key used in cryptographic operations.

Field Name Data Type Default Value Description
algorithm RSA

Key algorithm

public type PublicKey record

Public key used in cryptographic operations.

Field Name Data Type Default Value Description
algorithm RSA

Key algorithm

public type TrustStore record

Record for providing trust store related configurations.

Field Name Data Type Default Value Description
path string

Path to the key store file

password string

Key store password

public function crc32b(any input) returns (string)

Returns Hex encoded CRC32B value for the provided element. This accepts string, byte[], json and xml content.

Parameter Name Data Type Default Value Description
input any

Value for checksum generation

Return Type Description
string

The generated checksum

public function decodePrivateKey(crypto:KeyStore? keyStore, string? keyAlias, string? keyPassword) returns (PrivateKey | error<>)

Read a private key from the provided PKCS#12 archive file.

Parameter Name Data Type Default Value Description
keyStore crypto:KeyStore? null

Key store configuration

keyAlias string? null

Key alias

keyPassword string? null

Key password

Return Type Description
PrivateKey | error<>

Reference to the private key or error if private key was unreadable

public function decodePublicKey(crypto:KeyStore? keyStore, string? keyAlias) returns (PublicKey | error<>)

Read a public key from the provided PKCS#12 archive file.

Parameter Name Data Type Default Value Description
keyStore crypto:KeyStore? null

Key store configuration

keyAlias string? null

Key alias

Return Type Description
PublicKey | error<>

Reference to the public key or error if private key was unreadable

public function hashMd5(byte[] input) returns (byte[])

Returns the MD5 hash of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

Return Type Description
byte[]

Hashed output

public function hashSha1(byte[] input) returns (byte[])

Returns the SHA-1 hash of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

Return Type Description
byte[]

Hashed output

public function hashSha256(byte[] input) returns (byte[])

Returns the SHA-256 hash of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

Return Type Description
byte[]

Hashed output

public function hashSha384(byte[] input) returns (byte[])

Returns the SHA-384 hash of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

Return Type Description
byte[]

Hashed output

public function hashSha512(byte[] input) returns (byte[])

Returns the SHA-512 hash of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

Return Type Description
byte[]

Hashed output

public function hmacMd5(byte[] input, byte[] key) returns (byte[])

Returns the HMAC using MD-5 hash function of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

key byte[]

Key used for HMAC generation

Return Type Description
byte[]

HMAC output

public function hmacSha1(byte[] input, byte[] key) returns (byte[])

Returns the HMAC using SHA-1 hash function of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

key byte[]

Key used for HMAC generation

Return Type Description
byte[]

HMAC output

public function hmacSha256(byte[] input, byte[] key) returns (byte[])

Returns the HMAC using SHA-256 hash function of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

key byte[]

Key used for HMAC generation

Return Type Description
byte[]

HMAC output

public function hmacSha384(byte[] input, byte[] key) returns (byte[])

Returns the HMAC using SHA-384 hash function of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

key byte[]

Key used for HMAC generation

Return Type Description
byte[]

HMAC output

public function hmacSha512(byte[] input, byte[] key) returns (byte[])

Returns the HMAC using SHA-512 hash function of the given data.

Parameter Name Data Type Default Value Description
input byte[]

Value to be hashed

key byte[]

Key used for HMAC generation

Return Type Description
byte[]

HMAC output

public function signRsaMd5(byte[] input, crypto:PrivateKey privateKey) returns (byte[] | error<>)

Returns RSA-MD5 based signature value for the given data.

Parameter Name Data Type Default Value Description
input byte[]

The content to be signed

privateKey crypto:PrivateKey

Private key used for signing.

Return Type Description
byte[] | error<>

The generated signature or error if private key is invalid

public function signRsaSha1(byte[] input, crypto:PrivateKey privateKey) returns (byte[] | error<>)

Returns RSA-SHA1 based signature value for the given data.

Parameter Name Data Type Default Value Description
input byte[]

The content to be signed

privateKey crypto:PrivateKey

Private key used for signing.

Return Type Description
byte[] | error<>

The generated signature or error if private key is invalid

public function signRsaSha256(byte[] input, crypto:PrivateKey privateKey) returns (byte[] | error<>)

Returns RSA-SHA256 based signature value for the given data.

Parameter Name Data Type Default Value Description
input byte[]

The content to be signed

privateKey crypto:PrivateKey

Private key used for signing.

Return Type Description
byte[] | error<>

The generated signature or error if private key is invalid

public function signRsaSha384(byte[] input, crypto:PrivateKey privateKey) returns (byte[] | error<>)

Returns RSA-SHA384 based signature value for the given data.

Parameter Name Data Type Default Value Description
input byte[]

The content to be signed

privateKey crypto:PrivateKey

Private key used for signing.

Return Type Description
byte[] | error<>

The generated signature or error if private key is invalid

public function signRsaSha512(byte[] input, crypto:PrivateKey privateKey) returns (byte[] | error<>)

Returns RSA-SHA512 based signature value for the given data.

Parameter Name Data Type Default Value Description
input byte[]

The content to be signed

privateKey crypto:PrivateKey

Private key used for signing.

Return Type Description
byte[] | error<>

The generated signature or error if private key is invalid