summaryrefslogtreecommitdiff
path: root/M2Crypto/Rand.py
blob: 86a6f16719d578a384689d2d5083884ba6811d62 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
"""M2Crypto wrapper for OpenSSL PRNG. Requires OpenSSL 0.9.5 and above.

Copyright (c) 1999-2003 Ng Pheng Siong. All rights reserved.
Copyright (c) 2014-2017 Matej Cepl. All rights reserved.

See LICENCE for the license information.
"""
from __future__ import absolute_import

from M2Crypto import m2, py27plus, six
if py27plus:
    from typing import AnyStr, Tuple  # noqa


__all__ = ['rand_seed', 'rand_add', 'load_file', 'save_file', 'rand_bytes',
           'rand_pseudo_bytes', 'rand_file_name', 'rand_status']


class RandError(ValueError):
    pass

m2.rand_init(RandError)


def rand_add(blob, entropy):
    # type: (bytes, float) -> None
    """
    Mixes blob into the PRNG state.

    :param blob: added data
    :param entropy: (the lower bound of) an estimate of how much randomness
        is contained in blob, measured in bytes.

    Thus, if the data at buf are unpredictable to an adversary, this
    increases the uncertainty about the state and makes the PRNG output less
    predictable. Suitable input comes from user interaction (random key
    presses, mouse movements) and certain hardware events.

    Details about sources of randomness and how to estimate their entropy
    can be found in the literature, e.g. RFC 1750.
    """
    m2.rand_add(blob, entropy)  # pylint: disable=no-member


def rand_seed(seed):
    # type: (bytes) -> None
    """
    Equivalent to rand_add() when len(seed) == entropy.

    :param seed: added data (see description at rand_add)
    """
    m2.rand_seed(seed)  # pylint: disable=no-member


def rand_status():
    # type: () -> int
    """
    Check whether there is enough entropy in PRNG.

    :return: 1 if the PRNG has been seeded with enough
       data, 0 otherwise.
    """
    return m2.rand_status()  # pylint: disable=no-member


def rand_file_name():
    # type: () -> str
    """
    Generate a default path for the random seed file.

    :return: string with the filename.
       The seed file is $RANDFILE if that environment variable
       is set, $HOME/.rnd otherwise. If $HOME is not set either,
       an error occurs.
    """
    return six.ensure_text(m2.rand_file_name())  # pylint: disable=no-member


def load_file(filename, max_bytes):
    # type: (AnyStr, int) -> int
    """
    Read a number of bytes from file filename and adds them to the PRNG.

    If max_bytes is non-negative, up to to max_bytes are read; starting with
    OpenSSL 0.9.5, if max_bytes is -1, the complete file is read.

    :param filename:
    :param max_bytes:
    :return: the number of bytes read.
    """
    return m2.rand_load_file(six.ensure_str(filename), max_bytes)  # pylint: disable=no-member


def save_file(filename):
    # type: (AnyStr) -> int
    """
    Write a number of random bytes (currently 1024) to file.

    The file then can be used to initialize the PRNG by calling load_file() in
    a later session.

    :param filename:
    :return: returns the number of bytes written, and -1 if the bytes
         written were generated without appropriate seed.
    """
    return m2.rand_save_file(filename)  # pylint: disable=no-member


def rand_bytes(num):
    # type: (int) -> bytes
    """
    Return n cryptographically strong pseudo-random bytes.

    An error occurs if the PRNG has not been seeded with enough randomness
    to ensure an unpredictable byte sequence.

    :param num: number of bytes to be returned
    :return: random bytes
    """
    return m2.rand_bytes(num)  # pylint: disable=no-member


def rand_pseudo_bytes(num):
    # type: (int) -> Tuple[bytes, int]
    """
    Return num pseudo-random bytes into buf.

    Pseudo-random byte sequences generated by this method will be unique
    if they are of sufficient length, but are not necessarily
    unpredictable. They can be used for non-cryptographic purposes and for
    certain purposes in cryptographic protocols, but usually not for key
    generation etc.

    Output of the function is mixed into the entropy pool before
    retrieving the new pseudo-random bytes unless disabled at compile
    time (see FAQ).

    :param num: number of bytes to be returned
    :return: random bytes
    """
    import warnings
    if m2.OPENSSL_VERSION_NUMBER >= 0x10100000:
        warnings.warn('The underlying OpenSSL method has been ' +
                      'deprecated. Use Rand.rand_bytes instead.',
                      DeprecationWarning)

    return m2.rand_pseudo_bytes(num)  # pylint: disable=no-member