Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Brian Smith
nettle
Commits
c8c37f89
Commit
c8c37f89
authored
Apr 04, 2013
by
Niels Möller
Browse files
Update manual with ECC material and some spell checking.
parent
ede8bf66
Changes
2
Hide whitespace changes
Inline
Sidebyside
ChangeLog
View file @
c8c37f89
20130404 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (Elliptic curves): Document highlevel ECDSA
support.
From Martin Storsjö. Fallback functions for older GMP releases.
* gmpglue.c (mpn_copyd, mpn_copyi, mpn_zero): New functions.
* gmpglue.h: Declare them.
...
...
nettle.texinfo
View file @
c8c37f89
...
...
@@ 7,14 +7,14 @@
@syncodeindex fn cp
@c
%**end of header
@set UPDATEDFOR 2.
6
@set UPDATEDFOR 2.
7
@set AUTHOR Niels Möller
@copying
This manual is for the Nettle library (version @value
{
UPDATEDFOR
}
), a
lowlevel cryptographic library.
Originally written 2001 by @value
{
AUTHOR
}
, updated 201
2
.
Originally written 2001 by @value
{
AUTHOR
}
, updated 201
3
.
@quotation
This manual is placed in the public domain. You may freely copy it, in
...
...
@@ 23,6 +23,12 @@ appreciated, but not required.
@end quotation
@end copying
@ifnottex
@macro pmod
{
m
}
(mod
\m\)
@end macro
@end ifnottex
@titlepage
@title Nettle Manual
@subtitle For the Nettle Library version @value
{
UPDATEDFOR
}
...
...
@@ 73,7 +79,7 @@ Reference
* Key derivation functions::
* Publickey algorithms::
* Randomness::
* A
scii
encoding::
* A
SCII
encoding::
* Miscellaneous functions::
* Compatibility functions::
...
...
@@ 87,6 +93,7 @@ Publickey algorithms
* RSA:: The RSA public key algorithm.
* DSA:: The DSA digital signature algorithm.
* Elliptic curves:: Elliptic curves and ECDSA
@end detailmenu
@end menu
...
...
@@ 189,7 +196,7 @@ The implementation of the MD5 message digest is written by Colin Plumb.
It has been hacked some more by Andrew Kuchling and @value
{
AUTHOR
}
.
Released into the public domain.
@item RIP
M
ED160
@item RIPE
M
D160
The implementation of RIPEMD160 message digest is based on the code in
libgcrypt, copyright owned by the Free Software Foundation. Ported to
Nettle by Andres Mejia. Released under the LGPL.
...
...
@@ 239,6 +246,11 @@ for bignum operations.
@item DSA
Written by @value
{
AUTHOR
}
, released under the LGPL. Uses the GMP library
for bignum operations.
@item ECDSA
Written by @value
{
AUTHOR
}
, released under the LGPL. Uses the GMP library
for bignum operations. Development of Nettle's ECC support was funded by
Internetfonden.
@end table
@node Conventions, Example, Copyright, Top
...
...
@@ 287,7 +299,7 @@ functions which can fail, return one on success and zero on failure.
@chapter Example
A simple example program that reads a file from standard input and
writes its SHA1 checksum on standard output should give the flavor of
writes its SHA1 check

sum on standard output should give the flavor of
Nettle.
@example
...
...
@@ 332,7 +344,7 @@ This chapter describes all the Nettle functions, grouped by family.
* Key derivation functions::
* Publickey algorithms::
* Randomness::
* A
scii
encoding::
* A
SCII
encoding::
* Miscellaneous functions::
* Compatibility functions::
@end menu
...
...
@@ 544,7 +556,7 @@ This function also resets the context in the same way as
@subsubsection @acronym
{
SHA3224
}
The SHA3 hash functions were specified by NIST in re
p
sonse to weaknesses
The SHA3 hash functions were specified by NIST in res
p
onse to weaknesses
in SHA1, and doubts about SHA2 hash functions which structurally are
very similar to SHA1. The standard is a result of a competition, where
the winner, also known as Keccak, was designed by Guido Bertoni, Joan
...
...
@@ 1929,7 +1941,7 @@ underlying cipher. These interfaces are defined in @file{<nettle/gcm.h>}
@subsubsection General @acronym
{
GCM
}
interface
@deftp
{
Context struct
}
{
struct gcm
_
key
}
Message independent hash subkey, and related tables.
Message independent hash sub

key, and related tables.
@end deftp
@deftp
{
Context struct
}
{
struct gcm
_
ctx
}
...
...
@@ 1994,7 +2006,7 @@ The following macros are defined.
@deffn Macro GCM
_
CTX (@var
{
context
_
type
}
)
This defines an allinone context struct, including the context of the
underlying cipher, the hash subkey, and the permessage state. It expands
underlying cipher, the hash sub

key, and the permessage state. It expands
to
@example
@
{
...
...
@@ 2350,7 +2362,7 @@ attacks by using salting and expensive computation.
@subsection @acronym
{
PBKDF2
}
The most well known PBKDF is the @code
{
PKCS #5 PBKDF2
}
described in
@cite
{
RFC 2898
}
which uses a pseudorandom function such as
@cite
{
RFC 2898
}
which uses a pseudo

random function such as
@acronym
{
HMACSHA1
}
.
Nettle's @acronym
{
PBKDF2
}
functions are defined in
...
...
@@ 2488,6 +2500,7 @@ key, and to no others''.
@menu
* RSA:: The RSA public key algorithm.
* DSA:: The DSA digital signature algorithm.
* Elliptic curves:: Elliptic curves and ECDSA
@end menu
@node RSA, DSA, Publickey algorithms, Publickey algorithms
...
...
@@ 2507,14 +2520,14 @@ It's remarkably simple to describe the trapdoor function behind
F(x) = x
^
e mod n
@end example
I.e. raise x to the @code
{
e
}
:
th power, while discarding all multiples of
I.e. raise x to the @code
{
e
}
'
th power, while discarding all multiples of
@code
{
n
}
. The pair of numbers @code
{
n
}
and @code
{
e
}
is the public key.
@code
{
e
}
can be quite small, even @code
{
e = 3
}
has been used, although
slightly larger numbers are recommended. @code
{
n
}
should be about 1000
bits or larger.
If @code
{
n
}
is large enough, and properly chosen, the inverse of F,
the computation of @code
{
e
}
:
th roots modulo @code
{
n
}
, is very difficult.
the computation of @code
{
e
}
'
th roots modulo @code
{
n
}
, is very difficult.
But, where's the trapdoor?
Let's first look at how @acronym
{
RSA
}
keypairs are generated. First
...
...
@@ 2703,7 +2716,7 @@ example if if @var{n_size} is too small, or if @var{e_size} is zero and
@code
{
pub>e
}
is an even number.
@end deftypefun
@node DSA,
, RSA, Publickey algorithms
@node DSA,
Elliptic curves
, RSA, Publickey algorithms
@comment nodename, next, previous, up
@subsection @acronym
{
DSA
}
...
...
@@ 2712,11 +2725,11 @@ The @acronym{DSA} digital signature algorithm is more complex than
published @acronym
{
FIPS
}
186 which is the authoritative specification.
Sometimes @acronym
{
DSA
}
is referred to using the acronym @acronym
{
DSS
}
,
for Digital Signature Standard. The most recent revision of the
specification, FIPS1863, was issue
e
d in 2009, and it adds support for
specification, FIPS1863, was issued in 2009, and it adds support for
larger hash functions than @acronym
{
sha1
}
.
For @acronym
{
DSA
}
, the underlying mathematical problem is the
computation of discre
e
t logarithms. The public key consists of a large
computation of discret
e
logarithms. The public key consists of a large
prime @code
{
p
}
, a small prime @code
{
q
}
which is a factor of @code
{
p1
}
,
a number @code
{
g
}
which generates a subgroup of order @code
{
q
}
modulo
@code
{
p
}
, and an element @code
{
y
}
in that subgroup.
...
...
@@ 2759,7 +2772,7 @@ difficult group structure. One good algorithm is Pollardrho, which has
complexity @code
{
sqrt(q)
}
.
The important point is that security depends on the size of @emph
{
both
}
@code
{
p
}
and @code
{
q
}
, and they should be cho
o
sen so that the difficulty
@code
{
p
}
and @code
{
q
}
, and they should be chosen so that the difficulty
of both discrete logarithm methods are comparable. Today, the security
margin of the original @acronym
{
DSA
}
may be uncomfortably small. Using a
@code
{
p
}
of 1024 bits implies that cracking using the number field sieve
...
...
@@ 2937,7 +2950,7 @@ to @code{p_bits = 1024}. Nonstandard sizes are possible, in particular
can not in general be expected to support such keys. Also note that
using very large @var
{
p
_
bits
}
, with @var
{
q
_
bits
}
fixed at 160, doesn't
make much sense, because the security is also limited by the size of the
smaller prime. Using a larger @code
{
q
_
bits
}
requires switchi
g
n to a
smaller prime. Using a larger @code
{
q
_
bits
}
requires switchin
g
to a
larger hash function. To generate @acronym
{
DSA
}
keys for use with
@acronym
{
SHA256
}
, use @code
{
q
_
bits = 256
}
and, e.g., @code
{
p
_
bits =
2048
}
.
...
...
@@ 2947,7 +2960,159 @@ Returns one on success, and zero on failure. The function will fail if
small.
@end deftypefun
@node Randomness, Ascii encoding, Publickey algorithms, Reference
@node Elliptic curves,, DSA, Publickey algorithms
@comment nodename, next, previous, up
@subsection @acronym
{
Elliptic curves
}
For cryptographic purposes, an elliptic curve is a mathematical group of
points, and computing logarithms in this group is computationally
difficult problem. Nettle uses additive notation for elliptic curve
groups. If @math
{
P
}
and @math
{
Q
}
are two points, and @math
{
k
}
is an
integer, the point sum, @math
{
P + Q
}
, and the multiple @math
{
k P
}
can be
computed efficiently, but given only two points @math
{
P
}
and @math
{
Q
}
,
finding an integer @math
{
k
}
such that @math
{
Q = k P
}
is the elliptic
curve discrete logarithm problem.
Nettle supports standard curves which are all of the form @math
{
y
^
2 =
x
^
3  3 x + b @pmod
{
p
}}
, i.e., the points have coordinates @math
{
(x,y)
}
,
both considered as integers modulo a specified prime @math
{
p
}
. Curves
are represented as a @code
{
struct ecc
_
curve
}
. Supported curves are
declared in @file
{
<nettle/ecccurve.h>
}
, e.g., @code
{
nettle
_
secp
_
256r1
}
for a standardized curve using the 256bit prime @math
{
p = 2
^{
256
}

2
^{
224
}
+ 2
^{
192
}
+ 2
^{
96
}
 1
}
. The contents of these structs is not
visible to nettle users. The ``bitsize of the curve'' is used as a
shorthand for the bitsize of the curve's prime @math
{
p
}
, e.g., 256 bits
for @code
{
nettle
_
secp
_
256r1
}
.
@subsubsection Sidechannel silence
Nettle's implementation of the elliptic curve operations is intended to
be sidechannel silent. The sidechannel attacks considered are:
@itemize
@item Timing attacks
If the timing of operations depends on secret values, an attacker
interacting with your system can measure the response time, and infer
information about your secrets, e.g., a private signature key.
@item Attacks using memory caches
Assume you have some secret data on a multiuser system, and that this
data is properly protected so that other users get no direct access to
it. If you have a process operating on the secret data, and this process
does memory accesses depending on the data, e.g, an internal lookup
table in some cryptographic algorithm, an attacker running a separate
process on the same system may use behavior of internal CPU caches to
get information about your secrets.
@end itemize
Nettle's ECC implementation is designed to be @dfn
{
sidechannel silent
}
,
and not leak any information to these attacks. Timing and memory
accesses depend only on the size of the input data and its location in
memory, not on the actual data bits. This implies a performance penalty
in several of the building blocks.
@subsection ECDSA
ECDSA is a variant of the DSA digital signature scheme (@pxref
{
DSA
}
),
which works over an elliptic curve group rather than over a (subgroup
of) integers modulo @math
{
p
}
. Like DSA, creating a signature requires a unique
random nonce (repeating the nonce with two different messages reveals
the private key, and any leak or bias in the generation of the nonce
also leaks information about the key).
Unlike DSA, signatures are in general not tied to any particular hash
function or even hash size. Any hash function can be used, and the hash
value is truncated or padded as needed to get a size matching the curve
being used. It is recommended to use a strong cryptographic hash
function with digest size close to the bit size of the curve, e.g.,
SHA256 is a reasonable choice when using ECDSA signature over the curve
secp256r1. A protocol or application using ECDSA has to specify which
curve and which hash function to use, or provide some mechanism for
negotiating.
Nettle defines ECDSA in @file
{
<nettle/ecdsa.h>
}
. We first need
to define the data types used to represent public and private keys.
@deftp
{
struct
}
{
struct ecc
_
point
}
Represents a point on an elliptic curve. In particular, it is used to
represent an ECDSA public key.
@end deftp
@deftypefun void ecc
_
point
_
init (struct ecc
_
point *@var
{
p
}
, const structecc
_
curve *@var
{
ecc
}
)
Initializes @var
{
p
}
to represent points on the given curve @var
{
ecc
}
.
Allocates storage for the coordinates, using the same allocation
functions as GMP.
@end deftypefun
@deftypefun void ecc
_
point
_
clear (struct ecc
_
point *@var
{
p
}
)
Deallocate storage.
@end deftypefun
@deftypefun int ecc
_
point
_
set (struct ecc
_
point *@var
{
p
}
, const mpz
_
t @var
{
x
}
, const mpz
_
t @var
{
y
}
)
Check that the given coordinates represent a point on the curve. If so,
the coordinates are copied and converted to internal representation, and
the function returns 1. Otherwise, it returns 0. Currently, the
infinity point (or zero point, with additive notation) i snot allowed.
@end deftypefun
@deftypefun void ecc
_
point
_
get (const struct ecc
_
point *@var
{
p
}
, mpz
_
t @var
{
x
}
, mpz
_
t @var
{
y
}
)
Extracts the coordinate of the point @var
{
p
}
. The output parameters
@var
{
x
}
or @var
{
y
}
may be NULL if the caller doesn't want that
coordinate.
@end deftypefun
@deftp
{
struct
}
{
struct ecc
_
scalar
}
Represents an integer in the range @math
{
0 < x < group order
}
, where the
``group order'' refers to the order of an ECC group. In particular, it
is used to represent an ECDSA private key.
@end deftp
@deftypefun void ecc
_
scalar
_
init (struct ecc
_
scalar *@var
{
s
}
, const struct ecc
_
curve *@var
{
ecc
}
)
Initializes @var
{
s
}
to represent a scalar suitable for the given curve
@var
{
ecc
}
. Allocates storage using the same allocation functions as GMP.
@end deftypefun
@deftypefun void ecc
_
scalar
_
clear (struct ecc
_
scalar *@var
{
s
}
)
Deallocate storage.
@end deftypefun
@deftypefun int ecc
_
scalar
_
set (struct ecc
_
scalar *@var
{
s
}
, const mpz
_
t @var
{
z
}
)
Check that @var
{
z
}
is in the correct range. If so, copies the value to
@var
{
s
}
and returns 1, otherwise returns 0.
@end deftypefun
@deftypefun void ecc
_
scalar
_
get (const struct ecc
_
scalar *@var
{
s
}
, mpz
_
t @var
{
z
}
)
Extracts the scalar, in GMP @code
{
mpz
_
t
}
representation.
@end deftypefun
To create and verify ECDSA signatures, the following functions are used.
@deftypefun void ecdsa
_
sign (const struct ecc
_
scalar *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func *@var
{
random
}
, unsigned @var
{
digest
_
length
}
, const uint8
_
t *@var
{
digest
}
, struct dsa
_
signature *@var
{
signature
}
)
Uses the private key @var
{
key
}
to create a signature on @var
{
digest
}
.
@var
{
random
_
ctx
}
and @var
{
random
}
is a randomness generator.
@code
{
random(random
_
ctx, length, dst)
}
should generate @code
{
length
}
random octets and store them at @code
{
dst
}
. The signature is stored in
@var
{
signature
}
, in the same was as for plain DSA.
@end deftypefun
@deftypefun int ecdsa
_
verify (const struct ecc
_
point *@var
{
pub
}
, unsigned @var
{
length
}
, const uint8
_
t *@var
{
digest
}
, const struct dsa
_
signature *@var
{
signature
}
)
Uses the public key @var
{
pub
}
to verify that @var
{
signature
}
is a valid
signature for the message digest @var
{
digest
}
(of @var
{
length
}
octets).
Returns 1 if the signature is valid, otherwise 0.
@end deftypefun
Finally, to generation of new an ECDSA key pairs
@deftypefun void ecdsa
_
generate
_
keypair (struct ecc
_
point *@var
{
pub
}
, struct ecc
_
scalar *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func *@var
{
random
}
);
@var
{
pub
}
and @var
{
key
}
is where the resulting key pair is stored. The
structs should be initialized, for the desired ECC curve, before you call this function.
@var
{
random
_
ctx
}
and @var
{
random
}
is a randomness generator.
@code
{
random(random
_
ctx, length, dst)
}
should generate @code
{
length
}
random octets and store them at @code
{
dst
}
. For advice, see
@xref
{
Randomness
}
.
@end deftypefun
@node Randomness, ASCII encoding, Publickey algorithms, Reference
@comment nodename, next, previous, up
@section Randomness
...
...
@@ 3184,7 +3349,7 @@ Information about a single source.
@end deftp
@defvr Constant YARROW256
_
SEED
_
FILE
_
SIZE
Recomm
a
nded size of the Yarrow256 seed file.
Recomm
e
nded size of the Yarrow256 seed file.
@end defvr
@deftypefun void yarrow256
_
init (struct yarrow256
_
ctx *@var
{
ctx
}
, unsigned @var
{
nsources
}
, struct yarrow
_
source *@var
{
sources
}
)
...
...
@@ 3268,9 +3433,9 @@ Returns an entropy estimate, in bits, suitable for calling
@code
{
yarrow256
_
update
}
. Usually, 0, 1 or 2 bits.
@end deftypefun
@node A
scii
encoding, Miscellaneous functions, Randomness, Reference
@node A
SCII
encoding, Miscellaneous functions, Randomness, Reference
@comment nodename, next, previous, up
@section A
scii
encoding
@section A
SCII
encoding
Encryption will transform your data from text into binary format, and that
may be a problem if you want, for example, to send the data as if it was
...
...
@@ 3420,7 +3585,7 @@ hexadecimal digits have been seen). Returns 1 on success, and 0 on
error.
@end deftypefun
@node Miscellaneous functions, Compatibility functions, A
scii
encoding, Reference
@node Miscellaneous functions, Compatibility functions, A
SCII
encoding, Reference
@comment nodename, next, previous, up
@section Miscellaneous functions
...
...
@@ 3581,4 +3746,11 @@ End:
@c LocalWords: DSA gmp FIPS DSS libdes OpenSSL ARCTWO Josefsson Nikos Andreas
@c LocalWords: Mavroyanopoulos Sigfridsson Comstedt interoperability Sparc IC
@c LocalWords: DES FIXME Rivest's plaintext ciphertext CTR XORed timestamp
@c LocalWords: XORs cryptologists
@c LocalWords: XORs cryptologists libnettle libhogweed GCM ECDSA NTT
@c LocalWords: toolkits BLOWFISH Möller RIPEMD libgcrypt PBKDF Shishi
@c LocalWords: GnuTLS Gutmann's GOSTHASH GOST Aleksey Kravchenko ECC
@c LocalWords: rhash Mavrogiannopoulos Internetfonden Keccak Bertoni
@c LocalWords: Michaël Peeters Assche Dobbertin Antoon Bosselaers KDF
@c LocalWords: Preneel rôle McGrew Viega KDFs PBKDFs passphrase PRF
@c LocalWords: th deallocate pre bitsize multi lookup secp startup
@c LocalWords: typedef typedef
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment