crypto::rsa
This module provides RSA signature and encryption schemes defined in PKCS #1.
The implementation only supports RSA keys with two prime factors. Most of the
RSA operations in this module require buffers to perform. Buffer sizes are
provided for keys of a default maximum size of 4096-bits. BITSIZE
may be changed with compiler flags to support bigger keys. MINBITSIZE
defines the minimum size accordingly.
Public and private keys are stored in byte slices. pubkey_init is used
to initialize a public key. privkey_init or privkey_initd is used
to initialize a private key, depending on which parameters are available.
This is a low-level module which implements cryptographic primitives. Direct
use of cryptographic primitives is not recommended for non-experts, as
incorrect use of these primitives can easily lead to the introduction of
security vulnerabilities. Non-experts are advised to use the high-level
operations available in the top-level crypto module.
Be advised that Hare's cryptography implementations have not been audited.
Index
Types
type pkcs1_hashalgo;
type privparams;
type pubparams;
Errors
type badsig;
type error;
Constants
const BITSIZE: size;
const MINBITSIZE: size;
const PKCS1_SIGNBUFSIZE: size;
const PKCS1_VERIFYBUFSIZE: size;
const PRIVKEYSIZE: size;
const PUBKEYSIZE: size;
Functions
fn pkcs1_sign([]u8, []u8, []u8, pkcs1_hashalgo, []u8) (void | error);
fn pkcs1_verify([]u8, []u8, []u8, pkcs1_hashalgo, []u8) (void | error);
fn privkey_init([]u8, privparams, []u8...) (size | error);
fn privkey_initd([]u8, privparams, []u8, []u8...) (size | error);
fn privkey_nbitlen([]u8) size;
fn privkey_nsize([]u8) size;
fn privkey_params([]u8) privparams;
fn pubkey_init([]u8, pubparams) (size | error);
fn pubkey_params([]u8) pubparams;
fn strerror(error) str;
Types
type pkcs1_hashalgo
type pkcs1_hashalgo = enum {
SHA1,
SHA256,
SHA384,
SHA512,
SHA512_224,
SHA512_256,
};
Supported hash algorithms for pkcs1_sign and pkcs1_verify.
type privparams
type privparams = struct {
nbitlen: size,
p: []u8,
q: []u8,
dp: []u8,
dq: []u8,
iq: []u8,
};
RSA key parameters for initializing private keys with privkey_init. If
the private exponent d is available, privkey_initd may be used, which
derives 'dp' and 'dq'. All big integer values are in big-endian order.
type pubparams
type pubparams = struct {
n: []u8,
e: []u8,
};
RSA key parameters for initializing public keys with pubkey_init.
Errors
type badsig
type badsig = !void;
Signature verification failed.
type error
type error = !(badsig | errors::overflow | errors::invalid);
A tagged union of all RSA error types.
Constants
def BITSIZE
def BITSIZE: size;
The default bit size of RSA keys is 4096-bit. Used as base for buffer sizes.
def MINBITSIZE
def MINBITSIZE: size;
The minimum bit size of RSA keys used only for validation during key init.
The default value is 1024-bit.
def PKCS1_SIGNBUFSIZE
def PKCS1_SIGNBUFSIZE: size;
Required buffer size for pkcs1_sign.
def PKCS1_VERIFYBUFSIZE
def PKCS1_VERIFYBUFSIZE: size;
Required buffer size for pkcs1_verify.
def PRIVKEYSIZE
def PRIVKEYSIZE: size;
Size required to store a private key of BITSIZE length.
def PUBKEYSIZE
def PUBKEYSIZE: size;
Size required to store a public key of BITSIZE length.
Functions
fn pkcs1_sign
fn pkcs1_sign(
priv: []u8,
msghash: []u8,
sig: []u8,
algo: pkcs1_hashalgo,
buf: []u8,
) (void | error);
Signs a message hash 'msghash' using the PKCS#1 V1.5 signature scheme. The
signature will be written to 'sig' which must be in the the size of the
modulus n (see privkey_nsize). 'algo' defines the hash algorithm
'msghash' was created with.
A temporary buffer 'buf' of size PKCS1_SIGNBUFSIZE must be provided.
fn pkcs1_verify
fn pkcs1_verify(
pubkey: []u8,
msghash: []u8,
sig: []u8,
algo: pkcs1_hashalgo,
buf: []u8,
) (void | error);
Verifies a PKCS#1 v1.5 signature given a public key 'pubkey', the message
hash 'msghash', the signature 'sig' and the hash algorithm 'algo'. 'algo'
must reflect the hash algorithm 'sig' was created with.
A temporary buffer 'buf' of size PKCS1_VERIFYBUFSIZE must be provided.
fn privkey_init
fn privkey_init(privkey: []u8, x: privparams, n: []u8...) (size | error);
Initializes the private key 'privkey' using the values from 'x'. 'nbitlen' of
'x' may be omitted, if the modulus 'n' is passed. All other values of 'x'
must be present. If 'x' is missing 'dp' and 'dq' use privkey_initd.
In case of invalid parameters or if the key is too small, errors::invalid
is returned. If the key does not fit 'privkey', errors::overflow is
returned. On success the number of bytes written to 'privkey' is returned.
fn privkey_initd
fn privkey_initd(privkey: []u8, x: privparams, d: []u8, n: []u8...) (size | error);
Initializes the private key 'privkey' using the values from 'x' and the
secret exponent 'd'. 'dp' and 'dq' will be derived from 'p' and 'q' of 'x'.
'nbitlen' of 'x' may be omitted, if the modulus 'n' is passed. 'x' must
provide 'iq'.
In case of invalid parameters or if the key is too small, errors::invalid
is returned. If the key does not fit 'privkey', errors::overflow is
returned. On success the number of bytes written to 'privkey' is returend.
fn privkey_nbitlen
fn privkey_nbitlen(privkey: []u8) size;
Returns the length of the modulus 'n'.
fn privkey_nsize
fn privkey_nsize(privkey: []u8) size;
Returns the number of bytes that are required to store a value modulo 'n'.
fn privkey_params
fn privkey_params(privkey: []u8) privparams;
Returns the private key parameters borrowed from 'privkey'.
fn pubkey_init
fn pubkey_init(pubkey: []u8, x: pubparams) (size | error);
Initializes a public key from given pubparams 'x'. The data format
of 'pubkey' is subject to change and must not be used to serialize the key.
PUBKEYSIZE defines the required size to store a key of BITSIZE.
If given key does not fit into 'pubkey' or is too small, errors::overflow
is returned. Returns errors::invalid, if given key parameters are
invalid. Returns the number of bytes written to 'pubkey' on success.
fn pubkey_params
fn pubkey_params(pubkey: []u8) pubparams;
Returns the public key parameters, borrowed from given 'pubkey'.
fn strerror
fn strerror(err: error) str;
Converts an error into a human-friendly string representation.