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
4a69d892
Commit
4a69d892
authored
May 04, 2014
by
Niels Möller
Browse files
Document new DSA interface.
parent
00c5dcca
Changes
2
Hide whitespace changes
Inline
Side-by-side
ChangeLog
View file @
4a69d892
2014-05-04 Niels Möller <nisse@lysator.liu.se>
* nettle.texinfo (DSA): Document new DSA interface.
2014-05-03 Niels Möller <nisse@lysator.liu.se>
* configure.ac: Check for SIZEOF_SIZE_T.
...
...
nettle.texinfo
View file @
4a69d892
...
...
@@ -3607,11 +3607,117 @@ key.
Like for @acronym
{
RSA
}
, Nettle represents @acronym
{
DSA
}
keys using two
structures, containing values of type @code
{
mpz
_
t
}
. For information on
how to customize allocation, see @xref
{
Custom Allocation,,GMP
Allocation,gmp, GMP Manual
}
.
Allocation,gmp, GMP Manual
}
. Nettle's @acronym
{
DSA
}
interface is defined
in @file
{
<nettle/dsa.h>
}
.
Most of the @acronym
{
DSA
}
functions are very similar to the
corresponding @acronym
{
RSA
}
functions, but there are a few differences
pointed out below. For a start, there are no functions corresponding to
A @acronym
{
DSA
}
group is represented using the following struct.
@deftp
{
Context struct
}
{
dsa
_
params
}
p q g
Parameters of the @acronym
{
DSA
}
group.
@end deftp
@deftypefun void dsa
_
params
_
init (struct dsa
_
params *@var
{
params
}
)
Calls @code
{
mpz
_
init
}
on all numbers in the struct.
@end deftypefun
@deftypefun void dsa
_
params
_
clear (struct dsa
_
params *@var
{
params
}
params)
Calls @code
{
mpz
_
clear
}
on all numbers in the struct.
@end deftypefun
@deftypefun int dsa
_
generate
_
params (struct dsa
_
params *@var
{
params
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func *@var
{
random
}
, void *@var
{
progress
_
ctx
}
, nettle
_
progress
_
func *@var
{
progress
}
, unsigned @var
{
p
_
bits
}
, unsigned @var
{
q
_
bits
}
)
Generates paramaters of a new group. The @var
{
params
}
struct should be
initialized 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
}
.
@var
{
progress
}
and @var
{
progress
_
ctx
}
can be used to get callbacks
during the key generation process, in order to uphold an illusion of
progress. @var
{
progress
}
can be NULL, in that case there are no
callbacks.
@var
{
p
_
bits
}
and @var
{
q
_
bits
}
are the desired sizes of @code
{
p
}
and
@code
{
q
}
. To generate keys that conform to the original @acronym
{
DSA
}
standard, you must use @code
{
q
_
bits = 160
}
and select @var
{
p
_
bits
}
of
the form @code
{
p
_
bits = 512 + l*64
}
, for @code
{
0 <= l <= 8
}
, where the
smaller sizes are no longer recommended, so you should most likely stick
to @code
{
p
_
bits = 1024
}
. Non-standard sizes are possible, in particular
@code
{
p
_
bits
}
larger than 1024, although @acronym
{
DSA
}
implementations
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. To generate @acronym
{
DSA
}
keys for use with
@acronym
{
SHA256
}
, use @code
{
q
_
bits = 256
}
and, e.g., @code
{
p
_
bits =
2048
}
.
Returns one on success, and zero on failure. The function will fail if
@var
{
q
_
bits
}
is too small, or too close to @var
{
p
_
bits
}
.
@end deftypefun
Signatures are represented using the structure below.
@deftp
{
Context struct
}
{
dsa
_
signature
}
r s
@end deftp
@deftypefun void dsa
_
signature
_
init (struct dsa
_
signature *@var
{
signature
}
)
@deftypefunx void dsa
_
signature
_
clear (struct dsa
_
signature *@var
{
signature
}
)
You must call @code
{
dsa
_
signature
_
init
}
before creating or using a
signature, and call @code
{
dsa
_
signature
_
clear
}
when you are finished
with it.
@end deftypefun
Keys are represented as bignums, of type @code
{
mpz
_
t
}
. A public keys
represent a group element, and is of the same size as @code
{
p
}
, while a
private key is an exponent, of the same size as @code
{
q
}
.
@deftypefun int dsa
_
sign (const struct dsa
_
params *@var
{
params
}
, const mpz
_
t @var
{
x
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func *@var
{
random
}
, size
_
t @var
{
digest
_
size
}
, const uint8
_
t *@var
{
digest
}
, struct dsa
_
signature *@var
{
signature
}
)
Creates a signature from the given hash digest, using the private key
@var
{
x
}
. @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
}
. Returns one on success, or zero on failure. Signing
can fail only if the key is invalid, so that inversion modulo @code
{
q
}
fails.
@end deftypefun
@deftypefun int dsa
_
verify (const struct dsa
_
params *@var
{
params
}
, const mpz
_
t @var
{
y
}
, size
_
t @var
{
digest
_
size
}
, const uint8
_
t *@var
{
digest
}
, const struct dsa
_
signature *@var
{
signature
}
)
Verifies a signature, using the public key y. Returns 1 if the signature
is valid, otherwise 0.
@end deftypefun
To generate a keypair, first generate a @acronym
{
DSA
}
group using
@code
{
dsa
_
generate
_
params
}
. A keypair in this group is then created
using
@deftypefun void dsa
_
generate
_
keypair (const struct dsa
_
params *@var
{
params
}
, mpz
_
t @var
{
pub
}
, mpz
_
t @var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func *@var
{
random
}
)
Generates a new keypair, using the group @var
{
params
}
. The public key is
stored in @var
{
pub
}
, and the private key in @var
{
key
}
. Both variables
must be initialized using @code
{
mpz
_
init
}
before this call.
@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
@subsection Old, deprecated, @acronym
{
DSA
}
interface
Versions before nettle-3.0 used a different interface for @acronym
{
DSA
}
signatures, where the group parameters and the public key was packed
together as @code
{
struct dsa
_
public
_
key
}
. Most of this interface is kept
for backwards compatibility, and declared in @file
{
nettle/dsa-compat.h
}
.
Below is the old documentation. The old and new interface use distinct
names and don't confict, with one exception: The key generation
function. The @file
{
nettle/dsa-compat.h
}
redefines
@code
{
dsa
_
generate
_
keypair
}
as an alias for
@code
{
dsa
_
compat
_
generate
_
keypair
}
, compatible with the old interface
and documented below.
The old @acronym
{
DSA
}
functions are very similar to the corresponding
@acronym
{
RSA
}
functions, but there are a few differences pointed out
below. For a start, there are no functions corresponding to
@code
{
rsa
_
public
_
key
_
prepare
}
and @code
{
rsa
_
private
_
key
_
prepare
}
.
@deftp
{
Context struct
}
{
dsa
_
public
_
key
}
p q g y
...
...
@@ -3637,18 +3743,8 @@ deallocated by calling one of
Calls @code
{
mpz
_
clear
}
on all numbers in the key struct.
@end deftypefun
Signatures are represented using the structure below, and need to be
initialized and cleared in the same way as the key structs.
@deftp
{
Context struct
}
{
dsa
_
signature
}
r s
@end deftp
@deftypefun void dsa
_
signature
_
init (struct dsa
_
signature *@var
{
signature
}
)
@deftypefunx void dsa
_
signature
_
clear (struct dsa
_
signature *@var
{
signature
}
)
You must call @code
{
dsa
_
signature
_
init
}
before creating or using a
signature, and call @code
{
dsa
_
signature
_
clear
}
when you are finished
with it.
@end deftypefun
Signatures are represented using @code
{
struct dsa
_
signature
}
, described
earlier.
For signing, you need to provide both the public and the private key
(unlike @acronym
{
RSA
}
, where the private key struct includes all
...
...
@@ -3658,7 +3754,6 @@ function, although the implementation of @acronym{DSA} with
@acronym
{
SHA256
}
should be considered somewhat experimental due to lack
of official test vectors and interoperability testing.
@c FIXME: Update for new DSA interface
@deftypefun int dsa
_
sha1
_
sign (const struct dsa
_
public
_
key *@var
{
pub
}
, const struct dsa
_
private
_
key *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func @var
{
random
}
, struct sha1
_
ctx *@var
{
hash
}
, struct dsa
_
signature *@var
{
signature
}
)
@deftypefunx int dsa
_
sha1
_
sign
_
digest (const struct dsa
_
public
_
key *@var
{
pub
}
, const struct dsa
_
private
_
key *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func @var
{
random
}
, const uint8
_
t *@var
{
digest
}
, struct dsa
_
signature *@var
{
signature
}
)
@deftypefunx int dsa
_
sha256
_
sign (const struct dsa
_
public
_
key *@var
{
pub
}
, const struct dsa
_
private
_
key *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func @var
{
random
}
, struct sha256
_
ctx *@var
{
hash
}
, struct dsa
_
signature *@var
{
signature
}
)
...
...
@@ -3684,7 +3779,7 @@ Verifies a signature. Returns 1 if the signature is valid, otherwise 0.
Key generation uses mostly the same parameters as the corresponding
@acronym
{
RSA
}
function.
@deftypefun int dsa
_
generate
_
keypair (struct dsa
_
public
_
key *@var
{
pub
}
, struct dsa
_
private
_
key *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func @var
{
random
}
, void *@var
{
progress
_
ctx
}
, nettle
_
progress
_
func @var
{
progress
}
, unsigned @var
{
p
_
bits
}
, unsigned @var
{
q
_
bits
}
)
@deftypefun int dsa
_
compat
_
generate
_
keypair (struct dsa
_
public
_
key *@var
{
pub
}
, struct dsa
_
private
_
key *@var
{
key
}
, void *@var
{
random
_
ctx
}
, nettle
_
random
_
func @var
{
random
}
, void *@var
{
progress
_
ctx
}
, nettle
_
progress
_
func @var
{
progress
}
, unsigned @var
{
p
_
bits
}
, unsigned @var
{
q
_
bits
}
)
@var
{
pub
}
and @var
{
key
}
is where the resulting key pair is stored. The
structs should be initialized before you call this function.
...
...
@@ -3699,23 +3794,7 @@ progress. @var{progress} can be NULL, in that case there are no
callbacks.
@var
{
p
_
bits
}
and @var
{
q
_
bits
}
are the desired sizes of @code
{
p
}
and
@code
{
q
}
. To generate keys that conform to the original @acronym
{
DSA
}
standard, you must use @code
{
q
_
bits = 160
}
and select @var
{
p
_
bits
}
of
the form @code
{
p
_
bits = 512 + l*64
}
, for @code
{
0 <= l <= 8
}
, where the
smaller sizes are no longer recommended, so you should most likely stick
to @code
{
p
_
bits = 1024
}
. Non-standard sizes are possible, in particular
@code
{
p
_
bits
}
larger than 1024, although @acronym
{
DSA
}
implementations
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 switching 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
}
.
Returns one on success, and zero on failure. The function will fail if
@var
{
q
_
bits
}
is neither 160 nor 256, or if @var
{
p
_
bits
}
is unreasonably
small.
@code
{
q
}
. See @code
{
dsa
_
generate
_
keypair
}
for details.
@end deftypefun
@node Elliptic curves,, DSA, Public-key algorithms
...
...
Write
Preview
Markdown
is supported
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