Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
N
nettle
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Labels
Merge Requests
5
Merge Requests
5
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Commits
Open sidebar
Nettle
nettle
Commits
4a69d892
Commit
4a69d892
authored
May 04, 2014
by
Niels Möller
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Document new DSA interface.
parent
00c5dcca
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
118 additions
and
35 deletions
+118
-35
ChangeLog
ChangeLog
+4
-0
nettle.texinfo
nettle.texinfo
+114
-35
No files found.
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
