SYNOPSIS

 #include <openssl/asn1.h>

 ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
 ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);

DESCRIPTION

Ces fonctions génèrent l'encodage ASN1 d'une chaîne dans une structure ASN1_TYPE.

str contient la chaîne à encoder. nconf ou cnf contiennent les renseignements facultatifs de configuration dans lesquelles d'autres chaînes seront lues. nconf proviendra typiquement d'un fichier de configuration tandis que cnf est obtenu dans une structure X509V3_CTX qui sera typiquement utilisée par les fonctions d'extension de certificats X509 v3. cnf ou nconf peuvent valoir NULL si aucune configuration supplémentaire n'est utilisée.

FORMAT DES CHAÎNES DE GÉNÉRATION

Les données effectivement encodées sont déterminées par la chaîne str et les informations de configuration. Le format général de la chaîne est :

[modificateur,]type[:valeur]

C'est-à-dire zéro modificateur ou plus, séparés par des virgules, suivis d'un type, lui-même suivi de façon facultative par un deux-points et une valeur. Les formats de type, valeur et modificateur sont décrits ci-dessous.

TYPES PRIS EN CHARGE

Les types pris en charge sont décrits ci-dessous. À moins que ce ne soit indiqué explicitement, seul le format ASCII est autorisé.

BOOLEAN, BOOL

Encoder un type booléen. La chaîne valeur est obligatoire et devrait valoir soit TRUE, soit FALSE. Les valeurs TRUE, true, Y, y, YES, yes, FALSE, false, N, n, NO et no sont acceptées.

NULL

Encoder le type NULL, la chaîne valeur ne doit pas être présente.

INTEGER, INT

Encoder un type ASN1 INTEGER. La chaîne valeur représente la valeur de l'entier. Elle peut être précédée d'un signe moins et est normalement interprétée comme une valeur décimale à moins que le préfixe 0x soit inclus.

ENUMERATED, ENUM

Encoder un type ASN1 ENUMERATED, par ailleurs identique à INTEGER.

OBJECT, OID

Encoder un type ASN1 OBJECT IDENTIFIER, la chaîne valeur peut être un nom court, un nom long ou un format numérique.

UTCTIME, UTC

Encoder une structure ASN1 UTCTime. La valeur doit être au format AAMMDDHHMMSSZ.

GENERALIZEDTIME, GENTIME

Encoder une structure ASN1 GeneralizedTime. La valeur doit être au format AAAAMMDDHHMMSSZ.

OCTETSTRING, OCT

Encoder un type ASN1 OCTET STRING. La valeur représente le contenu de cette structure. Les chaînes de format ASCII et HEX peuvent être utilisées pour indiquer le format de valeur.

BITSTRING, BITSTR

Encoder un type ASN1 BIT STRING. La valeur représente le contenu de cette structure. Les chaînes de format ASCII, HEX et BITLIST peuvent être utilisées pour indiquer le format de valeur.

Si le format diffère de BITLIST, le nombre de bits non utilisés est mis à zéro.

UNIVERSALSTRING, UNIV, IA5, IA5STRING, UTF8, UTF8String, BMP, BMPSTRING, VISIBLESTRING, VISIBLE, PRINTABLESTRING, PRINTABLE, T61, T61STRING, TELETEXSTRING, GeneralString, NUMERICSTRING, NUMERIC

Encoder les types de chaîne correspondant. La valeur représente le contenu de cette structure. Le format peut être ASCII ou UTF8.

SEQUENCE, SEQ, SET

Formater le résultat en tant que type ASN1 SEQUENCE ou SET. La valeur devrait être un nom de section qui contiendra le contenu. Les noms des champs de la section sont ignorés et les valeurs sont au format de la chaîne créée. Si valeur est absent, alors une SEQUENCE vide sera encodée.

MODIFICATEURS

Les modificateurs affectent les structures suivantes. Ils peuvent être utilisés pour ajouter des étiquettes EXPLICIT ou IMPLICIT, ajouter des enveloppes ou changer le format de chaîne du type et de la valeur finale. Les formats pris en charge sont documentés ci-dessous.

EXPLICIT, EXP

Ajouter une étiquette explicite à la structure suivante. Cette chaîne devrait être suivie par un deux-points et la valeur de l'étiquette à utiliser sous forme numérique décimale.

En faisant suivre le nombre d'un U, A, P ou C, une étiquette de type UNIVERSAL, APPLICATION, PRIVATE ou CONTEXT SPECIFIC peut être utilisée (CONTEXT SPECIFIC par défaut).

IMPLICIT, IMP

Identique à EXPLICIT sauf qu'un étiquetage IMPLICIT est utilisé à la place.

OCTWRAP, SEQWRAP, SETWRAP, BITWRAP

La structure suivante est entourée par une OCTET STRING, une SEQUENCE, un SET ou une BIT STRING respectivement. Pour une BIT STRING, le nombre de bits non utilisés est mis à zéro.

FORMAT

Indique le format de la valeur finale. Il devrait être suivi par un deux-points et une des chaînes ASCII, UTF8, HEX ou BITLIST.

Si aucune chaîne de format n'est incluse, ASCII est utilisée. Si UTF8 est indiquée, alors la chaîne valeur doit être une chaîne UTF8 correcte. Pour le format HEX, la sortie doit être un ensemble de chiffres hexadécimaux. BITLIST (qui n'est correct que pour une BIT STRING) est la liste des index des bits positionnés séparés par des virgules, tous les autres bits valent zéro.

EXEMPLES

Une IA5String simple :

 IA5STRING:Salut le monde

Une IA5String étiquetée explicitement :

 EXPLICIT:0,IA5STRING:Salut le monde

Une IA5String étiquetée explicitement et utilisant une étiquette APPLICATION :

 EXPLICIT:0A,IA5STRING:Salut le monde

Une BITSTRING avec les bits 1 et 5 activés et tous les autres à zéro :

 FORMAT:BITLIST,BITSTRING:1,5

Un exemple plus complexe utilisant un fichier de configuration pour produire une SEQUENCE constituée d'un BOOL, d'un OID et d'une UTF8String :

 asn1 = SEQUENCE:seq_section
 [seq_section]
 field1 = BOOLEAN:TRUE
 field2 = OID:commonName
 field3 = UTF8:Troisième champ

Cet exemple produit une structure RSAPrivateKey. Il s'agit de la clef contenue dans le fichier client.pem de toute distribution OpenSSL (remarque : les noms des champs comme « coeff » sont ignorés et ne sont présents que par souci de clarté.

 asn1=SEQUENCE:private_key
 [private_key]
 version=INTEGER:0
 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 e=INTEGER:0x010001
 d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
 F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
 p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
 D4BD57
 q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
 46EC4F
 exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
 9C0A39B9
 exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
 E7B2458F
 coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
 628657053A

Cet exemple est la clef publique correspondante dans une structure SubjectPublicKeyInfo :

 # Commencer par une SEQUENCE
 asn1=SEQUENCE:pubkeyinfo
 # pubkeyinfo contient un identificateur d'algorithme et la clef publique
 # enveloppés dans une BIT STRING
 [pubkeyinfo]
 algorithm=SEQUENCE:rsa_alg
 pubkey=BITWRAP,SEQUENCE:rsapubkey
 # l'identifiant d'algorithme pour RSA est un simple OID et un NULL
 [rsa_alg]
 algorithm=OID:rsaEncryption
 parameter=NULL
 # Véritable clef publique : module et exposant
 [rsapubkey]
 n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
 D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 e=INTEGER:0x010001

VALEURS DE RETOUR

ASN1_generate_nconf() et ASN1_generate_v3() renvoient les données encodées sous la forme d'une structure ASN1_TYPE ou NULL si une erreur est survenue.

Les codes d'erreur peuvent être obtenus avec ERR_get_error(3).

HISTORIQUE

ASN1_generate_nconf() et ASN1_generate_v3() ont été ajoutées dans la version 0.9.8 d'OpenSSL.

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.