SwiftDigest is a library for cleanly and correctly calculating digests or hashes of data. It is designed to be simple to use for simple tasks, but well-factored and cleanly designed enough for complex tasks, and extensible with new algorithms and features. It is not designed to implement algorithms in pure Swift, although you could certainly do that yourself.
SwiftDigest currently supports SHA-256 and SHA-1, using CommonCrypto as its engine. Additional algorithms can be added from your own code. I'm also happy to accept pull requests.
// Simple, "all at once" interface
digest(myString, algorithm: SHA256()).hex
// Or build it up over time
var buffer = DigestBuffer(SHA256())
// Periodically:
buffer += someData
// When you want a digest from it:
let digest = buffer.digest
// The digest is available in multiple formats:
digest.bytes
digest.data
digest.hex
digest.base64WithOptions(nil)
To calculate a digest with SwiftDigest, you will first have to instantiate an
algorithm. Algorithms conform to the AlgorithmType protocol and present a
very simple, fairly useless interface. You usually won't use one directly;
instead, you'll pass it to another part of SwiftDigest with a friendlier
interface. However, if you need the absolute best speed possible, you can
use a raw algorithm.
AlgorithmType does not specify any constructors, and construction is up to
the individual conforming types. Currently, SwiftDigest includes SHA256 and
SHA1 algorithms, but you can create your own as well. See the documentation
comments on AlgorithmType for details on what you need to do.
SwiftDigest provides a digest(_: algorithm:) function as a simple interface
to its functionality. The first parameter is the data, which can be in one of four
formats:
- A
[UInt8]array of bytes. - An instance conforming to
Digestible.Digestibletypes know how to feed themselves into an Algorithm. They includeString,NSData, andUInt8. - A
SequenceTypeof[UInt8]arrays of bytes. (Currently disabled due to compiler trouble.) - A
SequenceTypeofDigestibleinstances.
Instances in the Sequence variants mentioned above will be added to the digest
one at a time, so digest() plays quite well with Swift's built-in lazy()
sequences.
digest() returns a Digest object, described below. Internally, it uses a
DigestBuffer.
A completed digest is available as a Digest object. Each Digest object
contains an immutable digest value, which it can format in many ways:
bytes: a[UInt8]array of raw bytes.data: anNSDataobject containing the raw bytes.hex: aStringcontaining a hexadecimal representation of the digest.base64WithOptions(): returns a Base64-encodedString. Options are as in Foundation.base64DataWithOptions(): returns a Base64-encodedNSData. Options are as in Foundation.base64BytesWithOptions()returns a Base64-encoded[UInt8]byte array. Options are as in Foundation.
Digests are also Equatable, Hashable, and Comparable. Shorter digests are
treated as less than longer digests, but you should only ever encounter this
case if you're comparing digests from different algorithms.
A DigestBuffer allows you to incrementally build up a digest, optionally
reading values out of it as you go along. To get started, allocate a
DigestBuffer with a new algorithm:
var buffer = DigestBuffer(SHA256())
Then append some data. The append() method comes in several variants,
taking a Digestible object, a [UInt8] array, or an UnsafeArrayBuffer
of UInt8s.
buffer.append(data)
buffer.append(moreData)
You can also use the overloaded += operator, or the + operator, which
goes well with reduce().
buffer += data
buffer += moreData
At any time, you can get a Digest object from the digest property and
use it:
let digest = buffer.digest
But even after doing so, it's okay to keep modifying the buffer; the old digest object won't be affected:
buffer += evenMoreData
Copying a DigestBuffer will also give you an independent instance
containing all the in-progress data that the old digest had:
var otherBuffer = buffer
buffer += "c"
otherBuffer += "c"
buffer.digest == otherBuffer.digest
Contributions are welcome, and should be submitted as pull requests to GitHub. If you want to contribute an algorithm, please observe the following rules:
- Include at least two tests: one ensuring that basic hashing works, and one
ensuring you can correctly copy a
DigestBufferconfigured with your algorithm. The current tests include examples of these tests for the existing algorithms. - The main SwiftDigest repository is for production-ready implementations of algorithms. Pure Swift reimplementations of algorithms will only be accepted if they're written by experienced cryptographic engineers. You should instead rely on a well-tested cryptographic library like CommonCrypto.
Brent Royal-Gordon brent@architechies.com for Groundbreaking Software.
Please drop me a line if you use SwiftDigest in a product. I'd love to see where it goes and find out what could be improved.
Copyright (C) 2014 Groundbreaking Software LLC. Distributed under the MIT License.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.