Home

Awesome

<p align="center"> <a href="https://www.kitura.io/packages.html#all"> <img src="https://img.shields.io/badge/docs-kitura.io-1FBCE4.svg" alt="APIDoc"> </a> <a href="https://travis-ci.org/Kitura/BlueRSA"> <img src="https://travis-ci.org/Kitura/BlueRSA.svg?branch=master" alt="Build Status - Master"> </a> <img src="https://img.shields.io/badge/os-macOS-green.svg?style=flat" alt="macOS"> <img src="https://img.shields.io/badge/os-iOS-green.svg?style=flat" alt="iOS"> <img src="https://img.shields.io/badge/os-linux-green.svg?style=flat" alt="Linux"> <img src="https://img.shields.io/badge/license-Apache2-blue.svg?style=flat" alt="Apache 2"> <a href="http://swift-at-ibm-slack.mybluemix.net/"> <img src="http://swift-at-ibm-slack.mybluemix.net/badge.svg" alt="Slack Status"> </a> </p>

BlueRSA

Swift cross-platform RSA wrapper library for RSA encryption and signing. Works on supported Apple platforms (using Security framework). Linux (using OpenSSL) is working but is still somewhat of a work in progress.

Contents

Prerequisites

Swift

macOS

iOS

Linux

Build

To build CryptorRSA from the command line:

% cd <path-to-clone>
% swift build

Testing

To run the supplied unit tests for CryptorRSA from the command line:

% cd <path-to-clone>
% swift build
% swift test

Using CryptorRSA

Including in your project

Swift Package Manager

To include BlueRSA into a Swift Package Manager package, add it to the dependencies attribute defined in your Package.swift file. You can select the version using the majorVersion and minor parameters. For example:

	dependencies: [
		.Package(url: "https://github.com/Kitura/BlueRSA", majorVersion: <majorVersion>, minor: <minor>)
	]

Carthage

To include BlueRSA in a project using Carthage, add a line to your Cartfile with the GitHub organization and project names and version. For example:

	github "Kitura/BlueRSA" ~> <majorVersion>.<minor>

Before starting

The first you need to do is import the CryptorRSA framework. This is done by the following:

import CryptorRSA

Data Types

BlueRSA supports the following major data types:

Key Handling

BlueRSA provides seven (7) functions each for creating public and private keys from data. They are as follows (where createXXXX is either createPublicKey or createPrivateKey depending on what you're trying to create):

Additionally, there are three APIs for creating a public key by extracting the key from a PEM formatted certificate: They are:

Example

The following example illustrates creating a public key given PEM encoded file located on a certain path. *Note: Exception handling omitted for brevity.

import Foundation
import CryptorRSA

...

let keyName = ...
let keyPath = ...

let publicKey = try CryptorRSA.createPublicKey(withPEMNamed: keyName, onPath: keyPath)

...

<Do something with the key...>

Data Encryption and Decryption Handling

BlueRSA provides functions for the creation of each of the three (3) data handling types:

Plaintext Data Handling and Signing

There are two class level functions for creating a PlaintextData object. These are:

Once the PlaintextData object is created, there are two instance functions that can be used to manipulate the contained data. These are:

Example

import Foundation
import CryptorRSA

...

let keyName = ...
let keyPath = ...

let myData: Data = <... Data to be encrypted ...>

let publicKey = try CryptorRSA.createPublicKey(withPEMNamed: keyName, onPath: keyPath)
let myPlaintext = CryptorRSA.createPlaintext(with: myData)
let encryptedData = try myPlaintext.encrypt(with: publicKey, algorithm: .sha1)

...

< Do something with the encrypted data...>


import Foundation
import CryptorRSA

...

let keyName = ...
let keyPath = ...

let myData: Data = <... Data to be signed ...>

let privateKey = try CryptorRSA.createPrivateKey(withPEMNamed: keyName, onPath: keyPath)
let myPlaintext = CryptorRSA.createPlaintext(with: myData)
let signedData = try myPlaintext.signed(with: privateKey, algorithm: .sha1)

...

< Do something with the signed data...>

Encrypted Data Handling

There are two class level functions for creating a EncryptedData object. These are:

Once the EncryptedData object is created, there is an instance function that can be used to decrypt the enclosed data:

BlueRSA currently supports OAEP padding, which is the recommended padding algorithm.

Example

import Foundation
import CryptorRSA

...

let keyName = ...
let keyPath = ...
let publicKey = try CryptorRSA.createPublicKey(withPEMNamed: keyName, onPath: keyPath)

let pkeyName = ...
let pkeyPath = ...
let privateKey = try CryptorRSA.createPrivateKey(withPEMNamed: pkeyName, onPath: pkeyPath)

let myData: Data = <... Data to be encrypted ...>

let myPlaintext = CryptorRSA.createPlaintext(with: myData)
let encryptedData = try myPlaintext.encrypt(with: publicKey, algorithm: .sha1)

let decryptedData = try encryptedData.decrypt(with: privateKey, algorithm: .sha1)

...

< Do something with the decrypted data...>

Signature Verification Handling

There is a single class level function that can be used to create a SignedData object. It is:

Once created or obtained PlaintextData and SignedData, there is an instance function which can be used to verify the signature contained therein:

import Foundation
import CryptorRSA

...

let keyName = ...
let keyPath = ...
let publicKey = try CryptorRSA.createPublicKey(withPEMNamed: keyName, onPath: keyPath)

let pkeyName = ...
let pkeyPath = ...
let privateKey = try CryptorRSA.createPrivateKey(withPEMNamed: pkeyName, onPath: pkeyPath)

let myData: Data = <... Data to be signed ...>

let myPlaintext = CryptorRSA.createPlaintext(with: myData)
let signedData = try myPlaintext.signed(with: privateKey, algorithm: .sha1)

if try myPlaintext.verify(with: publicKey, signature: signedData, algorithm: .sha1) {

	print("Signature verified")

} else {

	print("Signature Verification Failed")
}

Data Type Utility Functions

All three of the data handling types have two common utility instance functions. These are:

Community

We love to talk server-side Swift and Kitura. Join our Slack to meet the team!

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.