ecdsa(3) Algorithme de signature numérique utilisant les courbes elliptiques

SYNOPSIS

#include <openssl/ecdsa.h>

ECDSA_SIG*    ECDSA_SIG_new(void);

 void           ECDSA_SIG_free(ECDSA_SIG *sig);

 int            i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);

 ECDSA_SIG*     d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,

                long len);

ECDSA_SIG*    ECDSA_do_sign(const unsigned char *dgst, int dgst_len,

                        EC_KEY *eckey);

 ECDSA_SIG*     ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,

                        const BIGNUM *kinv, const BIGNUM *rp,

                        EC_KEY *eckey);

 int            ECDSA_do_verify(const unsigned char *dgst, int dgst_len,

                        const ECDSA_SIG *sigEC_KEY *eckey);

 int            ECDSA_sign_setup(EC_KEY *eckeyBN_CTX *ctx,

                        BIGNUM **kinvBIGNUM **rp);

 int            ECDSA_sign(int type, const unsigned char *dgst,

                        int dgstlen, unsigned char *sig,

                        unsigned int *siglenEC_KEY *eckey);

 int            ECDSA_sign_ex(int type, const unsigned char *dgst,

                        int dgstlen, unsigned char *sig,

                        unsigned int *siglen, const BIGNUM *kinv,

                        const BIGNUM *rpEC_KEY *eckey);

 int            ECDSA_verify(int type, const unsigned char *dgst,

                        int dgstlen, const unsigned char *sig,

                        int siglenEC_KEY *eckey);

 int            ECDSA_size(const EC_KEY *eckey);

const ECDSA_METHOD*   ECDSA_OpenSSL(void);

 void           ECDSA_set_default_method(const ECDSA_METHOD *meth);

 const ECDSA_METHOD*    ECDSA_get_default_method(void);

 int            ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);

int           ECDSA_get_ex_new_index(long argl, void *argp,

                        CRYPTO_EX_new *new_func,

                        CRYPTO_EX_dup *dup_func,

                        CRYPTO_EX_free *free_func);

 int            ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);

 void*          ECDSA_get_ex_data(EC_KEY *d, int idx);

DESCRIPTION

La structure ECDSA_SIG est constituée de deux BIGNUM pour les valeurs r et s d’une signature ECDSA (consultez X9.62 ou FIPS 186-2).

 struct
        {
        BIGNUM *r;
        BIGNUM *s;
 } ECDSA_SIG;

ECDSA_SIG_new() alloue une nouvelle structure ECDSA_SIG (remarque : cette fonction alloue aussi les BIGNUM) et l’initialise.

ECDSA_SIG_free() libère la structure ECDSA_SIG sig.

i2d_ECDSA_SIG() crée l’encodage DER de la signature ECDSA sig et écrit la signature encodée dans *pp (remarque : si pp est NULL, i2d_ECDSA_SIG renvoie la taille attendue en octet de la signature encodée DER (ou 0 en cas d’erreur).

d2i_ECDSA_SIG() décode une signature ECDSA encodée DER et renvoie la signature décodée dans une structure ECDSA_SIG nouvellement allouée. *sig pointe vers le tampon contenant la signature encodée DER de taille len.

ECDSA_size() renvoie la taille maximale d’une signature ECDSA encodée DER créée avec la clef privée eckey.

ECDSA_sign_setup() pourrait être utilisée pour précalculer des parties de l’opération de signature. eckey est la clef privée EC et ctx est un pointeur vers la structure BN_CTX (ou NULL). Les valeurs précalculées ou renvoyées dans kinv et rp peuvent être utilisées dans un appel suivant de ECDSA_sign_ex ou ECDSA_do_sign_ex.

ECDSA_sign() est une fonction enveloppe pour ECDSA_sign_ex avec kinv et rp définies à NULL.

ECDSA_sign_ex() calcule une signature numérique de la valeur de hachage dgst, de dgstlen octets, en utilisant la clef privée EC eckey et les valeurs précalculées facultatives kinv et rp. La signature encodée DER est stockée dans sig et sa taille est renvoyée dans sig_len. Remarque : sig doit pointer vers ECDSA_size octets de mémoire. Le paramètre type est ignoré.

ECDSA_verify() vérifie que la signature dans sig de taille siglen est une signature ECDSA valable de la valeur de hachage dgst de taille dgstlen en utilisant la clef publique eckey. Le paramètre type est ignoré.

ECDSA_do_sign() est une fonction enveloppe pour ECDSA_do_sign_ex avec kinv et rp définies à NULL.

ECDSA_do_sign_ex() calcule une signature numérique de la valeur de hachage dgst, de dgstlen octets, en utilisant la clef privée eckey et les valeurs précalculées facultatives kinv et rp. La signature est renvoyée dans une structure ECDSA_SIG nouvellement allouée (ou NULL en cas d’erreur).

ECDSA_do_verify() vérifie que la signature sig est une signature ECDSA valable de la valeur de hachage dgst de taille dgst_len en utilisant la clef publique eckey.

VALEURS DE RETOUR

ECDSA_size() renvoie la taille maximale de signature ou 0 en cas d’erreur.

ECDSA_sign_setup() et ECDSA_sign() renvoient 1 en cas de réussite ou 0 en cas d’erreur.

ECDSA_verify() et ECDSA_do_verify() renvoient 1 pour une signature valable, 0 pour une signature incorrecte ou -1 en cas d’erreur. Les codes d’erreur peuvent être obtenus par ERR_get_error(3).

EXEMPLES

Création d’une signature ECDSA d’une valeur de hachage SHA-1 donnée en utilisant la courbe secp192k1 donnée.

Première étape : créer un objet EC_KEY (remarque : cette partie n’est pas spécifique à ECDSA)

 int        ret;
 ECDSA_SIG *sig;
 EC_KEY    *eckey;
 eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
 if (eckey == NULL)
        {
        /* erreur */
        }
 if (!EC_KEY_generate_key(eckey))
        {
        /* erreur */
        }

Deuxième étape : calculer la signature ECDSA d’une valeur de hachage SHA-1 en utilisant ECDSA_do_sign

 sig = ECDSA_do_sign(digest, 20, eckey);
 if (sig == NULL)
        {
        /* erreur */
        }

ou en utilisant ECDSA_sign

 unsigned char *buffer, *pp;
 int            buf_len;
 buf_len = ECDSA_size(eckey);
 buffer  = OPENSSL_malloc(buf_len);
 pp = buffer;
 if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey);
        {
        /* erreur */
        }

Troisième étape : vérifier la signature ECDSA créée en utilisant ECDSA_do_verify

 ret = ECDSA_do_verify(digest, 20, sig, eckey);

ou en utilisant ECDSA_verify

 ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);

et enfin évaluer la valeur de retour :

 if (ret == -1)
        {
        /* erreur */
        }
 else if (ret == 0)
        {
        /* signature incorrecte */
        }
 else   /* ret == 1 */
        {
        /* signature correcte*/
        }

CONFORMITÉ À

ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 (Digital Signature Standard, DSS)

HISTORIQUE

L’implémentation ecdsa a été introduite pour la première fois dans OpenSSL 0.9.8

AUTEUR

Nils Larsch pour le projet OpenSSL (http://www.openssl.org).

TRADUCTION

La traduction de cette page de manuel est maintenue par les membres de la liste <debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le paquet manpages-fr-extra.