integer/doc/modular_arithmetic/discrete_log.qbk

[section:discrete_log Discrete Log]

[section Introduction]

The discrete log is the inverse of modular exponentiation.
To wit, if /a/[super /x/] = /b/ mod /p/, then we write /x/ = log[sub a](/b/).
Fast algorithms for modular exponentiation exists, but currently there are no polynomial time algorithms known for the discrete logarithm,
a fact which is the basis for the security of Diffie-Hellman key exchange.

Despite having exponential complexity in the number of bits, the algorithms for discrete logarithm provided by Boost are still useful,
for there are many uses of the discrete logarithm outside of cryptography which do not require massive inputs.
The algorithms provided by Boost should be acceptable up to roughly 32 bits.

[endsect]

[section Synopsis]

    #include <boost/integer/discrete_log.hpp>

    namespace boost { namespace integer {

    template<class Z>
    boost::optional<Z> trial_multiplication_discrete_log(Z base, Z arg, Z p);


    template<class Z>
    class bsgs_discrete_log
    {
    public:
        bsgs_discrete_log(Z base, Z p);

        boost::optional<Z> operator()(Z arg) const;

    };
    }}

[endsect]

[section Usage]


Boost provides two algorithms for the discrete log: Trial multiplication and the "baby-step giant-step" algorithm.
Basic usage is shown below:

    auto logarithm = trial_multiplication_discrete_log(2, 3, 5);
    if (logarithm)
    {
        std::cout << "log_2(3) mod 5 = " << l.value() << std::endl;
    }

    auto log_2 = bsgs_discrete_log(2, 5);
    int log = log_2(3).value();
    std::cout << "log_2(3) mod 5 = " << log << std::endl;


Of these, trial multiplication is more general, requires [bigo](/p/) time and [bigo](1) storage.
The baby-step giant step algorithm requires [bigo]([radic] p) time and [bigo]([radic] p) storage,
and is slightly less general as the base must be coprime to the the modulus.
Let's illustrate this with a few examples: Suppose we wish to compute log[sub 2](3) mod 4.
Since 2[super /x/] = 3 mod 4 has no solution, the result is undefined.

    boost::optional<int> l = trial_multiplication_discrete_log(2, 3, 4);
    if (!l)
    {
        std::cout << "log_2(3) mod 4 is undefined!\n";
    }

The baby-step giant-step algorithm is less polite when the base and the modulus are not coprime:

    try
    {
        auto log_2 = bsgs_discrete_log(2, 4);
    }
    catch(std::exception const & e)
    {
        // e.what() is gonna tell you 2 and 4 are not coprime:
        std::cout << e.what() << std::endl;
    }


The baby-step giant-step discrete log will *never* compute a logarithm when the base and modulus are not coprime,
because it relies on the existence of modular multiplicative inverses.
However, discrete logarithms can exist even when the base and modulus share a common divisor greater than 1.
For example, since 2[super 1] = 2 mod 4, log[sub 2](2) = 1.
Trial multiplication successfully recovers this value, and `bsgs_discrete_log` blows up.


[endsect]

[section References]
Wagstaff, Samuel S., ['The Joy of Factoring], Vol. 68. American Mathematical Soc., 2013.
[endsect]
[endsect]
[/
Copyright 2018 Nick Thompson.
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt).
]