Požadavek encrypt

Slouží pro zašifrování předaných dat.

Požadavek provede zašifrování vstupních dat zvolenou šifrou. Jedná se o symetrické šifrování, takže parametry musí být na obou stranách stejné.

<request>
<encrypt
cipher="3des-cbc|3des-cbc_np|..."
key="{string}"
key-prep="true|false"
key-format="base64|plain|unicode|hex|url"
init-format="plain|base64|unicode|hex|url"
data="{string}"
init="{string}"
hash="sha|sha256|sha384|sha512|md5|cr32|crc64"
iter="{number}"
input="base64|plain|unicode|hex|url"
output="plain|base64|unicode|hex|url"
/>
</request>

Atributy

cipher - Použitá šifrovací metoda - dále viz. tabulka šifer.(typ: string) TYP HODNOTY: string; (možnosti obsahu: 3des-cbc | 3des-cbc_np | ...)

key - Šifrovací klíč - heslo.(typ: string) TYP HODNOTY: string;

key-prep - Určuje, zda bude klíč použit jak je, nebo bude operace provedena hashem klíče, výchozí hodnou je false.(typ: boolean) TYP HODNOTY: boolean; (možnosti obsahu: true | false)

key-format - Určuje, v jakém formátu byl dodán klíč, výchozí hodnotou je plain.(typ: string) TYP HODNOTY: string; (možnosti obsahu: base64 | plain | unicode | hex | url)

init-format - Určuje, v jakém formátu je dodán inicializační vector, výchozí hodnotou je plain (což není příliš bezpečné)(typ: string) TYP HODNOTY: string; (možnosti obsahu: plain | base64 | unicode | hex | url)

data - Šifrovaná data.(typ: string) TYP HODNOTY: string;

init - Inicializace dat.(typ: string) TYP HODNOTY: string;

hash - Je-li klíč před použitím hashován, určuje, jaký hash bude použit, výchozí hodnotou je SHA256(typ: number) TYP HODNOTY: number; (možnosti obsahu: sha | sha256 | sha384 | sha512 | md5 | cr32 | crc64)

iter - Počet iterací prováděných při přípravě klíče, výchozí hodnotou je 3.(typ: number) TYP HODNOTY: number;

input - Určuje, v jakém formátu jsou dodána data pro provedení požadavku, výchozí hodnotou je plain.(typ: string) TYP HODNOTY: string; (možnosti obsahu: base64 | plain | unicode | hex | url)

output - Určuje, v jakém formátu bude poskytnut výstup, umožňuje zadat několik po sobě jdoucích konverzí formátu, výchozí hodnotou je base64.(typ: string) TYP HODNOTY: string; (možnosti obsahu: plain | base64 | unicode | hex | url)

Potomci

Požadavek encrypt neobsahuje žádné další elementy, ani žádné jiné číselné či řetězcové hodnoty.

Poznámka k request

Typ formátu unicode:

Hodnota unicode v atributech key-format, init-format, input a output má vliv na to, jestli se na vstupu s řetězcem pracuje jako s UTF-8, nebo UTF-16. Jeho změna nepovede k chybné unicode interpretaci textu, ale povede k vytvoření jiného výstupu. Opět platí, že na obou stranách musí být použit stejný způsob práce s řetězcem. A to je význam této volby. Zajistit, aby obě strany pracovaly s textem stejně.

Varianta NO PADDING:

U všech šifer je možné zvolit doplněk názvu "_np". Tento doplněk provede šifrování variantou NO PADDING. I tato hodnota musí být na obou stranách stejná.

Výstupní formát:

Požadavek umožňuje provést několik po sobě jdoucích konverzí výstupu, lze si tak připravit výstup přímo pro svou potřebu. Nastavením atributu output na hodnotu "base64 url" například dojde k převodu výstupu do base64 a následné úpravy do URL kódování.

Odpověď

Struktura odpovědi na požadavek encrypt vrácená v obálce response:

<response>
<encrypt
type="ok|error"
>
<value ... {string}</value> ?
</encrypt>
</response>

Atributy

type - popis neuveden(typ: string) TYP HODNOTY: string; (možnosti obsahu: ok | error)

Potomci

<value>
 {string} 
</value>

Výraz pro identifikaci chyb v odpovědi serveru: encrypt[@type='error'] (odkaz na popis detailu: @detail).

Poznámka k response

Inicializační vektor:

Jedná se o inicializaci většiny šifrovacích algoritmů. Jeho velikost a pravidla jeho tvorby jsou závislé na použité šifře. Musí být na obou stranách stejný a většinou se nejedná o tajnou informaci. Vhodné způsoby tvorby a velikost inicializačních vektorů naleznete v dokumentaci ke zvolené šifře. V mnoha případech lze použít pseudonáhodná data, jelikož úkolem vektoru je především zvýšit míru entropie v přenášené zprávě. U některých šifer je vhodné tvořit vektor vzhledem k přenášené zprávě, jiný pro textová data, jiný pro obrázky a podobně. Stejně platí, že pro určitou zprávu (text, obrázek, ...) je vhodnější určitá šifra, či přesněji její modifikace.

Příprava klíče:

Je obvyklé, že se nešifruje přímo "heslem", ale jeho, dle pravidel, vypočítaným hashem. Jelikož výsledkem hash je větší spektrum znaků, než uživatel běžně používá při tvorbě hesla, navíc se jedná o entropičtější data, je tento klíč mnohem bezpečnější pro šifrování. Většina aplikací provádí tuto operaci standardně, bez vědomí uživatele, je proto třeba s tím počítat. V případě, že se šifrování nedaří, je vhodné vyzkoušet, zda protistrana nepoužívá právě tuto úpravu klíče. V případě nezadaní atributů hash a iter, se použije kombinace SHA256 a 3 iterací, což je nejobvyklejší způsob přípravy klíče.

Podporované šifry:

Požadavek podporuje kompletní seznam symetrických šifer a jejich variant podporovany knihovnou OpenSLL. Pro bližší informace spusťte openssl help. Níže jsou uvedeny šifry podporované v době vzniku dokementace, pro aktuální informace navštivte dokumentaci OpenSSL.